Understanding dynamic client registration
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 .
- Then click .
- 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:
Refresh token issuance mechanism to be configured for the
client being registered An HTTP error 400 – Bad Request is thrown for
an invalid input. 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. 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. 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. 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.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 pega_associated_ruleset String No 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 use_idp_session_expiry String No 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 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:
A comma (,) is
missing the client_name and client_description
properties. This error applies to the SAML bearer and JWT
bearer grant types. This
error applies to the Authorization code grant
type. This error applies to the authorization_code and
password grant types. The refresh_token_strategy is not among: This error applies only to the authorization_code
grant type.
">
">
">
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. 400 {
"error": "invalid_grant_types",
"error_description": "Identity profile missing in <grant_type> details"}
The grant_type details does not contain identity profile
details. 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. 400 {
"error": "invalid_request"
"error_description": "Invalid issue_refresh_token value"
}
The issue_refresh_token value is not either true or
false. 400 {
"error": "invalid_request",
"error_description": "Invalid refresh_token_strategy value"
}
400 {
"error": "invalid_request",
"error_description": "Invalid use_idp_session_expiry value"
}
The use_idp_session_expiry value is not either true or
false. 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.
Previous topic Enhanced refresh token strategy Next topic Creating and configuring an OAuth 2.0 provider