PingAM 7.5.0

Configure realms in the UI

To create and configure realms through the AM admin UI, start from the Realms page.

If you use DNS aliases, AM requires cookies for all configured realms.

For example, if you install AM in the domain, openam.example.net and have realms, identity.example.org and security.example.com, you must configure cookie domains for .example.net, .example.org, and .example.com.

You can set up cookie domains for each realm by following the procedure in Configure DNS aliases to access a realm.

Create a new realm

You can create a new realm through the AM admin UI as described below, or by using the ssoadm create-realm command:

  1. In the AM admin UI, go to Realms and click New Realm.

    On the New Realm page, configure the realm.

  2. In the Name field, enter a descriptive name for the realm.

Realm names must not match any of the following:

  • Existing realm names.

  • Existing realm aliases.

  • Names of AM REST endpoints.

    By default, you cannot use any of the following names for a new realm:

    agents
api
applications
applicationtypes
authenticate
cache
conditiontypes
dashboard
decisioncombiners
docs
email
global-audit
global-config
groups
health
metrics
policies
push
realm-audit
realm-config
realms
records
resourcetypes
scripts
selfservice
serverinfo
sessions
subjectattributes
subjecttypes
things
timetravel
token
tokens
users

  1. The realm is active by default.

    If you configure the realm to be inactive, users cannot use it to authenticate, or be granted access to protected resources.

  2. In the Parent field, enter the parent of your realm.

    Default: the Top Level Realm (/).

  3. In the Realm Aliases field, enter a simple text alias to represent the realm.

  4. In the DNS Aliases field, enter fully qualified domain names (FQDN) that can be used to represent the realm.

    A DNS alias is not related to the CNAME record used in DNS database zones. In other words, the option shown in the AM admin UI does not conform to the definition of DNS aliases described in RFC 2219.

    Entering a DNS alias in the AM admin UI also applies required changes to the advanced server property com.sun.identity.server.fqdnMap.

    For more information, see Configure DNS aliases to access a realm.

  5. To enable client-side sessions for the realm, toggle the Use Client-Side Sessions switch.

    For more information on sessions, see Introduction to sessions.

  6. Click Create to save your configuration.

Configure DNS aliases to access a realm

You can configure realms to be associated with specific fully qualified domain names (FQDN).

For example, consider a deployment with the following characteristics:

  • The FQDN for AM and the top level realm is openam.example.com.

  • AM also services realm1.example.com, and realm2.example.com. In other words, AM receives all HTTP(S) connections for these host names. Perhaps they share an IP address, or AM listens on all interfaces.

Without applying DNS aliases to the relevant realm, when a user visits http://realm1.example.com:8080/openam, AM redirects that user to the top level realm, https://openam.example.com:8443/openam. If the authenticating user is present only in realm1, then authentication fails even with correct credentials.

If no DNS alias is configured for a realm, realm1 users must visit URLs such as https://openam.example.com:8443/openam/XUI/?realm=/realm1#login. This format of URL reveals the top level realm, and exposes extra information about the service.

Configure DNS aliases for realms to prevent redirection and having to expose the top level realm domain by performing the following steps:

Realm aliases must be unique within an AM instance, and cannot contain the characters ", #, $, %, &, +, ,, /, :, ;, <, =, >, ?, @, \, or spaces.

  1. Add the domains that AM services to the list of domains that created cookies will be applicable to, as follows:

    • In the AM admin UI, go to Configure > Global Services > Platform.

    • In Cookie Domains, enter the domains that AM will service.

      For example, if you install AM at openam.example.net, and intend to have realms associated with the FQDNs realm1.example.org and realm2.example.com, the Cookie Domains list will include example.net, example.org, and example.com.

  2. Set the FQDN for each realm as follows:

    • Go to Realms > Realm Name > Properties.

    • In DNS Aliases, enter one or more FQDN values for the realm.

    • Save your changes.

  3. Adding DNS aliases by using the AM admin UI also adds FQDN mappings to the AM server.

    To verify these have been created perform the following steps:

    • Go to Configure > Server Defaults > Advanced.

    • For each FQDN DNS alias configured, verify the existence of a property named com.sun.identity.server.fqdnMap[Realm FQDN] with a property value of Realm FQDN.

      For example, the property may be called com.sun.identity.server.fqdnMap[realm1.example.com] with a value of realm1.example.com.

      If the property does not exist or needs to be changed, manually create the property for each FQDN DNS alias.

    • Save your changes.

    The new realm aliases take effect immediately, it is not necessary to restart AM. You can now use a URL such as http://realm1.example.com:8080/openam to access realm1, rather than https://openam.example.com:8443/openam/XUI/?realm=/realm1#login.