Deprecated application management
|The topics in this section are for tenants created before January 12, 2023. Refer to Application management migration FAQ.|
Your applications act as clients to Identity Cloud. ForgeRock uses both OAuth 2.0 and OpenID Connect protocols to protect your applications which act as clients to Identity Cloud. When you register a supported application or service, Identity Cloud sets the OAuth 2.0 grant type based on the type of application you’re registering. Identity Cloud also sets OpenID Connect default options for you. You can customize configuration in the application’s client profile.
To get started, first register your application or service to your tenant. Then, create a client profile for the application or service.
You can view and manage all your applications on the Applications page of the Identity Cloud admin UI.
|The Identity Cloud admin UI supports a maximum of 500 applications.|
Register an application or service
In the Identity Cloud admin UI, go to Applications, and click + Add Application.
In the New Consumer App dialog box, choose the application type you want to register:
In the Web Application Credentials dialog box, enter a Client ID to be displayed in the Applications list, and if shown, enter a Client Secret.
Click Create Application.
Create a client profile
In the Identity Cloud admin UI, click Applications.
In the Applications list, find the application name, then click More (), and choose Edit.
Review read-only 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.
Password used to register your client with AM’s authorization server, and then used when your client must authenticate to AM.
Edit 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.
App Logo URI
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.
Custom URL for handling login. Overrides the default OpenAM login page.
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
(default) Instead of requesting authorization directly from the user, your client application 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. Refer to Implicit grant.
- 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 application or service.
- Client Credentials
Used when the client acts on its own behalf or requests access to protected resources based on previously-arranged authorization.
- Refresh Token
Credentials used to obtain access tokens.
- Device Code
Authorizes a client device, such as a 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.
- SAML 2.0
Leverages the REST-based services provided by AM’s OAuth 2.0 support. Maintains existing SAML 2.0 federation implementation.
Specify scopes that display to the resource owner when they authorize client access to protected resources.
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 determines 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 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.
The URL configured in the redirection URI must be either localhost, 127.0.01, or ::1. For example, http://localhost:*/, https://127.0.0.1:80*/, or https://[::1]:*443/.
Enable this setting, for example, for desktop applications 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 ten 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:
(default) User info JSON response format.
User info encrypted JWT response format.
User info signed JWT response format.
︎ User info signed then encrypted 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 with which the ID token must be encrypted. Default algorithm value is RSA1_5 (RSAES-PKCS1-V1_5).
Supported application types
When you register an application or service, Identity Cloud automatically sets the optimal configuration for you. To change the default settings, edit the client profile.
Native / SPA
Native applications are developed for specific platforms or devices. Examples include the applications on mobile phones and applications dedicated to the macOS platform.
Single-page applications (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 applications, refer to Authorization code grant with PKCE.
Web applications are OAuth 2.0 clients that run on a web server. End users (resource owners) access web applications using a web browser. The application 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.
Machine-to-machine (M2M) applications interact with an API and no user involvement is necessary. The application can ask for an access token without involving a user in the process. A smart meter that tracks your utility usage and wearable devices that gather and communicate health data use services and M2M applications.
OAuth 2.0 and OpenID Connect
Identity Cloud uses OAuth 2.0 and OpenID Connect to protect your applications.
Identity Cloud provides an 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, refer to RFC6749.
You may encounter domain validation prompts when using forgeblocks.com and id.forgerock.io domains as redirect URLs in your Google OAuth 2.0 applications. To resolve this, you must use a custom domain, and then set up domain verification with Google.
You may encounter "No provider found" errors when using forgeblocks.com and id.forgerock.io domains as redirect URLs in your OAuth 2.0 applications. To resolve this, either modify the redirect URL to include a realm identifier, or use a custom domain:
A custom domain acts as a realm DNS alias, so when it is used as a redirect URL, Identity Cloud implicitly knows which realm to use.
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, refer to OIDC grant flows.
What’s in the client profile
Changing the client profile settings requires a working knowledge of 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.
Scopes limit your client application’s access to end users' resources. For a deep dive on how scopes work, refer to Scopes.
Grant types, also known as grant flows, describe how your application or service access gets an access token. To choose one, refer to the summary of grant types in OAuth 2.0 grant flows.
Claims convey information about the end user to your client application or service. For a deep dive on claims, refer to the Claims.
Your applications and services use access tokens when making requests on behalf of a user. Tokens provide proof that your application or service is authorized to access the end user’s data. For a deep dive on access tokens, refer to Identity Cloud as authorization server.
Keys protect sensitive information that Identity Cloud needs to both send and receive. You can store keys in ESV secrets, then use them in OAuth 2.0 authentication flows by mapping the ESVs to secret IDs.