Managing Integrations
Overview and Usage
The Integrations page in the PTC Admin Center displays the client configuration information to the customer administrators and operators who can use this information to create a trust relationship between their third-party applications and PTC products, such as Windchill+.
Client integrations are used to provide delegated authorization from one system to another on behalf of a user. These integrations allow a user to give access to PTC systems in third-party applications, such as web applications or native code applications. These are often ERP systems that monitor or consume data from PTC products.
Integration clients are registered with PTC identity services to retrieve an authorization token on behalf of a user. This token can then be used by the third-party application to request access to the PTC resource that is required by the third-party application.
 |
Currently, to view the Integrations page and use this feature, your organization must have Windchill+ access. PTC provides a client for all Windchill+ organizations as part of Windchill+ provisioning.
|
PTC supports the creation of confidential applications (applications that can hold credentials securely without exposing them to unauthorized parties) to provide integration with third-party systems.
The Integrations page enables an Organization Administrator to manage client integrations for their organization. From this page you can:
• Manage client integrations
• Access all required client credentials
• Set up client integrations with your external third-party applications by providing the client credentials
Before You Begin
• You must be an administrator in your organization to view or manage client integrations.
• Review the security best practices for handling integration credentials securely.
Client Integration Properties
The following information is provided to set up a client integration:
• Client ID—An application’s unique identifier that is used for configuring authentication with PTC. Your application uses it while requesting an OAuth 2.0 access token.
• Secret Key—A string that signs and validates ID Tokes for authentication and provides access to specific PTC endpoints. The key exists by default and requires rotations to view it.
• Callback URL—A redirect URL allowed for user authentication with PTC products.
• Auth URL—An endpoint used to grant permission for a client application to access their protected resources. It is required for connecting your client application to PTC resources.
• Access Token URL—An endpoint that allows the client to exchange an authorization code for an access token, allowing access to the user's protected resources.
• Audience—Identifies the audience (resource URI or server) for which this access token is intended. It is a way for the consuming party to validate if a particular JSON Web Token (JWT) is meant for them or not.
Currently, the accepted audience is https://windchill-plus
• Scope—An array of scopes that are granted to this access token.
Currently, the allowed scope is WINDCHILL_READ.
Manage Client Integrations
Organization administrators can create multiple external integrations that can be used to configure the third-party integrations with PTC products such as Windchill+. The Integrations page shows these applications, and each application has its own corresponding details page.
To manage client integrations:
1. In the left navigation pane, click Integrations.
2. On the Integrations page, click the application name or click Manage.
 |
The default value for Name is pulled from the value set at the time the Auth0 application was created.
|
The selected application’s page opens in the same browser tab. All actions performed on this page affect only the selected OAuth 2.0 client and its data.
3. Perform the steps mentioned in Creating an Integration section.
Creating an Integration
Perform the following steps to set up an integration:
1. Sign in to the PTC Admin Center.
2. Go to the Integrations page.
3. From the PTC Admin Center Integrations page, copy the values for the following parameters to the clipboard, and then paste them into the applicable section of your third-party applications page:
◦ Client ID
◦ Secret Key
a. To view the secret key, you must rotate it. On the PTC Admin Center Integrations page, under the Secret Key section, click Rotate Key.
|
|
Rotating your secret key generates a new key and invalidates the current key, disconnecting any associated integrations. This action cannot be undone.
|
b. Copy the secret key from the New Key Generated dialog box and click Close.
|
|
• After you close this dialog, you will no longer be able to view this secret key.
• A secret is confidential, and you must always rotate it and generate a new one whenever you (as an administrator/operator) want to use the key. This is to safeguard against any attempts to misuse the secret for a malicious intent.
• Secrets must be rotated by the user per the Software Development Lifecycle Practices. It is a shared responsibility to maintain secure application integrations. Ensure that each time a secret is rotated, all associated applications are updated with the current secret.
|
◦ Application URL
In the Application URL section, click the pencil icon next to Callback URL to enter the callback URL for your third-party application, and then click Save.
◦ Auth URL
◦ Access Token URL
See the detailed steps for using this information to integrate your third-party application in Generating an access token with your application.
Generating an Access Token with Your Application
This section describes the access token generation process.
1. The delegated authorization with Authorization Code flow starts with a GET REST API call to the Auth endpoint of the authorization server. For example, GET https://<AUTHORIZATION_SERVER>/authorize?audience=<AUDIENCE>&response_type=code&client_id=<Client ID>&scope=<SCOPE>&redirect_uri=Callback URL>&state=<STATE> where,
◦ audience—For whom the access token is intended. This is a required parameter and must be set to https://windchill-plus
◦ response_type—Indicates that the authorization server returns an authorization code. This is a required parameter and must be set to code.
◦ client_id—The client ID you received from PTC Admin Center.
◦ scope—One or more scope values indicating those parts of the application that you want to access. This is a required parameter, and it must be set to WINDCHILL_READ.
◦ redirect_uri—Application Callback URL.
◦ state—A random string generated by your application, which you will verify later.
For example, GET https://ptc-atlas-dev.us.auth0.com/authorize?audience=https://windchill-plus&response_type=code&client_id=rOTYOu4jQrKynCOZqvS9Pah6rVTxlGZi&scope=WINDCHILL_READ&redirect_uri=https://oauth.pstmn.io/v1/browser-callback&state=4000194150204c968a165f6fab08afa8 PTC Sign In page is displayed.
2. Enter your credentials to sign in.
3. After successful authentication, the flow continues when the authorization server redirects to the callback URL with authorization code and state as the query parameters: <Callback URL>?code=<AUTH_CODE>&state=<STATE>
|
|
The application must first compare this state value to ensure it matches the one you started with. You can store the state value in a cookie or session and compare it when the user comes back. This helps ensure that your redirection endpoint is safe from any attempts to exchange arbitrary authorization codes.
|
For example, https://oauth.pstmn.io/v1/browser-callback?code=wWR_mPfnggMSC694bf10bekymLYP6opBXNxmR3QYjIAPn&state=4000194150204c968a165f6fab08afa8
4. The application then exchanges the authorization code to get an Access Token by making a POST request to the token endpoint: POST https://<AUTHORIZATION_SERVER>/oauth/token
Request payload:
grant_type: "authorization_code"
code: <AUTH_CODE>
redirect_uri: "<Callback URL>"
client_id: "<Client ID>"
client_secret: "<CLIENT_SECRET>"
where,
◦ grant_type=authorization_code—The grant type for this flow is Authorization Code grant.
◦ code=AUTH_CODE_HERE—This is the code you received in the query string.
◦ redirect_uri=REDIRECT_URI—Must be identical to the redirect URI provided in the original link.
◦ client_id=CLIENT_ID—The same client ID you received from the PTC Admin Center.
◦ client_secret=CLIENT_SECRET—As this request is made from the server-side code, the secret is included.
Response body: {"access_token":"<Access Token>","scope":"WINDCHILL_READ","expires_in":3600,"token_type":"Bearer"}
5. Use the Access Token to make API Calls to PTC systems by sending it as part of Authorization Headers: /Windchill/oauth/servlet/odata/ProdMgmt/Parts?$filter=startswith(Name,'Axle')&ptc.search.latestversion=true
Request Headers: <Authorization: Bearer Access Token>