Configuring an OAuth 2.

0 authentication profile

Version 8.7
Updated on March 15, 2022
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.

Before you begin: Add an authentication profile that you want to configure. For
more information, see Creating an authentication profile.
The OAuth 2.0 provider is an authorization server that provides token-based
authorization so that Pega Platform can access external web service APIs. When you
use OAuth 2.0, Pega Platform, the provider negotiates a token that Pega Platform
uses to access the external application for a defined period. To learn how to
obtain the values for the configuration fields on this tab, see the API guide of
the authorization server (OAuth 2.0 provider).
In the navigation pane of Dev Studio,click RecordsSecurityAuthentication Profile.
In the list of instances, select an OAuth 2.0 authentication profile.
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.
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.
Enter the credentials to access OAuth 2.0-protected resources in the external
application:
In the Client identifier field, enter the client ID that the authorization server
provides.
In the Client secret field, enter the client secret that the authorization server
provides.
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.
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.
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.
Optional: To enable single sign-on (SSO) for Box, perform the following actions:
Select the Enable SSO check box.
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).
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.
For the password credentials grant type, in the Password credentials section, enter
the login details:
In the Username field, enter the name of the property that references the value for
the username.
In the Password field, enter the name of the property that references the value for
the user password.
Ensure that you encrypt the password.
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.
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.
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.
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.
For the authorization code grant type, configure the code:
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.
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.
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).
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.
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
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.
Optional: To increase authentication security, in the Security settings section,
configure keys and certificates:
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.
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.
Click Save.
Previous topic