PingOne Advanced Identity Cloud

Application management (legacy)

The topics in this section are for tenants created before January 12, 2023. Learn more in Application management migration FAQ.

Your applications act as clients to PingOne Advanced Identity Cloud. Ping Identity uses both OAuth 2.0 and OpenID Connect protocols to protect your applications. When you register a supported application or service, Advanced Identity Cloud sets the OAuth 2.0 grant type based on the type of application you’re registering. Advanced 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 Advanced Identity Cloud admin UI.

The Advanced Identity Cloud admin UI supports a maximum of 500 applications.

Register an application or service

  1. In the Advanced Identity Cloud admin UI, go to Applications, and click + Add Application.

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

  3. 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.

  4. Click Create Application.

Create a client profile

  1. In the Advanced Identity Cloud admin UI, click Applications.

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

  3. Review read-only Client Credentials:

    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.

    Client Secret

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

  4. Edit General Settings:

    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 URI

    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.

    Sign-in URLs

    Custom URL for handling login. Overrides the default OpenAM login page.

    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

    (default) Instead of requesting authorization directly from the user, your client application or service directs the user to an authorization server (Advanced 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. Learn more in 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.

    Scopes

    Specify scopes that display to the resource owner when they authorize client access to protected resources.

    The openid scope is required.

  5. 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 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.

    Add Claims

    Claims can be 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 applications 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.

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

    • (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.

    ID Token Encryption Public 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).

  6. Click Save.

Supported application types

When you register an application or service, Advanced 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 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 applications, learn more in Authorization code grant with PKCE.

Web

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.

Service

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

Advanced Identity Cloud uses OAuth 2.0 and OpenID Connect to protect your applications.

OAuth 2.0

Advanced 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, learn more in 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 could 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:

  • Incorrect:
    https://<tenant-env-fqdn>/am/oauth2/client/form_post/...

  • Correct:
    https://<tenant-env-fqdn>/am/oauth2/<realm>/client/form_post/...
    or
    https://<custom-domain-fqdn>/am/oauth2/client/form_post/...

A custom domain acts as a realm DNS alias, so when it is used as a redirect URL, Advanced Identity Cloud implicitly knows which realm to use.

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, learn more in 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

Scopes limit your client application’s access to end users' resources. For a deep dive on how scopes work, learn more in Scopes.

Grant types

Grant types, also known as grant flows, describe how your application or service access gets an access token. Learn more about grant types in OAuth 2.0 grant flows.

Claims

Claims convey information about the end user to your client application or service. For a deep dive on claims, learn more in the Claims.

Access tokens

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, learn more in Advanced Identity Cloud as authorization server.

Keys

Keys protect sensitive information that Advanced 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 labels.