Configuring an OAuth 2.0 authentication profile

Configure an OAuth 2.0 authentication profile to secure messages that your application sends and receives, by using an OAuth 2.0 token-based authorization process. You define OAuth 2.0 authentication profiles for Pega Platform to securely access external REST service APIs with access tokens.

1. In the navigation pane of Dev Studio,click Records > Security > Authentication Profile.
2. In the list of instances, select an OAuth 2.0 authentication profile.
3. In the OAuth 2.0 provider list, click the name of an OAuth 2.0 provider. You can select from various well-known providers, as well as Custom.
4. In the Grant type list, select the grant type that defines how to request an access token from the OAuth 2.0 provider:
   • To configure your application to obtain client credentials from the authorization service, select Client credentials.

     With these credentials, you can access protected resources in the external application for a defined period.

   • To configure your application to submit an authorization code request to the external application to which you want to connect, select Authorization code.

     The authorization server of the external application validates the credentials in the request, and then authenticates you with your user credentials to produce an authorization code. You exchange the code to obtain an access token from the authorization server, which grants you access to your protected resources on the external application. Use this grant type when your application requires manual intervention to authorize access to the protected resources of the external application.

   • To configure your application to exchange your user credentials for an access token, select Password credentials.

     Use this grant type when your application has a trusted relationship with the API provider or when the API provider does not support other authorization grants.

   • To configure your application to use a JWT bearer token to request an access token from the authorization server. JWT bearer.
5. Enter the credentials to access OAuth 2.0-protected resources in the external application:
   1. In the Client identifier field, enter the client ID that the authorization server provides.
   2. In the Client secret field, enter the client secret that the authorization server provides.
   3. Optional: To define the client scope, in the Scope field, enter the scope that is specified in the API guide of the external application and that is configured for this client.
      Separate multiple scopes with a space.
   4. Optional: If the service provider supports a refresh token, select the Use refresh token if available check box.
      The refresh token automatically obtains a new access token when the current token expires.
   5. Optional: To revoke all access tokens that you obtain from the external OAuth 2.0 provider for this OAuth 2.0 client, click Revoke access tokens.
6. Optional: To enable single sign-on (SSO) for Box, perform the following actions:
   1. Select the Enable SSO check box.
   2. In the Single sign-on (SSO) identity provider (IdP) federation ID field, enter the SSO identity provider federation ID for the Box account.
      You can get this value from the entityID attribute of the EntityDescriptor element of the IdP metadata XML file with SSO configuration for Box.
      This field supports the Global Resource Settings syntax (=PageName.PropertyName).
7. For the JWT bearer grant type, in the JWT assertion section, identify the source of the JWT for generating the access token request:
   • To use the JWT from the OAuth 2.0 identity provider from the OpenID Connect identity provider you use to SSO into your pega application, select Use token from active SSO session.
   • To use a JWT generation profile, in the JWT generation template field, press the Down arrow key to select a JWT generation profile, or click the Open icon to create a JWT profile.
   • To use a property reference, in the Property reference field, enter the name of the property that stores the encoded JWT.
8. For the password credentials grant type, in the Password credentials section, enter the login details:
   1. In the Username field, enter the name of the property that references the value for the username.
   2. In the Password field, enter the name of the property that references the value for the user password.
      Ensure that you encrypt the password.
9. In the Access token endpoint field, enter the access token URL that is specified in the API guide of the application to which you want to connect.
   Calls to this endpoint produce an access token that you can use to access protected resources in the external application for a defined period.
10. Optional: To enter parameters for an access token or to refresh a token request, click Add access token and refresh token parameters, enter parameter names and values, and then click OK.
11. Optional: In the Revoke token endpoint field, enter the revoke token URL that is specified in the API guide of the application to which you want to connect.
12. Optional: To add request parameters, click Add parameters, and then enter the parameter names and values.
    Calls to this endpoint revoke access tokens for your application that functions as an OAuth 2.0 client.
13. For the authorization code grant type, configure the code:
    1. In the Authorization code endpoint field, enter the authorization code endpoint URL that is specified in the API guide of the authorization server to which you want to connect.
    2. To add parameters, click Add parameters, and then enter the parameter names and values.
       Calls to this endpoint produce an access token that you can use to access protected resources in the external application for a defined period.
    3. In the Redirect URI endpoint field, specify that the target endpoint redirects to an authority with a URI that exposes a datapage using the Global Resource Settings syntax (=PageName.PropertyName).
14. In the Advanced configuration section, in the Client authentication subsection, select an authentication scheme to use for sending the client credentials in the access token request.

    Choices	Actions
    Client secret through the Basic scheme	In the Authentication scheme list, select Client secret. In Method, select Basic. This option sends the client credentials (client ID and client secret) to the external application as a part of the authorization header.
    Client secret through the POST request	In the Authentication scheme list, select Client secret. In Method, select POST. This option sends the client credentials in the body of the POST request.
    JSON web token through a JWT generation profile	In the Authentication scheme list, click Private Key JSON Web Token (JWT). Select Use JWT generation profile. In the JWT generation profile field, press the Down arrow key to select a JWT generation profile, or click the Open icon to create a JWT profile.
    JSON web token through a property reference	In the Authentication scheme list, click Private Key JSON Web Token (JWT). Select Use property reference. In the Property reference field, enter the name of the property that contains the JWT.

15. In the Send access token as section, select how to send the access token to the external application:
    • To allow applications, such as mobile apps, to use third-party tokens to authenticate with a server, select Authorization header
    • To allow applications to authenticate requests when you want to express a request entirely in a URL, select Query string parameter
16. In the Secure protocol configuration section, in the Lowest allowable SSL/TSL version list, select the SSL or TLS protocol version that you want to use to securely connect to the external application by using OAuth 2.0.
17. Optional: To increase authentication security, in the Security settings section, configure keys and certificates:
    1. In the Truststore field, press the Down arrow key to select a truststore, or click the Open icon to create a truststore.
       The truststore contains the server certificate to use in the TLS/SSL handshake.
    2. In the Keystore field, press the Down arrow key to select a keystore, or click the Open icon to create a keystore.
       The keystore stores the Pega Platform client's private/public key pair the server uses to authenticate the client.
18. Click Save.