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

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

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.