How-tos

Configuring OAuth Settings for Workspaces

Instructions on how to configure your workspaces in Cloudentity

Configure your Cloudentity Workspace

  1. Select Auth Settings from the sidebar in the admin portal.

  2. Proceed to configuring the server. The configuration is divided into the following parts:

    • Auth Settings where you configure the server grant types, allowed authentication methods, and client registration.
    • Tokens where you configure all things token-related, such as token type, lifetime, signature and encryption, as well as claims exposed in the token.
    • Consent where you configure the consent page for the end users.
    • Authorization where you can assign the policies authorizing the server to issue a token in specific cases.

Configure Auth Settings

  1. Go to Auth Settings > OAuth.

Configure Grant Types

  1. Go to the General tab.

    General View

    There are a few sections in the General view that need to be configured to optimize protection and security exercised within your workspace. They are

    • Allowed grant types
    • Pushed Authorization Request (PAR) enforcement
    • Scopes
  2. Under the Allowed grant types section, enable specific grant types by selecting the corresponding checkboxes.

    Grant Types

    There are a few grant types that you can allow in your workspace for an application to acquire an access token. They are

    • Authorization code
    • Client credentials
    • Refresh token
    • Resource owner password
    • Implicit
    • JWT Bearer
    • Token Exchange
    • CIBA
    • Device Authorization (formerly known as Device Flow)

    Enforce PKCE

    For the Authorization code grant type, you can enable two additional options:

    • Enforce PKCE for all clients
    • Enforce PKCE for public clients.
  3. Select Enforce PAR to enforce pushed authorization requests in this server. For more information, see Pushed Authorization Requests.

Configure Client Authentication

  1. Go to Client Authentication > Allowed token endpoint authentication methods section and enable specific methods by selecting the corresponding checkboxes.

    Token Endpoint Authentication Methods

    There are a few token endpoint authentication methods that you can allow in your workspace. They are

    • Client secret with three flavors to choose from: Client Secret Basic, Client Secret JWT, and Client Secret Post.
    • JSON web token (Private Key JWT)
    • TLS client authentication with two options to choose from: TLS Client Auth and Self Signed TLS Client Auth.

    Note

    Select None to allow for creating applications without authorization. This option does not prevent you from enabling the other methods.

  2. In the Client Authentication view, navigate to the TLS Client Authentication section and enable the TLS Client Auth and/or the Self Signed TLS Client Auth methods by selecting the corresponding checkboxes.

    Note

    You can add your trusted client certificates. Privacy-enhanced mail (PEM) encoded root CA certificates are used for client mTLS token endpoint authentication. If you do not add any trusted client certificates, system root Certificate Authority (CA) certificates are used instead.

Configure Dynamic Client Registration

  1. Go to Client registration and select Enable dynamic client registration.

  2. Select a dynamic client registration policy from the dropdown menu or create a new DCR policy.

    Note

    This step is optional: You can leave out dynamic client registration policy if you do not need any access restrictions for DCR.

  3. Optionally, enable Protect by access token and/or Protect by software statement and/or Signed Request Body by selecting the corresponding toggle switches.

Note

For enabled features, choose how to specify your JSON WEB KEY SETS and provide either a code value for your JWKS or a link to it.

Read More

For more information on configuring DCR, see Configuring Dynamic Client Registration with authorization servers.

Result

You have successfully configured your Dynamic Client Registration.

Configure Token Settings

  1. Select Token under Auth Settings.

  2. In the Type view, select the access token type:

    • JSON WEB TOKEN (a signed token that contains entity-specific data and can be validated in place)

      or

    • OPAQUE (a random string that requires introspection to be validated / get entity-specific data)

  3. Go to TTL and set Time to Live (TTL) for tokens, authorization code, and cookie max age. Save your changes.

  4. Go to Signing and encryption.

  5. Enable the token encryption if necessary (this is required by the FAPI standard).

  6. Set up the signing key rotation settings. For more information, read Key rotation.

  7. Go to Claims.

  8. Choose between the legacy and hash subject format.

    For the legacy format, the sub value is populated with an identifier provided by the IDP and stored as a plaintext. If you have multiple IDPs configured in your workspace, identifier collision may happen.

    For the hash format, the identifier from the IDP is prefixed with the identifier of the Identity Source and one-way hashed to avoid sub collision and make it impossible to read (for improved security of Personally Identifiable Information (PII)).

    Getting the Original Subject Value

    If you set the subject format to hash and you need to retrieve the original value (plain text) of the sub claim, inject a custom claim to the access token or call the Cloudentity OAuth 2.0 Introspection endpoint. By default, Cloudentity tenants' authentication context contain the idp_sub attribute that can be used to provide the source (original sub) for the custom claim. To retrieve the subject, add a custom claim to access tokens with a name of your choice, source type set to AuthN Context, and Source Path set to IDP subject attribute. See example below.

    IDP subject custom claim

    If the idp_sub attribute is not present in the authentication context defined in the tenanant configuration, add it manually.

  9. Set up Allowed Subject Identifier Types.

    Subject identifier types

    Cloudentity supports the Public and Pairwise subject identifier types.

    The Pairwise subject identifier represents one user with unique identifiers to different clients. Each Pairwise subject identifier is assigned to a specific user-client pair for enhancing the user privacy.

  10. Configure claims exposed with tokens issued to the client. For detailed information on claim configuration, read Configuring claims for ID tokens and access tokens.

The consent screen is a prompt displayed to the end user when an application requests access to the user’s private data.

  1. Go to Auth Settings > Consent.

  2. In the Consent screen view, select the type of the consent page that you’d like to use:

    • OAUTH CONSENT based on default scopes or

    • OPEN BANKING CONSENT for specialized use cases, such as Open Banking.

  3. Select Save changes to apply your choice.

Note

The Open Banking consent page requires configuration. For instructions on how to integrate the custom consent page with Cloudentity, see Configuring the custom consent page.

Open Banking Consent

If you choose OPEN BANKING CONSENT for your workspace, enter the consent URL in the field provided and select Save changes to proceed. For detailed instructions on how to enable OPEN BANKING CONSENT in the workspace, see Enabling the custom consent page.

Configure Authorization Settings

  1. Go to Auth Settings > Authorization

  2. Configure the Workspace Authorization Policy settings.

    1. Select Client registration policy from the dropdown menu to define the policy that validates developer attributes before they can register applications.

    2. Select Token issue policy from the dropdown menu to define the policy that validates user attributes before they can be provided with a token.

    3. Select Machine token policy from the dropdown menu to define the policy that validates machine-to-machine application attributes before they can be provided with a token.

    Note

    For each policy type, you can either select an existing policy or create a new one. For information on creating policies, see Creating policies.