Skip to main content


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

OAuth 2.0 Management Services

Updated on March 15, 2022

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 typePurposeService endpoint HTTP method
Keys endpointUsed 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/keysGET
Token introspection endpoint Used to validate the access token.https://<host>:<port>/prweb/PRRestService/oauth2/v1/token/introspectPOST
Token deny list endpointUsed to get the list of denied tokens or to add tokens to the deny list.https://<host>:<port>/prweb/api/oauth2/v1/token/denylistGET 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

SettingValue
Cryptographic algorithm4096-bit RSA key pair
Default key rotation period15 days
Key rotation period range1 to 365 days
Dynamic system settingShort 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

For example:

The following list shows a sample request and response:

  • Sample request: GET /keys
  • Sample response:

    The response is JSON Web Key Set (JWKS).

    {
      "keys": [
        {
          "kty": "RSA",
          "e": "AQAB",						
          "use": "sig",					
          "kid": "8928ce9c4eb8f1f02e57cd435cb7a794",
          "alg": "RS256",
          "n": "kVgSt5nVKt5OXRwjBAlgHZ1oBkm8MQhxpp-TUG0t9CsHFeu8yDMRDlNqJZgwjQPjhc7pjkTf1b0xnxjQEGs6ezxXwBpSmtysLQzuAkTd4TQnIY9OVq78Q9DO0TpTWVhaHYnsGoTswQNytPsgF9WypCqMX1tI0PVvArMR6GXbJuUi5cY7topVP3LGJf3_jeEf7COWsHEo4t8dCNLhKlwmOpAYFALXJ7ZueAralbZe0I6cGqPpfDEBy0iWvG0x0nvK1IVgsfMNvxRO1aa-EVc1XJxNAFMI_T_lNh3zrPdB5OcbJVZczug5VlYIIYjlZpi8g9cqfIYY-j1NIZ3QfXnO_j1lemlKvER9sQbXoLS7A3UWSxrn0d0DogW8bQyB-FtOp9iK5WziKRbkdghZ3lMRvPZIWw7kZ75JR7TYOmWzG14AFV0_PzoBgvejV722P3Cm3PfIJe97ar2QEFmCIWPlTPtkJs9w9qwMlNELLszYcar1fefFtsqgwuBpuWex5pbscHYWes8SbMG2xkUP43j0TWgWfMPOaa-u0m_5urEJAA9R5jsK7fkdkAjlZWG8EyzqlO9XTvEN5ECva0ZUhLBqNpQKjCua42ntjcDif-hdZv10w8wRaZmn2QPtQXg3BtPaJr4T0BjKUT0Uj2V6nRa_IWtTBl8rfZr8yESQP-NDqSU"
        },
        {
          "kty": "RSA",
          "e": "AQAB",
          "use": "sig",
          "kid": "02611e4a4cdad7b3861939df5f8cdb76",
          "alg": "RS256",
          "n": "oKeBjxPblG__GZVt7NsCz5kOJIGudIqE-ZO36sTBBElcwnOBKE_nPbbqPoNMxkb8tDt52_drm1OCFRrrawydhZvvqaiM9hGX3_OTVZBWXD_i1JnUomtZIBe-foyW-330CVEumIpGHiXdA9BKKXYb5W0CBb7vDdJP6AE4vUTDqBdSPFWJX853eSj0gAJ8mSbP25rJotWnjzSBPGBxMAGU8BJuRF6kC7qUbzc6aolHshM35QV7nsC3tR7XdiMS0bP0OcNZblSUIHESx3S_M5vxjiM7s5yv0foBQpdfJkKz5I92LxDpryTC1te6XkKbzVlgtDlT3z3dtstxOeTsPpQN4JfBZMYIDsShO4jDwZFIXHWd1EqztcfCxP4AAqU8vajelkJ5YkiUglqpf7LRdwhyJlAMn5BxJgWe3SSCSLKRA6qDFTQoRqwZokACnThBHQ48cxN-JF1YTkw3rv0HYkdYKVtWk8_VV6pTgg6bQDXisoHlcxrucD226rmCJU54af4KggahhBGqn6OUTm96NKKrL6pQkxQUkuVXluNYZtfrWQzUaE8KI8Wszgc_w6gXh8LHy9PpBeF_MKM-NbfEqTG8NOyVQOWHorgXjvWguHxjYcp8qm6A2dyczG5wMwrCJIaNflDRkMkAHA0ATKZBkliviHqUZU_EVRIPcucGRSQrRI8"
        }
      ]
    }
    

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

For example:

The following list shows a sample request and response for POST introspection:

  • Sample request:POST /introspectContent-Type:application/x-www-form-urlencodedAuthorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JWRequest body: token=mF_9hgh.B5f-4hghgh.1JqMhhghgh
  • Sample response:

    Response Code: 200

    {
        "active": true
    }
    

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

The supported GET query parameters are client_id, username, and revoked_after.
For example:

The following list shows a sample request and response for GET HTTP method:

  • Sample request:GET /denylistAuthorization: Bearer czZCaGRSa3F0MzpnWDFmQmF0M2JW...
  • Sample response:

    HTTP status: 200

    {
        "revoked_before": "20200719T132021.66 GMT",
        "jti": [
            "9e69ebde3cd3d78212a66346a48ceb8a",
           “78e21a3aa9c999cab6b7d64dd2ca3f82”,
           …..
        ]
    }
    

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.

For example:

The following input shows sample response for pagination:GET/denylist?client_id=67088366916174900&username=testOperator&revoked_after=20200719T132021.66 GMTAuthorization: Bearer czZCaGRSa3F0MzpnWDFmQmF0M2JW...

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.

For example:

The following list shows a Sample request and response for POST HTTP method:

  • Sample request

    The sample request invalidates all tokens of a client where the client_id is 67088366973216174900.

    POST / denylist HTTP

    Content-Type: application/x-www-form-urlencoded

    Authorization: Bearer czZCaGRSa3F0MzpnWDFmQmF0M2JW

    Request body: client_id = 67088366973216174900

  • Sample response

    HTTP status: 200

    {
        "jti": [
            "0c2141b68c4b7ceb888c30be6d95b218",
            "78e21a3aa9c999cab6b7d64dd2ca3f82"
        ]
    }
    
  • Previous topic Creating and configuring an OAuth 2.0 client registration
  • Next topic Understanding authorized access tokens

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