Managing OAuth Client Applications

A client application that sends API requests to Access Manager must be registered with Access Manager Identity Server. You can register a client application by using the API calls, Administration Console, or the Identity Server user portal page.

Prerequisites for managing client applications include:

  • User Portal: Define any of the following roles in the OAuth policy for the user:

    • NAM_OAUTH2_DEVELOPER: Allows the user to view and modify the client registration details of the applications that the user has registered on the portal.

    • NAM_OAUTH2_ADMIN: Allows the user to view and modify the client registration details of all the client applications that are registered with Access Manager.

    The user (an application developer) must log in to Identity Server for registering a client application. The My Applications tab lists all applications that the user has added. The user can view details, modify, and delete applications.

  • API calls: Define the NAM_OAUTH2_ADMIN role in the OAuth policy for the user.

  • Administration Console: The user must request the Access Manager administrator to register a client application using Administration Console.

Registering OAuth Client Applications

  1. Click Devices > Identity Server > Edit > OAuth & OpenID Connect > Client Applications > Register New Client.

  2. In Client Configuration, select Enable Client and specify the following details:

    Field

    Description

    Client Name

    Specify the name of the client application.

    Client Type

    Select whether this is a web-based or a desktop client application.

    If you select Native/Desktop, Use Persistent Cookie gets displayed.

    You can select Use Persistent Cookie to allow single sign-on for a user who uses client applications on a desktop or a mobile.

    For example, a user accesses client A using the credentials and gets authenticated. Client A receives a refresh token and an access token. Now, user accesses client B immediately or after few days. If Use Persistent Cookie is enabled for client B, then the client uses the persistent cookie to retrieve the token and authenticate the user. Hence, client B will get authenticated automatically.

    If Use Persistent Cookie is not selected for client B configuration, user has to provide credentials to retrieve refresh token and access token.

    NOTE:When a client application uses the Authorization Code flow, the request must contain the revocation_id parameter along with the clientID parameter. The revocation_id value can be the device ID.

    If revocation_id is not included in the request, the user cannot use the persistent cookie to authenticate from client B.

    Login Redirect URIs

    Specify the URI based on the Client type.

    Specify the URIs that Identity Server uses to send the authorization code and implicit requests.

    For web-based applications, specify the client type in this format: https://client.example.org/callback

    For native/desktop applications, specify the client type in any one of the following formats:

    https://www.namnetiq.in/

    x-com.netiq.sample://www.namnetiq.in/

    urn:ietf:wg:oauth:2.0:oob (supported only for the authorization code flow).

    NOTE:The limitation on the attribute in the eDirectory (Octet string) is 64K of data.

    Grants Required

    Select the grant types required for this client application. Available grant types include:

    • Authorization Code (default)

    • Implicit

    • Resource Owner Credentials

    • Client Credentials

    • SAML 2.0 Assertion

    Token Types

    Select the type of tokens that the authorization server will send to this client application:

    • Code

    • ID Token

    • Refresh Token

    • Access Token

    Refresh Token

    Select Always Issue New Token to issue a new refresh token for each refresh token request.

  3. (Conditional) If you selected ID Token in Client Configuration > Token Types, click OpenID Connect Configuration, and configure the following settings:

    Field

    Description

    JSON Web Key Set URI

    To encrypt an ID token using the public key of a client application, specify the client’s JSON Web Key Set URI. This is required to retrieve the encryption key that are defined in the JSON Web Key Set URI.

    ID Token Signed Response Algorithm

    This is a mandatory field for issuing an ID token to a client application. If you require Identity Server to sign the ID token using a JWS algorithm, select the appropriate signing algorithm. The signing algorithm depends on the certificate that is specified under Certificate Settings in the Global Settings page.

    For example, if Signing Algorithm is RS256 on the Global Settings page, select RS256.

    NOTE:If you select None, the ID token is sent as an unsigned token. Ensure to select this option only if you trust the integrity of an unsigned ID token.

    ID Token Encrypted Response Algorithm

    Specify the JWE algorithm to encrypt the key of the encrypted content in the ID token.

    NOTE:Ensure to specify the algorithm that is defined in the specified JSON Web Key Set URI so that the client application can use the private key to decrypt the token.

    ID Token Encrypted Response Enc

    This field gets auto-populated based on the algorithm specified in ID Token Encrypted Response Algorithm. JWE enc algorithm is required to encrypt the content of the ID token.

  4. Click Token Configuration. The timeout settings here overrides the global settings.

    Field

    Description

    Authorization Code Timeout

    Specify the duration after which the authorization code will expire.

    Access Token and ID Token Timeout

    Specify the duration after which access and ID tokens will expire.

    Refresh Token Timeout

    Specify the duration after which the refresh token will expire.

    Access Token and Refresh Token Format

    It is recommended to select the JWT token. However, you can select any of the following options:

      • Default: The format is set to binary or JWT based on the value you set in the OAUTH TOKENS IN BINARY FORMAT property of Identity Server.

        If OAUTH TOKENS IN BINARY FORMAT is

        • set to true, the format is binary.

        • set to false, the format is JWT.

        • unspecified, the format is JWT.

        When you update the value or add OAUTH TOKENS IN BINARY FORMAT, any client application with the Default option receives the tokens (access and refresh) in the modified format.

      • Binary: The token format is always binary irrespective of the value set in the OAUTH TOKENS IN BINARY FORMAT property of Identity Server.

        Binary tokens are always encrypted using Access Manager keys. To validate a token, the resource server uses Access Manager UserInfo and TokenInfo endpoints.

        If tokens are in the binary format, the following features are unavailable:

        • Encrypting an access token using the resource server key

        • Revoking a refresh token

        The Binary option is recommended only if you have an existing client application that cannot use JWT because some browsers restrict the length of the parameter values.

      • JWT: Recommended option. The token format is always JWT irrespective of the value set in the OAUTH TOKENS IN BINARY FORMAT property of Identity Server.

  5. Click Logout Configuration and specify the following details:

    Field

    Description

    Front-Channel Logout URI

    Specify the client application logout URL that Identity Server will use to trigger logout at the client application

    Enable Session Token

    When you enable this option, Identity Server includes session ID and issuer query parameters in the client application’s logout URL.

    This session ID is a co-relation ID that the client application uses to identify the unique user sessions established at Identity Server. It is not the Identity Server user session ID.

    Logout Redirect URIs

    (Applicable only for the Relying Party initiated logout request)

    Specify the URL to which the user will be redirected after logout. For example, https://client.example.org/logout.

    NOTE:The logout request (end_session) must include id_token_hint and post_logout_redirect_uri request parameters. Else, Identity Server does not redirect the user to the post-logout page.

    For information about the OIDC front-channel logout support, see OIDC Front-Channel Logout.

  6. Click Consent Screen Configuration and specify the following details:

    Field

    Description

    Client Logo URL

    Specify the URL of the logo that you want to include on the consent page.

    Privacy Policy URL

    Specify the URL of the privacy policy you want to include on the consent page. You can define your own privacy policy.

    Terms of Service URL

    Specify the URL of the terms of service.

    Contacts

    Specify the email addresses of people related to this client application.

  7. Click Authorized JavaScript origins (CORS) and add Domains. Domains configured here can access restricted resources available on the client application. Do not specify the port if you are using port 80 or 443.

    For example, beem://www.test.com:port, fb://app.local.url:port, https://namapp.com:port

  8. Click Authentication Contract to configure authentication contracts for the client application. This configuration is available in Access Manager 5.0 Service Pack 1 and later.

    When you configure authentication contracts for a client application using here, this server-side configuration takes precedence. After this configuration, the ACR value in the request is ignored, and contracts are used for authentication.

    In Available Contract, select contracts that you want to be used for authentication and move these to Satisfy Contract. By default, the first contract in the list is used. For the Resource Owner Credentials flow, if the identity provider does not support that contract, then the next contract in the list is used for authentication.

  9. Click Scope Configuration and select the required scopes for the client application.

    Field

    Description

    Scopes

    Select scopes that the client application can use.The client application can use only the scopes specified here. If the client application sends a non-configured scope, it will not be considered.

  10. Click Register Client.

    Identity Server assigns a client ID and a client secret. To see this ID and secret, go to the Client Application page and click the view icon for this client application.

Modifying Registered Client Applications

  1. Click Devices > Identity Server > Edit > OAuth & OpenID Connect > Client Applications.

    The page lists all registered client applications along with the following details:

    Field

    Description

    Client Application

    Name of the registered application

    Application Type

    Type of the application: Web or Native/Desktop

    Created By

    User name of the person who has registered the client application.

    Actions

    List of icons associated with actions that you can perform on an application. You can perform the following actions:

    • View details of a registered client application

    • Modify details of a registered client application

    • Delete a registered client application

    • Disable a client application.

      Disabling a client application does not delete it, and it will not revoke any token issued earlier. When you enable the client application again, the token issued earlier does not expire and will continue to work.

  2. Click the edit icon under Actions. Modify the details as required. For information about fields, see Registering OAuth Client Applications.

  3. Click Modify Client.