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
-
In the Advanced 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 Advanced 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:
Client Credentials
Discovery URI
AM URL base for OpenID Provider Configuration.
Default: http://openam.example.com:8088/openam/oauth2Client 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.
-
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. -
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
, orsub
. 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 MethodAuthentication 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 KeyA 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: 120Access 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: 3600Refresh 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: 604800JWT 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.
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).
-
-
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
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.