How To
ForgeRock Identity Platform
Does not apply to Identity Cloud

How do I modify the OIDC issuer ID or audience in a multi-server AM (All versions) environment?

Last updated Feb 24, 2021

The purpose of this article is to provide information on modifying the OIDC issuer ID or audience contained in the JWT when you have a multi-server AM environment. This amendment is needed because the JWT must contain the issuer ID or audience applicable to the instance.

Background Information

A JWT can define the author of the JWT (Issuer ID) and the recipients of the JWT (audience):

  • Acting as the client application, your issuer ID is the client ID. This means:
    • when you send a JWT, you set the issuer ID to the client ID.
    • when you receive a JWT, you should check that the audience contains the client ID.
  • Acting as AM, the issuer ID is the Issuer URL, which is the oauth2 endpoint (for example, This means:
    • when you receive a JWT that has been generated by AM (such as an ID token), you need to check that the issuer ID is the appropriate URL.
    • when you send a JWT to AM (such as the client credential JWT or request parameter) you should ensure the audience contains the AM issuer ID (URL).

See the standards for further information about these attributes: RFC 7519 › "iss" (Issuer) Claim and RFC 7519 › "aud" (Audience) Claim.

Modifying the OIDC issuer and audience

You can modify the OIDC audience as follows for a multi-instance deployment; this process also changes the issuer ID:

  1. Add and configure the Base URL Source service using the console, Amster or ssoadm:
    • Console: Navigate to: Realms > [Realm Name] > Services > Add a Service > Base URL Source and click Create. Complete the following fields:
      • Base URL Source - set to FIXED_VALUE.
      • Fixed value base URL - enter the URL of the load balancer in front of your AM instances, for example,
      • Extension class name - enter the following value:
      • Context path - enter the deployment URI that you specified when you installed AM (this is /openam by default).
    • Amster: Use the create command with the BaseUrlSource entity as described in Entity Reference › BaseUrlSource, ensuring you set the properties as follows: source Fixed value fixedValue [loadbalancerURL] extensionClassName contextPath [contextPath] replacing [loadbalancerURL] and [contextPath] with appropriate values.
    • ssoadm:
      1. Create a data file (called DATA_FILE to match the next command) with the following contents: base-url-source=FIXED_VALUE base-url-fixed-value=[loadbalancerURL] base-url-context-path=[contextPath] replacing [loadbalancerURL] and [contextPath] with appropriate values.
      2. Enter the following command: $ ./ssoadm add-svc-realm -s amRealmBaseURL -e [realmname] -u [adminID] -f [passwordfile] -D DATA_FILE replacing [realmname], [adminID] and [passwordfile] with appropriate values.
  2. Set the "aud" in the inbound Request Object JWT. This value should consist of the fixed value base URL + the specified context path + /oauth2 + /realm. The /realm element is not required if this is configured in the top level realm. For example, based on the example values above where this is configured in the employees realm using the default context path, it would be: "aud": ""

See Also

Security Guide › Configuring the Base URL Source Service

How do I understand the OAuth2 and OIDC JWTs that are generated or accepted by Identity Cloud or AM (All versions)?

AM (All versions) redirects to HTTP when deployed on Apache Tomcat with a load balancer doing SSL/TLS offloading

Related Training


Related Issue Tracker IDs


Copyright and Trademarks Copyright © 2021 ForgeRock, all rights reserved.