OAuth 2.0 Management Services
You can manage the token-based security of user sessions provided in the OAuth 2.0 service packages. OAuth 2.0 is a protocol that grants a third-party web site or application access to the user's protected resources, without necessarily revealing their long-term credentials or even their identity.
OAuth 2.0 REST endpoints
The OAuth 2.0 service package defines a set of Representational State Transfer (REST) service endpoints. An endpoint is typically a Uniform Resource Identifier (URI) on a web server.Pega Platform supports three REST endpoints: keys endpoints, token introspection endpoints, and token deny list endpoints, which are described in the following table:
OAuth 2.0 REST endpoint types
Endpoint type | Purpose | Service endpoint | HTTP method |
Keys endpoint | Used to get the public keys that are exposed in the JSON Web Key Set (JWKS) format and to perform signature validation of the authorized access token (AAT) that Pega Platform issues as the OAuth 2.0 provider. | https://<host>:<port>/prweb/PRRestService/oauth2/v1/token/keys | GET |
Token introspection endpoint | Used to validate the access token. | https://<host>:<port>/prweb/PRRestService/oauth2/v1/token/introspect | POST |
Token deny list endpoint | Used to get the list of denied tokens or to add tokens to the deny list. | https://<host>:<port>/prweb/api/oauth2/v1/token/denylist | GET and POST |
For more information about HTTP methods, see Service REST methods.
Keys endpoint
The keys endpoint publishes the public keys that you can use to validate the signature of access tokens that Pega Platform issues as an OAuth 2.0 provider. These public keys are exposed in the JSON Web Key Set (JWKS) format.
The OAuth 2.0 provider issues access tokens in the authorized access token (AAT) format. This token is a signed JSON Web Token (JWS).
For signing, Pega Platform uses a 4096-bit length RSA key-pair. The RSA key pair contains both private and public keys. The private key is used for signature generation of the JWT token, while the public key is used for signature verification of the token.
Key rotation
The default RSA key pair is valid for 15 days. After 15 days, Pega Platform generates a new RSA key-pair for JWT token signing. The keys endpoint provides both old and new RSA public keys in the JWK format.
You can customize the key rotation from anywhere between 1 to 365 days by using the AccessToken/KeyRotationInterval dynamic system setting in the Pega-IntegrationEngine ruleset. Pega Platform does not include the dynamic system setting by default.
For more information about creating this dynamic system setting, see Creating a dynamic system setting.
The following table presents the key parameters of the keys endpoint:
Keys endpoint settings
Setting | Value |
Cryptographic algorithm | 4096-bit RSA key pair |
Default key rotation period | 15 days |
Key rotation period range | 1 to 365 days |
Dynamic system setting | Short description: Should be descriptive
and easy to read, for example, AAT key rotation
interval. Setting purpose: AccessToken/KeyRotationInterval. Owning ruleset: Pega-IntegrationEngine. Value: Integer value with the desired key rotation time period. |
Service endpoint:
https://<host>:<port>/prweb/PRRestService/oauth2/v1/token/keys
Token introspection endpoint
The token introspection endpoint validates the AATs and refresh tokens that the Pega Platform OAuth2.0 provider issues. The endpoint response is either true or false for the active response parameter. The introspection endpoint supports only the POST method. By default, the endpoint is protected by basic authentication; therefore, you must provide client credentials (client identifier and secret) as an authorization header. You provide the input token in a POST body parameter.
Service endpoint:
https://<host>:<port>/prweb/PRRestService/oauth2/v1/token/introspect
Token deny list endpoint
The token deny list endpoint supports GET and POST methods. The GET method retrieves deny listed tokens from the server. You can use the POST method to add tokens to the deny list. The pzCanAccessBlacklistedTokenService privilege is required to use this endpoint. This endpoint is protected by OAuth2.0, and you must provide bearer access token in the authorization header.
Service endpoint:
https://<host>:<port>/prweb/PRRestService/oauth2/v1/token/denylist
Pagination
The GET method supports pagination and can send up to 1000 JWT identifiers (jti or
JWT ID) in a single response. For more than 1000 results, use the pagination
parameters to retrieve additional JWT IDs. To get the next page of results, the
request must include the revoked_after
query parameter, and its
value should be set to the revoked_before
value from the previous
response.
POST method
The POST method adds a token to the deny list based on filters that are POST body parameters. The supported POST body parameters are client_id, jti, username, issued_before, and issued_after.
A JWT ID provides a unique identifier for the JWT. You can use the Revoked_before parameter to get next page results if you have more than 1000 JWT IDs.
Previous topic Creating and configuring an OAuth 2.0 client registration Next topic Understanding authorized access tokens