Manage Applications

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.

To get started, first register your application or service to your tenant. Then, create a client profile for the app or service.

You can view and manage all your apps in the Applications page of the Admin UI.

See the quick takes on this page:

Register an app or service

  1. In the Admin UI, go to Applications, and click + New Application.

  2. In the New Application dialog box, choose Consumer, and click Next.

  3. In the New Consumer App dialog box, choose the app type you want to register:

  4. In the Application Name dialog box, enter a name to be displayed in the Applications list.

  5. Click Create Application.

Create a client profile

  1. In the Admin UI, click Applications.

  2. In the Applications list, find the app name, then click More (), and choose Edit.

  3. Edit Consumer application details:

    Application Details
    Client Credentials

    Discovery URI

    AM URL base for OpenID Provider Configuration.
    Default: http://openam.example.com:8088/openam/oauth2

    Client ID

    Identifier used to register your client with AM’s authorization server, and then used when your client must authenticate to AM.

    General Settings

    Name

    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

    Specify the location of your custom logo image file.

    Description

    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.

    Grant Types

    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

    ▪︎ Implicit
    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.

    ▪︎ SAML2
    Leverages the REST-based services provided by AM’s OAuth 2.0 support. Maintains existing SAML v2.0 federation implementation.

    Add Scopes

    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 openid scope is required.

  4. Edit Advanced Settings:

    Access

    Add Default Scopes

    Scopes to be set automatically when tokens are issued. The openid scope 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.

    Add Claims

    Claims can be in entered as simple strings, such as name, email, profile, or 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 apps that start a web server on a random free port during the OAuth 2.0 flow.

    Authentication

    Token Endpoint
    Authentication Method

    Authentication method client uses to authenticate to AM.
    Choose one:

    ▪︎ 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.

    ▪︎ Public clients run the risk of exposing their passwords to a host or user agent. For example, a JavaScript client running in a browser may be accessible to the public at large.

    Implied Consent

    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
    Public Key

    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.

    Subject Type

    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 access_token endpoint.

    Token Lifetimes

    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

    Consent Screen

    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:"

    Add Privacy Policy URI

    URI containing the client’s privacy policy documentation. The URI is displayed as a link in the consent page.
     

    200

    Client Management

    Access Token

    Specify the registration_access_token value that you provide when registering the client, and then subsequently, when reading or updating the client profile.

    Session Management

    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 userinfo endpoint.
    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).

  5. Click Save.

Supported application types

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 / SPA Apps with PKCE

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 client_secret value. 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

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.

Service / M2M Apps

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.

OAuth 2.0 and OpenID Connect

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.  

What’s in the client profile

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

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

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

Claims convey information about the end user to your client app or service. For a deep dive on claims, see the "Claims" section.  

Access tokens

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

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.