Creating and configuring an OAuth 2.0 client registration

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 > Security > OAuth 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.
    • 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.
    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.