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

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, http://host1.example.com:8080/openam/oauth2). 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: "iss" (Issuer) Claim and "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, http://lb.example.com.
     • Extension class name - enter the following value: org.forgerock.openam.services.baseurl.BaseURLProvider
     • 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 BaseUrlSource, ensuring you set the properties as follows: source Fixed value fixedValue [loadbalancerURL] extensionClassName org.forgerock.openam.services.baseurl.BaseURLProvider  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-extension-class=org.forgerock.openam.services.baseurl.BaseURLProvider 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": "http://lb.example.com/openam/oauth2/employees"

See Also

Configuring the Base URL Source Service

What JWTs are generated or accepted in Identity Cloud and AM?

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

Related Training

N/A

Related Issue Tracker IDs

N/A