Skip to main content


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

Understanding dynamic client registration

Updated on June 30, 2021

Use dynamic client registration (DCR) to dynamically register trusted third-party applications as OAuth 2.0 clients with Pega Platform. DCR create OAuth 2.0 clients for you, using Pega Platform defaults

OAuth 2.0 client registration

There are two ways to register an OAuth 2.0 client application:

Manual registration
Manual registration is typically used when you need to create an OAuth 2.0 client and the defaults do not suit your needs.
You can manually create an OAuth 2.0 client in the navigation pane of Dev Studio, by clicking RecordsSecurityOAuth 2.0 Client registration.
Then click ActionCreate.
Then, you choose the settings as you go through.
For more information, see OAuth 2.0 client registrations.
Dynamic creation
Dynamic client creation can be used to save time in creating OAuth 2.0 clients. The defaults can be changed at any time on the OAuth 2.0 client registration form.
OAuth 2.0 clients can also be registered programmatically by calling the dynamic client registration service endpoint.
The service endpoint is https://<host>:<port>/prweb/api/oauthclients/v1/client.

Dynamic client registration

Pega Platform introduced new properties to support enhanced refresh token mechanism in the OAuth2 Client Registration Rule form.

The newly added properties are also supported in the dynamic client creation.

By default, in the Authorization Code grant type section, the Set refresh token expiry from the IDP Session expiry check box is not selected.

When the Set refresh token expiry from the IDP Session expiry check box is selected, the use_idp_session_expiry is included in the payload. This value can be set to either true or false. If set to any other value, the system returns an Invalid Request (400) error. When the payload is not specified, then the default value is false.

OAuth 2.0 clients can also be registered programmatically by calling the DCR service endpoint. DCR itself is protected by OAuth 2.0. You must have the pzCanManageOAuthClients privilege enabled in order to use DCR to register third-party applications to manually registered as an OAuth 2.0 client.

Registering a client by using dynamic client registration

When you register a client using dynamic client registration, the OAuth 2.0 Client it generates has the default attributes shown in the table below:

PropertyValue
Service endpoint https://<host>:<port>/prweb/api/oauthclients/v1/client
HTTP Method POST

HTTP headers

When you register a client using dynamic client registration, the OAuth 2.0 Client it generates has the default attributes shown in the table below:

PropertyValueBehavior
AcceptApplication/json
Content-TypeApplication/json
AuthorizationBearer <AccessToken>Access token issued to the registered client privileged for dynamic client registration.

HTTP request

When you register a client using dynamic client registration, the OAuth 2.0 Client it generates has the default attributes shown in the table below:

Parameter nameData typeRequired?Description
client_nameStringYesUnique name of the third-party application to be registered as the OAuth 2.0 client
client_descriptionStringYesDescription of the third-party application to be registered as the OAuth 2.0 client
grant_typesArray of StringYesList of OAuth 2.0 grant types to be configured for the client being registered
refresh_token_strategyStringNo

Refresh token issuance mechanism to be configured for the client being registered

  • Valid inputs
  • · issueOnce
  • · issueNew
  • ·issueNew_ResetExpiry

An HTTP error 400 – Bad Request is thrown for an invalid input.

pega_associated_rulesetStringNo

Pega ruleset to associate with the client being registered.

Value can be either valid Pega Ruleset name or empty.

Set the property if you want the registered client to be associated with a specific Pega Ruleset, else do not add it to the request.

An HTTP error 400 – Bad Request is thrown for an invalid ruleset name.

authorization_codeObjectNoConfiguration to provide when authorization code grant is selected.
redirect_urisArray of StringYesList of URIs to be set as OAuth 2.0 redirect URIs for the client being registered
Issue_refresh_tokenStringNo

Flag to enable refresh token support for the client being registered when using authorization code grant type.

Input should be either true or false.

An HTTP error 400 – Bad Request is thrown for an invalid input.

use_idp_session_expiryStringNo

Flag to useSession Expiry from IDPasthe refresh token lifetime.

Input should be either true or false. An HTTP error 400 – Bad Request is thrown for an invalid input.

enable_pkceStringNoFlag to enable support for Proof Key for Code Exchange (PKCE)
passwordObjectNoConfiguration to provide when password credentials grant is selected.
issue_refresh_tokenStringNo

Flag to enable refresh token support for the client being registered when using password grant type.

Input should be either true or false. An HTTP error 400 – Bad Request is thrown for an invalid input.

identity_mapping_nameStringNoUnique name representing the Pega Identity mapping rule of type Custom to use with the grant type for deriving the operator context.
urn:ietf:params:oauth:grant-type:jwt-bearerObjectNoConfiguration to provide when password credentials grant is selected.
identity_mapping_nameStringYesUnique name representing the Pega Identity mapping rule of type JSON Web Token to use with the grant type for deriving the operator context.
urn:ietf:params:oauth:grant-type:saml2-bearerObjectNoConfiguration to provide when password credentials grant is selected.
identity_mapping_nameString YesUnique name representing the Pega Identity mapping rule of type SAML 2.0 Assertion to use with the grant type for deriving the operator context.

HTTP response

When you register a client using dynamic client registration, the OAuth 2.0 Client it generates has the default attributes shown in the table below:

HTTP bodyDataTypeDescription
client_nameStringUnique name of the third-party application specified in the DCR request.
client_idStringUnique client ID of the newly registered OAuth 2.0 client.
client_secretStringUnique client secret of the newly registered OAuth 2.0 client.
client_secret_expires_atStringAlways returns '0' and indicates a non-expiring client secret.
redirect_urisArray of StringsList of URIs set as OAuth 2.0 redirect URIs for the newly registered client.
grant_TypesArray of StringsList of OAuth 2.0 grant types configured for the newly registered client.

For example:

Example request:

{ 
"client_name": 
"AllGrants", 
"client_description": 
"AllGrants", 
"grant_types": [ 
"authorization_code", 
"password", 
"urn:ietf:params:oauth:grant-type:jwt-bearer", 
"urn:ietf:params:oauth:grant-type:saml2-bearer" 
],

"authorization_code": { 
"redirect_uris": [ 
"https://localhost", 
"https://localhost.com" 
], 
"issue_refresh_token": 
"false", 
"enable_pkce": "false" ,
“use_idp_session_expiry”:”true”
}, 
"urn:ietf:params:oauth:grant-type:jwt-bearer": { 
"identity_mapping_name": 
"testidentity" 
}, 
"password": { 
"identity_mapping_name": 
"testidentity" 
}, 
"urn:ietf:params:oauth:grant-type:saml2-bearer": { 
"identity_mapping_name": 
"testidentity" 
}, 

"refresh_token_strategy":"issueNew" ,
"pega_associated_ruleset":"validruleset"

}

Error handling

The following table details common errors that can occur during dynamic client registration requests:

"> "> ">
HTTP error codeError messageDescription
409
{
 "error": "duplicate_client",
 "error_description": "Client already exists"
}
A registered client already exists with the client_name parameter provided in the request.
400
{
 "error": "invalid_client_metadata",
 "error_description": "grant_types is missing"
}
Grant type details are not provided in the request.
400
{
 "error": "invalid_request",
 "error_description": “<grant_type_name> grant type details are missing"
}
The Grant type is specified in the grant_types parameter but corresponding details are not provided in the request.
400
{
 "error": "invalid_request_data",
 "error_description": "Request parsing failed"
}
A request is not in the correct JSON format.

A comma (,) is missing the client_name and client_description properties.

400
{
 "error": "invalid_grant_types",
 "error_description": "Identity profile missing in <grant_type> details"}
The grant_type details does not contain identity profile details.

This error applies to the SAML bearer and JWT bearer grant types.

400
{
 "error": "invalid_client_metadata",
 "error_description": "redirect_uris are not found for authorization_code grant"
}
Redirect URI details are not provided in the request.

This error applies to the Authorization code grant type.

400
{
 "error": "invalid_request"
 "error_description": "Invalid issue_refresh_token value"
}
The issue_refresh_token value is not either true or false.

This error applies to the authorization_code and password grant types.

400
{
 "error": "invalid_request",
 "error_description": "Invalid refresh_token_strategy value"
}

The refresh_token_strategy is not among:

  • issueOnce
  • issueNew
  • issueNew_ResetExpiry
400
{
 "error": "invalid_request",
 "error_description": "Invalid use_idp_session_expiry value"
}
The use_idp_session_expiry value is not either true or false.

This error applies only to the authorization_code grant type.

400

{
 "error": "invalid_client_metadata",
 "error_description": "pyRuleSetName-1 is either invalid RuleSet or user has insufficient privilege to use this RuleSet"}
The input to the property pega_associated_ruleset is not a valid ruleset
401
{
 "errors": [
 {
 "ID": "invalid_authorization_header"
 "message": "Invalid Authentication Data."
 }
 ]
}
The authorization header is not provided in the request.
401
{
"errors": [
 {
"ID": "invalid_token",
"message": "Invalid token or expired."
 }
]
}
The invalid token is provided in the request as authorization header.

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