OAuth is a standard framework that enables external client applications to securely access services on your behalf via HTTPS. The OAuth 2.0 specification provides several grant types. As of Pega 7.2, the Pega 7 Platform acts as an OAuth 2.0 provider and uses the client credentials grant type to grant trusted applications access to functions in Pega 7 Platform applications.

Procedure

This example describes how you can configure a client for access to the Pega API REST services.

Registering the client

Register the client with the Pega 7 Platform by creating an OAuth 2.0 Client Registration data instance in Designer Studio.

1. Create a new OAuth 2.0 Client Registration data instance from the Security category of the Records Explorer. For more information, see OAuth 2.0 Client Registration data instances - Completing the New or Save as form.

2. Complete the Client Information tab to save the data of the external client, as displayed in the following figure. It is a best practice to select or create an operator that is configured for the minimal level of access that is required by the application services. For more information, see OAuth 2.0 Client Registration data instances - Completing the Client Information tab.

   ​

   Completing the Client Information tab in the Client Registration data instance rule form

The system generates a unique client ID and secret for each Client Registration data instance, which you can regenerate at any time. The system also generates the endpoints that your client can use to obtain an access token or to revoke issued tokens.

Securing the Pega API by using OAuth 2.0

Select OAuth 2.0 as the authentication type for Pega API services in the Pega 7 Platform.

1. Use the Designer Studio search facility to search for the API service package.

2. On the Context tab of the API service package rule form, select OAuth 2.0 from the Authentication type list, as displayed in the following figure:

   

   Securing the Pega API by using OAuth 2.0

All of the services in the API package are now automatically configured for OAuth 2.0. Additionally, these services can now be invoked via a secure TLS 1.2 (HTTPS) endpoint only.

Configuring the client

According to the OAuth 2.0 client credentials grant flow, you must obtain an access token to access the protected (Pega API) resources.

1. To obtain an access token in Postman, send the client_id, client_secret, and grant_type in a POST request to the access token endpoint. Ensure that you have selected "No Auth" on the Authorization tab. A successful request returns an access_token that is valid for a defined period of time, as displayed in the following figure:

   

   ​Accessing a token endpoint

2. You can now make your actual request to a Pega API REST service that is protected by OAuth 2.0. In Postman, select the correct REST verb and provide a valid TLS 1.2 (HTTP) endpoint. This example describes how you can invoke the POST /cases Pega API. Enter the access_token in the Authorization tab in the format "Bearer <access_token>".

3. Enter your JSON-formatted request on the Body tab. This request is defined by the Pega API that you selected (POST /cases) and your case type. You can create a request case for city services and provide the request ID and details according to your case definition:

   {"caseTypeID": "Cnow-connectnow-Work-CityServicesRequest", "processID": "pyStartCase", "content": {"RequestID": "FT123", "RequestDetail": "faster trains, please!"}}

   A successful invocation of the service returns the ID and class of your case, as displayed in the following figure:

   ​

   Invoking the POST /cases Pega API