This topic assumes familiarity with the OAuth 2.0 protocol and Single Sign-On (SSO) concepts.

In OAuth 2.0, there are several grant types. The Authorization Code grant type is generally used for interactive use cases requiring a user interaction during the authentication.

This topic describes the manual steps for authorizing access to resources and authenticating resource owners using the OAuth Authorization Code grant type. Typically, when implementing an OAuth-enabled client, third-party libraries are used to streamline the acquisition, use, and secure management of the access and refresh tokens. Implementers are encouraged to evaluate a library appropriate for their use case and programming language. For more information on OAuth libraries of various languages, refer to Code: OAuth Libraries.

For more information about OAuth and grant types, refer to the following documentation:

For more information Single Sign-On (SSO) and OAuth configuration with PTC Products, refer to PTC Identity and Access Management Help Center.

All subsections of this document assume that both the Central Authorization Server (CAS), Windchill, and the client application have been configured for OAuth. Windchill must be configured as a Resource Server using OAuth. The OAuth Client must be registered as a Service Provider.

For more information, refer to the following documentation:

Before you begin, make sure to have the following information:

The first step of OAuth 2 is to get the authorization from the user. For browser-based or mobile apps, this is usually accomplished by displaying an interface provided by the service to the user.

It could take the form of a “Log In” link sending the user to the CAS server for an authorization. The URL of that link should resemble the following:

where:

In this example, the client application is Postman, and the URL called is:

The user sees the authorization prompt as shown below:

When the user clicks Sign On, the service redirects the user to an approval page as shown below:

When the user clicks Allow, the URL specified in redirect_uri above is called by the CAS, with an authorization code and the application state:

where:

In this example:

You should first compare this state value to ensure it matches the one you started with. You can typically store the state value in a cookie or session, and compare it when the user comes back. This helps ensure your redirection endpoint isn't able to be tricked into attempting to exchange arbitrary authorization codes.

Examples of a redirect_uri might be a redirect back into a web application that requested the sign-on in the first place, or a redirect into a native application on the client OS using URI schemes.

Your web app server exchanges the authorization code for an access token by making a POST request to the authorization server's token endpoint, with the request body containing the previously obtained authorization code. Note that according to RFC 6749, the request body must have the application/x-www-form-urlencoded content type.

The server returns an access token and a refresh token.

The response contains the access token (access_token) you will use to call WRS endpoints. Note that the response also includes the token lifetime in seconds (expires_in) and the refresh token (refresh_token). The refresh token will be used later.

The response body is in JSON format described in The OAuth 2.0 Authorization Framework: Successful Response. In example, the POST request looks like this:

Now that you have the access token, you can perform the WRS call specifying the access token as the Bearer Token in the Authorization header:

Note that to authenticate against WRS endpoints with an OAuth Bearer token, the client must call URLs containing the “oauth” prefix. Windchill must be configured to support OAuth. For more information, see Configure OAuth Delegated Authorization in Windchill Help Center.

For example:

Access tokens have a limited lifespan (in the example above, 3600 seconds or 1 hour). The access token lifetime is configured in your CAS. It should typically be short-lived (a few minutes maximum).

When the token expires, the user must login and grant authorization again. To avoid that, the client can request a new access token from the CAS using the refresh token. This is done by making a POST request to the CAS:

Where:

The server replies with a new access token, similar to the previous step. For example:

You can then use the new access token for subsequent WRS calls.

If the response also contains a new refresh token, then it means the original refresh token has also expired. The client should then securely store both the new access token and the new refresh token for subsequent uses.

The lifetime of the tokens is configurable in the CAS.

For instance, in Ping Federate it is possible to configure tokens roll refresh, so that the refresh token is single-use. Each time a new access token is requested using the refresh token, a new refresh token is issued.

OAuth 2 is a standard documented at: OAuth 2.0.

Most of the information in this document can be found here.

This document presents the detailed calls required to use OAuth 2. You may be able to simplify it using a code library tailored to your particular use case. The OAuth website has a list of these libraries: Code: OAuth Libraries.

For information on setting up PingFederate and OAuth, refer to: PTC Identity and Access Management Help Center.