Your applications act as clients to Identity Cloud.
ForgeRock uses both OAuth 2.0 and OpenID Connect protocols to protect your applications. When you register a supported app or service, Identity Cloud sets the OAuth 2.0 grant type based on the type of app you’re registering. Identity Cloud also sets OpenID Connect default options for you. You can customize configuration in the app’s client profile.
You can view and manage all your apps in the Applications page of the Identity Cloud Admin UI.
See the quick takes on this page:
In the Identity Cloud Admin UI, go to Applications, and click + New Application.
In the New Application dialog box, choose Consumer, and click Next.
In the New Consumer App dialog box, choose the app type you want to register:
In the Application Name dialog box, enter a name to be displayed in the Applications list.
Click Create Application.
In the Identity Cloud Admin UI, click Applications.
In the Applications list, find the app name, then click More (), and choose Edit.
Edit Consumer application details:
- Client Credentials
AM URL base for OpenID Provider Configuration.
Identifier used to register your client with AM’s authorization server, and then used when your client must authenticate to AM.
- General Settings
Specify a client name to display to the resource owner when the resource owner is asked to authorize client access to protected resources.
Specify the location of your custom logo image file.
Specify a client description to display to the resource owner when the resource owner is asked to authorize client access to protected resources.
Add Sign-in URLs
Custom URL for handling login. Overrides the default OpenAM login page.
Add Sign-out URLs
Custom URL for handling logout. Example: http://client.example.com:8080/openam/XUI/?realm=/#logout.
Specify the set of OAuth 2.0 grant types, also known as grant flows, allowed for this client:
▪︎ Authorization Code (This is the default.)
Instead of requesting authorization directly from the user, your client app or service directs the user to an authorization server (Identity Cloud).
▪︎ Back Channel Request
The client is issued an access token directly. No intermediate credentials (such as an authorization code) are issued. This grant type can potentially pose a security risk. See the "Implicit Grant" section in the ForgeRock AM 7 OAuth 2.0 Guide.
▪︎ Resource Owner Password Credentials
Username and password can be used directly as an authorization grant to obtain an access token. The credentials should only be used when there is a high degree of trust between the user and the client app or service.
▪︎ Client Credentials
Used when the client is acting on its own behalf or requests access to protected resources based previously-arranged authorization.
▪︎ Refresh Token
Credentials used to obtain access tokens.
▪︎ Device Code
Authorizes a client device, such as smarthome thermostat, to access its service on an end user’s behalf. For example, the end user could log in to the thermostat service using a cell phone to enter a code displayed on the thermostat.
Leverages the REST-based services provided by AM’s OAuth 2.0 support. Maintains existing SAML v2.0 federation implementation.
Specify scopes that are to be presented to the resource owner when the resource owner is asked to authorize client access to protected resources. The
openidscope is required.
Edit Advanced Settings:
Add Default Scopes
Scopes to be set automatically when tokens are issued. The
openidscope is required.
Add Response types
Specify the response types that the client uses. The response type value specifies the flow that determine how the ID token and access token are returned to the client. By default, the following response types are available:
code. Specifies that the client application requests an authorization code grant.
token. Specifies that the client application requests an implicit grant type and requests a token from the API.
id_token. Specifies that the client application requests an ID token.
code token. Specifies that the client application requests an access token, access token type, and an authorization code.
token id_token. Specifies that the client application requests an access token, access token type, and an ID token.
code id_token. Specifies that the client application requests an authorization code and an ID token.
code token id_token. Specifies that the client application requests an authorization code, access token, access token type, and an ID token.
Claims can be in entered as simple strings, such as
sub. Or, as a pipe-separated string in the format:
scope|locale|localized description. For example,
name|en|Full name of user.
Allow wildcard ports in redirect URLs
Specify whether AM allows the use of wildcards (* characters) in the redirection URI port to match one or more ports.
Enable this setting, for example, for desktop apps that start a web server on a random free port during the OAuth 2.0 flow.
Authentication method client uses to authenticate to AM.
client_secret_basic. Clients authenticate using the HTTP Basic authentication scheme after receiving a client_secret value.
client_secret_post. Clients authenticate by including the client credentials in the request body after receiving a client_secret value.
private_key_jwt. Clients sign a JSON web token (JWT) with a registered public key.
Token Endpoint Authentication Method (Client Type)
▪︎ Confidential clients can maintain the confidentiality of their credentials. For example, a web application runs on a server where its credentials are protected.
When enabled, the resource owner will not be asked for consent during authorization flows. The OAuth2 Provider must also be configured to allow clients to skip consent.
OAuth 2.0 Mix-Up Mitigation active
Enable this setting only if this OAuth 2.0 client supports the OAuth 2.0 Mix-Up Mitigation draft,
otherwise AM will fail to validate access token requests received from this client.
Add Default ACR values
Default Authentication Context Class Reference values. Specify strings that will be requested as Voluntary Claims by default in all incoming requests.
Add Request URIs
Specify request_uri values that a dynamic client would pre-register.
Client JWT Bearer
A base64-encoded X509 certificate in PEM format used to obtain the client’s JWT bearer public key. The client uses the private key to sign client authentication and access token request JWTs, while AM uses the public key for verification.
Default value is public.
▪︎ Choose pairwise if you want each client to receive a different subject value. This prevents correlation between clients.
▪︎ Choose public if you want each client to receive the same subject value.
Default Max Age
Enable this option to enforce a default maximum age of 10 minutes. If the user session is not currently active, and if more than ten minutes have passed since the user last authenticated, then the user must be authenticated again.
Use Certificate-Bound Access Tokens
Enable this option if you want access tokens issued to this client to be bound to an X.509 certificate. When enabled, access tokens will use the X.509 certificate to authenticate to the
Authorization code lifetime (seconds)
The time an authorization code is valid for.
Default value: 120
Access token lifetime (seconds)
The time an access token is valid for, in seconds
If you set the value to 0, the access token will not be valid. A maximum lifetime of 600 seconds is recommended. Default value: 3600
Refresh token lifetime (seconds)
The time a refresh token is valid for.
If this field is set to -1, the refresh token will never expire. Default value: 604800
JWT token lifetime (seconds)
The amount of time the JWT is valid for. Default value: 3600
Add Display Name
Custom user-facing title. In this example, MyClient.
Add Display Description
User-facing instruction text.
In this example, "This application is requesting the following information:"
registration_access_tokenvalue that you provide when registering the client, and then subsequently, when reading or updating the client profile.
Client Session URI
Specify the relying party (client) URI to which the OpenID Connect Provider sends "session changed" notification. Message is sent using the HTML 5 postMessage API.
Endpoint Response Formats
User info response format
Specify the output format from the
The supported output formats are:
▪︎ User info JSON response format.
▪︎ User info encrypted JWT response format.
▪︎ User info signed JWT response format.
▪︎ User info signed then encrypted response format.
Default: User info JSON response format.
Token introspection response format
Specifies the format of the token introspection response. The possible values for this property are:
▪︎ JSON response format
▪︎ Signed JWT response format
▪︎ Signed then encrypted JWT response format
Signing and Encryption
Public key selector
Select the public key for this client, which comes from the JWKs_URI, manual JWKs, or X.509 field.
JSON Web Key URI
The URI that contains the client public keys in JSON web key format.
JSON Web Key
Raw JSON web key value containing the client public keys.
Client ID Token Public Encryption Key
Base64-encoded public key for encrypting ID tokens.
Enable ID Token Encryption
When enabled, encryption uses the algorithm that the ID token must be encrypted with. Default algorithm value is RSA1_5 (RSAES-PKCS1-V1_5).
When you register an app or service, Identity Cloud automatically sets the optimal configuration for you. To change the default settings, edit the client profile.
Native apps are developed for specific platforms or devices. Examples include the apps you see on mobile phones, and apps dedicated to the MacOS platform.
Single-page apps (SPAs) are OAuth 2.0 clients that run in a user’s web browser.
SPAs use PKCE to verify the client because SPAs do not have a way to secure the
PKCE stands for Proof Key Code Exchange, a security standard explained in the IETF specification
"Proof Key for Code Exchange by OAuth Public Clients".
For a deep dive on how ForgeRock implements PKCE for native and SPA apps, see "Authorization Code Grant With PKCE" .
Web apps are OAuth 2.0 clients that run on a web server. End users (resource owners) access web apps using a web browser. The app makes API calls using a server-side programming language. The end user has no access to the OAuth 2.0 client secret, or any access tokens issued by the authorization server.
M2M apps interact with an API, and no user involvement is necessary. The app acts on behalf of itself, and not on behalf of a user. The app can ask for an access token directly without involving a user in the process at all. A smart meter that tracks your utility usage, and wearable devices that gather and communicate health data use services and M2M apps.
Identity Cloud uses OAuth 2.0 and OpenID Connect to protect your apps.
- OAuth 2.0
Identity Cloud provides authorization service in the OAuth 2.0 authorization flow. OAuth 2.0 lets you set up access to your resources without sharing end-user account information. For a deep dive, see RFC6749.
- OpenID Connect
OpenID Connect (OIDC) provides an identity layer on top of OAuth 2.0. OIDC lets a client make assertions about the user’s identity, and their means of authentication. For a deep dive, see the ForgeRock Access Management OpenID Connect 1.0 Guide.
Changing the client profile settings requires a working knowledge of the OAuth 2.0, its grant types, and its components. If no one has given you direction on how to configure the client profile, you’ll want to read up on some basic concepts.
Here are some links to deep dives in the ForgeRock OAuth 2.0 Guide:
Scopes limit your client app’s access to end users' resources. For a deep dive on how scopes work, see the "Scopes" section.
Grant types, also known as grant flows, describe how your app or service access gets an access token. To help you choose one, see the summary of grant types in the "OAuth 2.0 Grant Flows" section.
Claims convey information about the end user to your client app or service. For a deep dive on claims, see the "Claims" section.
Your apps and services use access tokens when making requests on behalf of a user. Tokens provide proof that your app or service is authorized to access the end user’s data. For a deep dive on access tokens, see "AM as the Authorization Server" section.
Keys protect sensitive information Identity Cloud needs to both send and receive. For a deep dive on keys and keystores, see the "Configuring Secrets, Certificates, and Keys" section.