Skip to main content


         This documentation site is for previous versions. Visit our new documentation site for current releases.      
 

Creating and configuring an OAuth 2.0 client registration

Updated on June 30, 2021

Create an OAuth 2.0 client registration data instance to allow an external application or mobile native application to securely access Pega Platform REST services over HTTPS.

  1. In the Dev Studio header, click Create SecurityOAuth 2.0 Client Registration.
  2. Enter a short description and client name for your OAuth 2.0 client registration data instance. Begin the name with a letter, and use only alphanumeric characters.
  3. Click Create and open.
    Result: The Client Information tab is populated with the following information:
    • Client ID – The unique ID that is assigned to the client.
    • Client secret – The password that is assigned to the client to authenticate with the Pega Platform authorization module.
    • Authorization endpoint – The endpoint when you use the Authorization code grant type to configure Pega Platform as an access token provider.
    • Access token endpoint – The request URL that you can access to receive an access token for the client as a response after authentication. Your REST service authenticates the client by using the client ID and client secret.
    • Token revocation endpoint – The request URL that you can access. After authentication, you can revoke an already issued access token for the client. When the token is revoked, the system returns an HTTP status code 200 as a response, and all subsequent requests that the client sends by using the token result in an error.
    • Userinfo endpoint – The endpoint for requesting user profile information.
  4. Optional: View and manage the client access tokens.
    • To see the client secret, click View & download, and then click Download credentials in the dialog box to save the client credentials in a .txt file.
    • To generate a new password for the client, click Regenerate client secret. The system revokes any active access token that was issued for the client.
    • To revoke all the access tokens for the client, click Revoke access token.
  5. In the Supported grant types section, select one or more grant types that define how an application gets an access token.
    • Authorization code – Select this check box to use an authorization code grant type for web and mobile apps, and then enter the following:
      • List of redirect URIs – Enter one or more URIs that provide an authorization code that is used to request an access token.
      • Enable refresh token – Select this check box to get a refresh token along with an access token from the token endpoint. Use the refresh token to obtain a new access token when your previous access token has expired.
      • Enable proof key for code exchange – Select this check box to use the PKCE extension for additional security in mobile applications.
      Caution: As a best practice, do not configure a loopback URL as a redirect URI. If you configure a loopback URL, then at run time, the port number is not validated, and the client application can use any available port on the user's system, including ports that you might not intend to be used.
    • Client credentials – Select this check box to choose an operator that your application uses to authorize the OAuth 2.0 client, and then enter the following:
      • Operator ID – Press the Down Arrow key to select a unique ID that is assigned to the operator.
        Caution: This operator must not represent a human user who can log in to the system. The operator must be reserved for an OAuth 2.0 client that wants to access resources in Pega Platform. You can modify the scope of the operator's access group to allow the client to access selective resources in Pega Platform.
    • Password credentials – Select this check box to use user credentials to authorize the OAuth 2.0 client, and then enter the following:
      • Identity mapping – Press the Down Arrow key to select an identity mapping that validates the operator credentials and converts them to the OAuth 2.0 access token. The default is the identity mapping data instance named pyDefaultIdentityMappingForPasswordGrant. Click the Open icon to create a new identity mapping.
      • Enable refresh token – Select this check box to get a refresh token along with an access token from the token endpoint. Use the refresh token to obtain a new access token when your previous access token has expired.
    • SAML bearer – Select this check box to use a SAML assertion to authorize the OAuth 2.0 client in your application, and then enter the following:
      • Identity mapping – Press the Down Arrow key to select an identity mapping that uses a SAML 2.0 assertion, or click the Open icon to create a new identity mapping. This extracts user information from the SAML assertion and validates it to issue the OAuth 2.0 access token.
    • JWT bearer – Select this check box to use a JSON Web Token assertion to authorize the OAuth 2.0 client, and then enter the following:
      • Identity mapping – Press the Down Arrow key to select an identity mapping that uses a JSON web token, or click the Open icon to create a new identity mapping. This extracts the user information from the JSON web token (JWT) claims and validates it to issue the OAuth 2.0 access token.
  6. In the Token lifetime section, define the lifetimes for authorization code and tokens.
    1. Authorization code lifetime (in seconds) – Enter the time period in seconds for which an authorization code issued to an OAuth 2.0 client is valid. The default value is 600 seconds.
    2. Access token lifetime (in seconds) – Enter the time period in seconds for which an access token issued to an OAuth 2.0 client is valid. The default value is 3600 seconds.

      For Authorization code grant type, the access token lifetime will always be taken from the Client registration rule form, even though the refresh token value taken from IdP is less than the configured value in the rule form.

      For SAML and JWT bearer grant type, the access token lifetime will be the minimum value of assertion validity and the access token value configured in the client registration rule form.
    3. Refresh token lifetime (in seconds) – Enter the time period in seconds for which a refresh token issued to an OAuth 2.0 client is valid. The default value is 86400 seconds.
  7. To configure the information returned from the Userinfo endpoint as a Userinfo token, in the User profile mapping section, in the JWT generation profile field, press the Down Arrow key and select a token profile. The default is pyDefaultUserInfoMapping, which is the JSON web token (JWT) generation profile that represents the default Userinfo token structure. To define a different JWT generation profile, click the Open icon.
  8. Click Save.
  9. To specify a proxy for your REST connector, in the Advanced configuration section, select the Use proxy check box, and then configure the remaining proxy parameters:
    1. In the Host field, enter the address of the proxy host.
    2. In the Port field, enter the port number.
    3. To add in the authentication details, select the Use Authentication check box, and:
      • In the User ID field, enter the user ID.
      • In the Password field, enter the password.

Have a question? Get answers now.

Visit the Support Center to ask questions, engage in discussions, share ideas, and help others.

Did you find this content helpful?

Want to help us improve this content?

We'd prefer it if you saw us at our best.

Pega.com is not optimized for Internet Explorer. For the optimal experience, please use:

Close Deprecation Notice
Contact us