How To
ForgeRock Identity Platform
Does not apply to Identity Cloud

How do I set up Realm DNS Aliases in AM (All versions) when CDSSO is configured?

Last updated May 10, 2022

The purpose of this article is to provide information on setting up Realm DNS Aliases in AM when Cross Domain Single Sign On (CDSSO) is configured. It assumes CDSSO is operating correctly and you already have a site configured.

2 readers recommend this article


If you don't already have a site configured, you must add a site to the server before you can add a secondary site URL. Here is an example site configuration:

  • Site URL:
  • Primary server URL:
  • Secondary server URL:

Web Agents

You must update the Web agent to use the site URL (load balancer) as the naming URL. You can do this by editing the com.sun.identity.agents.config.naming.url property in the agent.conf file (located in the /path/to/web_agents/agent_version/instances/Agent_nnn/config directory) or by adding the property in the console by navigating to: Realms > [Realm Name] > Agents > Web > [Agent Name] > Advanced > Custom Properties in the console.

Using the example site configuration above, you would add the following naming URL:

Java Agents

You do not need to do this for Java agents because the site URL is derived instead. See Important Changes to Existing Functionality (Changes to the Java Agent's Startup Sequence) for further information.

Setting up Realm DNS Aliases

Realm DNS aliases are an alternative to using Fully Qualified Domain Names (FQDNs) in AM as they implicitly add the realm to the request. For example, is interpreted as when realm DNS aliases are used.


Realm DNS aliases must be unique; you cannot have the same realm DNS alias configured in more than one realm, this can cause the server to become unresponsive.

You can set up realm DNS aliases as follows when CDSSO is configured:

  1. Add the CDSSO AM URL (sub-realm URL) as a secondary server URL (for example, using either the console or ssoadm:
    • Console: navigate to: Deployment > Sites > [Site Name] > Secondary URLs and add the new secondary server URL.
    • ssoadm: enter the following command: $ ./ssoadm add-site-sec-urls -s [sitename] -u [adminID] -f [passwordfile] -a [secondaryserverURL]replacing [sitename], [adminID], [passwordfile] and [secondaryserverURL] with appropriate values.
  2. Add the CDSSO FQDN as the realm DNS alias for the sub-realm (for example, using either the console or ssoadm:
    • Console: navigate to: Realms > [Realm Name] > Properties > Realm/DNS Aliases and ensure the appropriate DNS aliases are specified.
    • ssoadm: enter the following command: $ ./ssoadm set-realm-attrs -s sunIdentityRepositoryService -e [realmname] -u [adminID] -f [passwordfile] -p -a sunOrganizationAliases=[DNSAlias]replacing [realmname], [adminID], [passwordfile] and [DNSAlias] with appropriate values.
  3. Add the primary domain to the list of cookie domains (for example, using either the console or ssoadm:
    • Console: navigate to: Configure > Global Services > Platform > Cookie Domains and add the primary domain.
    • ssoadm: enter the following command: $ ./ssoadm set-attr-defs -s iPlanetAMPlatformService -t Global -u [adminID] -f [passwordfile] -a iplanet-am-platform-cookie-domains=[primarydomain]replacing [adminID], [passwordfile] and [primarydomain] with appropriate values.
  4. Restart the web application container in which AM runs to apply these configuration changes.

See Also

Multiple mappings found for organization identifier error when logging into AM (All versions)

Implementing CDSSO

Related Training

ForgeRock Access Management Core Concepts (AM-400)

Related Issue Tracker IDs


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