LinkedIn
Copied!

Table of Contents

Understanding dynamic client registration

Version:

Only available versions of this content are shown in the dropdown

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 Records Security OAuth 2.0 Client registration .
Then click Action Create .
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:

Property Value
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:

Property Value Behavior
Accept Application/json
Content-Type Application/json
Authorization Bearer <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 name Data type Required? Description
client_name String Yes Unique name of the third-party application to be registered as the OAuth 2.0 client
client_description String Yes Description of the third-party application to be registered as the OAuth 2.0 client
grant_types Array of String Yes List of OAuth 2.0 grant types to be configured for the client being registered
refresh_token_strategy String No

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_ruleset String No

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_code Object No Configuration to provide when authorization code grant is selected.
redirect_uris Array of String Yes List of URIs to be set as OAuth 2.0 redirect URIs for the client being registered
Issue_refresh_token String No

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_expiry String No

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_pkce String No Flag to enable support for Proof Key for Code Exchange (PKCE)
password Object No Configuration to provide when password credentials grant is selected.
issue_refresh_token String No

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_name String No Unique 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-bearer Object No Configuration to provide when password credentials grant is selected.
identity_mapping_name String Yes Unique 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-bearer Object No Configuration to provide when password credentials grant is selected.
identity_mapping_name String Yes Unique 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 body DataType Description
client_name String Unique name of the third-party application specified in the DCR request.
client_id String Unique client ID of the newly registered OAuth 2.0 client.
client_secret String Unique client secret of the newly registered OAuth 2.0 client.
client_secret_expires_at String Always returns '0' and indicates a non-expiring client secret.
redirect_uris Array of Strings List of URIs set as OAuth 2.0 redirect URIs for the newly registered client.
grant_Types Array of Strings List of OAuth 2.0 grant types configured for the newly registered client.

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 code Error message Description
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.

Did you find this content helpful?

Have a question? Get answers now.

Visit the Collaboration Center to ask questions, engage in discussions, share ideas, and help others.