Identity Cloud

Register a custom application

The topics in this section are for tenants created on or after January 12, 2023. Refer to Application management migration FAQ.

You can create an application without using a template. Then, configure application-specific details, including application name, icon, and other information. This allows for extensibility and flexibility to ensure all the applications across your organization can integrate with Identity Cloud.

You can integrate Identity Cloud with OpenID Connect (OIDC) and SAML applications.

Provisioning is not a custom applications feature.
ui workforce register custom application

Register a custom application or service

For more information about OpenID Connect (OIDC) applications, refer to Application management (current).

  1. On the Identity Cloud admin UI, go to Applications, and click Custom Application.

  2. On the Add a Custom Application dialog box, choose one of the following:

    • OIDC - OpenID Connect

    • SAML.

    • Bookmark.

  3. Click Next.

OpenID Connect (OIDC)

  1. Choose the application type you want to register. For details, refer to OIDC OpenID Connect applications.

    • Native / SPA

    • Web

    • Service

  2. Click Next.

  3. On the Application Details page, configure the following fields:

    • Name: The name of the application.

    • Description: A description of the application.

    • Application Owners: The owners of the application.

    • App Logo URI: The URl of the location of the application logo.

  4. Click Next.

  5. Enter a Client ID to display in the Applications list, and if shown, enter a Client Secret. Remember the client secret. If the client secret is forgotten, you must reset it on the Sign On tab on the edit application page.

  6. Click Create Application.

OAuth2.0 - Set up single sign-on

  1. On the Sign On tab, set or review the following credentials:

    Client Credentials
    Field Description

    Client ID

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

    (Web and Service) Client Secret

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

    Discovery URI

    AM URL base for OpenID Provider Configuration.
    Default: http://openam.example.com:8088/openam/oauth2
    Show advanced settings
    Field Description

    OAuth2.0 Authenticate Endpoint

    The endpoint for OAuth2.0 authentication.

    OAuth2.0 Authorization Endpoint

    The endpoint for OAuth2.0 authorization.

    OAuth2.0 Token Endpoint

    The endpoint the application uses to get an access token or a refresh token.

    OAuth2.0 Introspect Endpoint

    The endpoint that returns validation information for identifier-based access tokens.

    OAuth2.0 Userinfo Endpoint

    The endpoint that returns information about an end user.

    OAuth2.0 Identity Token Endpoint

    The endpoint that returns the identity token.
    General Settings
    Field Description

    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:

    Scopes

    Specify scopes presented to the resource owner when the resource owner is asked to authorize client access to protected resources. The openid scope is required.

  2. Review Advanced Settings:

    Access
    Field Description

    Default Scopes

    Scopes set automatically when tokens are issued. The openid scope is required.

    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

    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 end 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
    Field Description

    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.

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

    Default ACR values

    Default Authentication Context Class Reference values. Specify strings that will be requested as Voluntary Claims by default in all incoming requests.

    Request URIs

    Specify request_uri values that a dynamic client pre-registers.

    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 end user session is not currently active, and if more than 10 minutes have passed since the end user last authenticated, then the end user must authenticate 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
    Field Description

    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
    Field Description

    Display Name

    Custom user-facing title. In this example, MyClient.

    Display Description

    User-facing instruction text. In this example, "This application is requesting the following information:"

    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
    Field Description

    Access Token

    Specify the registration_access_token value you provided when registering the client, and then subsequently, when reading or updating the client profile.
    Session Management
    Field Description

    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
    Field Description

    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
    Field Description

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

  3. Click Save.

SAML 2.0

  1. On the Application Details page, configure the following fields:

    • Name: The name of the application.

    • Description: A description of the application.

    • Application Owners: The owners of the application.

    • App Logo URI: The URl of the location of the application logo.

  2. Click Create Application.

SAML 2.0 - Set up single sign-on

  1. Click the Sign On tab.

  2. Click Set Up SSO.

  3. If you have set up multiple domains, in the Select a domain drop-down field, select a domain to use for sign-on.

  4. Click Next.

  5. Follow the steps on the Set Up Single Sign-on page.

  6. Click Next.

  7. Click Save.

  8. To view IdP metadata for the application, click View IdP Metadata.

  9. To update the application provider metadata, click Update Metadata.

  10. To download a certificate, click Download Certificate.

  11. Review or if desired, copy the following credentials:

    Endpoints
    Field Description

    IDP-Initiated Login Endpoint

    The login endpoint initiated by the IDP.

  12. Review or edit the following:

    Settings
    Field Description

    Single Sign On URL

    The location where the SAML assertion is sent with an HTTP POST. This is often referred to as the SAML Assertion Consumer Service (ACS) URL for your application.

    Audience URI (SP Entity ID)

    The application-defined unique identifier that is the intended audience of the SAML assertion. This is most often the SP Entity ID of your application.

    Response

    Signed or Unsigned.

    Assertion Signature

    Signed or Unsigned.

  13. To set advanced settings, click Show advanced settings, and set or review the following:

    Field Description

    Name ID Format

    Identifies the SAML processing rules and constraints for the assertion’s subject statement. Use the default value of Unspecified unless the application explicitly requires a specific format.

    Assertion Encryption

    Encrypted or Unencrypted.

    Single Logout

    Enable to allow the application to initiate Single Logout. Then in the Single Logout URL, enter the location where the logout response is sent.

    Attribute Statements (optional)

    Insert statements into the SAML assertions shared with your application. Set the Name, Name Format, and Value for each statement. Click the plus sign to add a new statement.

  14. Click Save.

Bookmark

You can now register a bookmark application. For example, OneNote, Evernote, Google Bookmarks, or raindrop.io - to direct users to specific URLs. A bookmark application displays shortcut links on dashboards. When you click one of the links, the browser opens a new tab.

  1. On the Application Details page, configure the following fields:

    • Name: The name of the application.

    • Description: A description of the application.

    • Application Owners: The owners of the application.

    • URL: The sign-in URL for the application.

    • App Logo URI: The URl of the location of the application logo.

  2. Click Create Application.

Next step

Copyright © 2010-2024 ForgeRock, all rights reserved.