Creating and configuring an OAuth 2.0 client registration
Create an OAuth 2.0 client registration to allow an external application or mobile native application to securely access Pega Platform REST services over HTTPS.
- In the Dev Studio header, click .
- Enter a short description and client name for your OAuth 2.0 client registration. Begin the name with a letter and use only alphanumeric characters.
- Click Create and open.
- In the Client Credentials section, select the Type of
client:
- Confidential – Select this client type for applications that can securely authenticate with the Pega Platform authorization module and keep their client secret safe.
- Public – Select this client type for applications that cannot use client secrets, such as applications running in a browser or on a mobile device.
- Optional: View and manage the client access tokens.
- (Confidential only) To see the client secret, click View &
download, and then click Download credentials in
the dialog box to save the client credentials in a
.txtfile. - (Confidential only) To generate a new password for the client, click Regenerate client secret. The system revokes any active access token that it issued for the client.
- To revoke all the access tokens for the client, click Revoke access and refresh token.
- (Confidential only) To see the client secret, click View &
download, and then click Download credentials in
the dialog box to save the client credentials in a
-
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 checkbox to use an authorization code grant type for
web and mobile apps, and then enter the following information:
- List of redirect URIs – Enter one or more URIs that provide an authorization code that the client uses to request an access token.
- Enable
refresh token – Select this toggle to get a refresh token 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.
- Set refresh token expiry from IDP session expiry – Select this checkbox to set refresh tokens issued for authorization to expire according to the identity provider (IDP) session expiration, which ignores the value set for Refresh token lifetime (in seconds) in the Token expiry section.
- Enable Proof Key for Code Exchange – Select this checkbox to use the PKCE extension, which offers additional security in applications by providing proof to the authorization server that the authorization code belongs to the client application, and then enables the authorization server to issue an access token for that application.
- Client credentials (Confidential only) – Select this
checkbox to choose an operator
or access group that your application uses to authorize the OAuth 2.0 client, and then
enter the following information:
- Operator ID – Press the Down Arrow key to assign a unique ID to the operator.
- Password credentials – Select this checkbox to allow user
credentials to authorize the OAuth 2.0 client, and then enter the following information:
- Identity mapping – Press the Down Arrow key to select an identity mapping that validates the operator credentials, and then 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 checkbox to get a refresh token and an access token from the token endpoint. Use the refresh token to obtain a new access token after your previous access token has expires.
- SAML bearer – Select this checkbox to use a SAML assertion to
authorize the OAuth 2.0 client in your application, and then enter the following
information:
- 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 action extracts user information from the SAML assertion, and then validates it to issue the OAuth 2.0 access token.
- JWT bearer – Select this checkbox to use a JSON Web Token
assertion to authorize the OAuth 2.0 client, and then enter the following information:
- 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 action extracts the user information from the JSON web token (JWT) claims and validates it to issue the OAuth 2.0 access token.
- Authorization
code – Select this checkbox to use an authorization code grant type for
web and mobile apps, and then enter the following information:
- If Enable refresh token is selected, choose one of the following
options in the Token issuance section for refreshing the
token:
- Issue once and keep until expiry – Each time the client requests a new access token, Pega Platform issues the same refresh token, with the expiration time updated to the remaining token lifetime using the value provided in the Refresh token lifetime (in seconds) field.
- Issue a new refresh token without changing expiry – Each time the client requests a new access token, Pega Platform issues a new refresh token, and then updates the expiration time to the remaining token lifetime using the value in the Refresh token lifetime (in seconds) field.
- Issue a new refresh token and reset expiry – Each time the client requests a new access token, Pega Platform issues a new refresh token, with the expiry time reset to the value in the Refresh token lifetime (in seconds) field.
- In the Token expiry section, define the lifetimes for
authorization code and tokens.
- 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 Client registration rule form provides the access token lifetime, 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 is the minimum value of assertion validity and the access token value configured in the client registration rule form. - 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.
- 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.
- Access token idle timeout (in seconds) – Enter the timeout period in seconds for which the client has not renewed the token within this time. The refresh token also becomes invalid, as the renewal time exceeds the idle timeout.
- 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.
- Configure the information returned from the Userinfo endpoint as a Userinfo token, by pressing the Down Arrow key and selecting a token profile in the User profile mapping section, in the JWT generation profile field. 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.
- Click Save.
- To specify a proxy for your REST connector, in the Advanced
configuration section, select the Use proxy checkbox,
and then configure the remaining proxy parameters:
- In the Host field, enter the address of the proxy host.
- In the Port field, enter the port number.
- To add in the authentication details, select the Use
Authentication checkbox, and then enter the following information:
- In the User ID field, enter the user ID.
- In the Password field, enter the password.
Previous topic OAuth 2.0 client registrations Next topic OAuth 2.0 Management Services