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:

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:

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:

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:

Error handling

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

{
 "error": "duplicate_client",
 "error_description": "Client already exists"
}

{
 "error": "invalid_client_metadata",
 "error_description": "grant_types is missing"
}

{
 "error": "invalid_request",
 "error_description": “<grant_type_name> grant type details are missing"
}

{
 "error": "invalid_request_data",
 "error_description": "Request parsing failed"
}

{
 "error": "invalid_grant_types",
 "error_description": "Identity profile missing in <grant_type> details"}

{
 "error": "invalid_client_metadata",
 "error_description": "redirect_uris are not found for authorization_code grant"
}

{
 "error": "invalid_request"
 "error_description": "Invalid issue_refresh_token value"
}

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

{
 "error": "invalid_request",
 "error_description": "Invalid use_idp_session_expiry value"
}

{
 "error": "invalid_client_metadata",
 "error_description": "pyRuleSetName-1 is either invalid RuleSet or user has insufficient privilege to use this RuleSet"}

{
 "errors": [
 {
 "ID": "invalid_authorization_header"
 "message": "Invalid Authentication Data."
 }
 ]
}

{
"errors": [
 {
"ID": "invalid_token",
"message": "Invalid token or expired."
 }
]
}