Configure ForgeRock as a Key Manager

MWARE ESB has the capability to support multiple Key Managers at the same time. So with the use of connectors, it is capable of supporting any authorization server as a Key Manager. Additionally, MWARE ESB is prepacked with an inbuilt resident Key Manager.

MWARE ESB can connect to ForgeRock out-of-the-box using the MWARE ESB ForgeRock Connector.

Follow the instructions given below to configure ForgeRock as a third-party Key Manager:

Before you begin

Step 1 - Configure ForgeRock

Follow the instructions given below to configure the ForgeRock Authorization Server to work with MWARE ESB.

Step 1.1 - Configure OAuth 2.0 Provider

  1. Navigate to the URL where the ForgeRock Authorization server is deployed.

  2. Navigate to Realms -> Top Level Realm.

    Note

    The examples and configurations in this guide are based on the root realm named Top level realm, which exists by default.

    ForgeRock realms

  3. Navigate to Root Realm -> Dashboard -> Configure OAuth Provider -> Configure OAuth 2.0 section.

  4. Create an OAuth provider based on the following values.

    Field Value
    Realm /
    Refresh Token Lifetime (seconds) 60
    Authorization Code Lifetime (seconds) 120
    Access Token Lifetime (seconds) 3600
    Issue Refresh Tokens Enabled
    Issue Refresh Tokens on Refreshing Access Tokens Disabled
    Scope Implementation Class org.forgerock.openam.oauth2

    ForgeRock create OAuth Provider

  5. Navigate to Root Realm -> Services add Oauth2 provider as a new service as follows, ForgeRock add OAuth Provider

  6. Configure the scopes and the signing algorithm of the created OAuth 2.0 Provider using the following values.

    Field Value
    Client Registration Scope Whitelist default
    Subject Types supported public
    Default Client Scopes default
    OAuth2 Token Signing Algorithm RS256

    ForgeRock provider advance config

  7. Navigate to the Dynamic client registration tab and configure it to allow dynamic client registration using the following values.

    Field Value
    Require Software Statement for Dynamic Client Registration Disabled
    Required Software Statement Attested Attributes redirect_uris
    Allow Open Dynamic Client Registration Disabled
    Generate Registration Access Tokens Enabled
    Scope to give access to dynamic client registration dynamic_client_registration

    ForgeRock configure dcr

You can configure the other properties of the OAuth 2.0 provider based on your requirements.

Step 1.2 - Configure an OAuth 2.0 client

Create a static OAuth client as follows so that you can use the OAuth client keys for the purpose of dynamic client registration.

  1. Navigate to Realm -> OAuth 2.0 -> Applications -> Add client to create a client.

    Note

    Ensure to add the mentioned two scopes when creating the client because these scopes are required for dynamic client registration and introspection.

    Field Value
    Client ID amAdmin
    Client secret Enter a value of your choice.
    Scope(s) am-introspect-all-tokens
    dynamic_client_registration

    ForgeRock add client

  2. Navigate to the above created client under Applications -> Client ID of the App -> Core -> Access Token LifeTime.

  3. Set a long value for the Access Token LifeTime to obtain a long living registration access token. You will use this token to register and update clients dynamically.

  4. Navigate to the Advanced tab and configure the client_credential grant type that you need to use to obtain the access token.

    ForgeRock client grant

If you want to work with scopes, then you need to assign the relevant scopes to the relevant OAuth clients beforehand.

Step 2 - Configure MWARE ESB

Follow the instructions given below to configure MWARE ESB to work with the ForgeRock Authorization Server.

  1. Start MWARE ESB.

    <API-M_HOME> refers to the root folder of the extracted MWARE ESB distribution.

  2. Add a Key Manager.

    1. Sign in to the Admin Portal.

      https://<hostname>:9443/admin

    2. Click Key Manager and then click Add Key Manager.

      Add Key Manger

    3. Add the following configuration to add a new Key Manager.

      Add ForgeRock configurations

      Add ForgeRock configurations

      Add ForgeRock configurations

      Add ForgeRock configurations

      The following table provides definitions for each of the configurations.

      Configuration Description
      Name The name of the authorization server. Mandatory
      Display Name A name to display on the UI. Mandatory
      Description A brief description of the Key Manager. Optional
      Key Manager Type The type of Key Manager to be selected. Mandatory
      Well-known-url The well-known URL of the authorization server (Key Manager).
      If the well-known URL is provided, other endpoints can be imported.
      Optional
      Issuer The issuer that consumes or validates the access tokens
      Example:
      http://localhost:8080/openam/oauth2
      Mandatory
      Key Manager Endpoints
      Client Registration Endpoint The endpoint to verify the identity and obtain profile information of the end-user based on the authentication performed by an authorization server.
      Example:
      http://localhost:8080/openam/oauth2/register
      Mandatory
      Introspection Endpoint The endpoint that allows authorized protected resources to query the authorization server to determine the set of metadata for a given token that was presented to them by an OAuth client.
      Example:
      http://localhost:8080/openam/oauth2/introspect
      Mandatory
      Token Endpoint The endpoint that issues the access tokens.
      Example:
      http://localhost:8080/openam/oauth2/access_token
      Mandatory
      Revoke Endpoint The endpoint that revokes the access tokens. Optional
      Userinfo Endpoint The endpoint that allows clients to verify the identity of the end-user based on the authentication performed by an authorization server, as well as to obtain basic profile information about the end-user. Optional
      Authorize Endpoint The endpoint that is used to obtain an authorization grant from the resource owner via user-agent redirection. Optional
      Scope Management Endpoint The endpoint that is used to manage the scopes. Optional
      Connector Configurations
      Client ID The client Id of the static client to invoke the introspection endpoint. Mandatory
      Client Secret The client secret of the static client to invoke the introspection endpoint. Mandatory
      Claim URIs Provide the claim URIs for the consumer key and the scopes.
      Consumer Key Claim URI The claim URI for the consumer key. Optional
      Scopes Claim URI The claim URI for scopes. Optional
      Grant Types The supported grant types. Optional
      Certificates
      PEM Either copy and paste the certificate in PEM format or upload the PEM file. Optional
      JWKS The JSON Web Key Set (JWKS) endpoint is a read-only endpoint. This URL returns ForgeRock's public key set in JSON web key set format. This contains the signing key(s) the Relying Party (RP) uses to validate signatures from ForgeRock. Optional
      Advanced Configurations Token Generation
      Token Generation Enables token generation via the authorization server. Optional
      Out Of Band Provisioning This enables the provisioning of Auth clients that have been created without the use of the Developer Portal, such as previously created Auth clients. Optional
      Oauth App Creation This enables the creation of Auth clients. Optional
      Token Validation Method The method used to validate the JWT signature.
      Self Validate JWT The kid value is used to validate the JWT token signature. If the kid value is not present, gateway_certificate_alias is used. Optional
      Use introspect The JWKS endpoint is used to validate the JWT token signature. If this option is used to validate the tokens it is mandatory to add a Token Handling Option. Optional
      Token Handling Options Provides a way to validate the token for this particular authorization server. This is mandatory if the Token Validation Method is introspect
      For Forgerock if its JWT it is required to specify a claim mapping as a unique identifier and If its REFERENCE its required to set a regular expression for the length of the token.
      Example For JWT
      Claim Key : iss
      Claim Value : http://loccbcalhost:8080/openam/oauth2
      Example for Reference
      {27}
      REFERENCE The tokens matching a specific regular expression (regEx) is validated. Optional
      JWT The tokens matching a specific JWT is validated. Optional
      CUSTOM The token matching a custom pattern is validated. Optional
      Claim Mappings Local and remote claim mapping. Optional

Step 3 - Generate keys using the ForgeRock Key Manager

  1. Sign in to the Developer Portal.

    https://<hostname>:9443/devportal

  2. Click Applications.

  3. Create a new application or use the default application.
  4. Click Production Keys.

    ForgeRock Developer Portal generate keys

  5. Click Generate Keys.

Top