Configuring Realms (Console)

You create and configure realms through the AM console, starting from the Realms page.

Note

AM requires cookies for all configured realms when using DNS aliases. For example, if you install AM in the domain, openam.example.net and have realms, identity.example.org and security.example.com then 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 "To Configure DNS Aliases for Accessing a Realm".

This section has the following procedures:

To Create a New Realm

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

  1. Log in to the AM console as administrator, amAdmin.

  2. On the Realms page, click New Realm. The New Realm page appears. Complete the form to configure the realm.

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

    Note

    Realm names must not match any of the following:

    • Existing realm names.

    • Existing realm aliases.

    • Names of AM REST endpoints.

      For example users, groups, realms, policies or applications.

  4. The Active button is enabled by default.

    Warning

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

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

    Default: the top level realm (/).

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

  7. 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 console does not conform to the definition of DNS aliases described in RFC 2219.

    Tip

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

    For more information, see "To Configure DNS Aliases for Accessing a Realm".

  8. To enable client-based sessions for the realm, toggle the Use Client-based Sessions switch. For more information on sessions, see Introducing Sessions.

  9. Click Create to save your configuration.

To Configure DNS Aliases for Accessing 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:

Note

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:

    1. Log in to the AM console as an AM administrator, for example, amAdmin.

    2. Navigate to Configure > Global Services > Platform.

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

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

  2. Set the FQDN for each realm as follows:

    1. Navigate to Realms > Realm Name, and then click Properties.

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

    3. Save your changes.

  3. (Optional) Adding DNS aliases by using the AM console also adds FQDN mappings to the AM server.

    To verify these have been created perform the following steps:

    1. Navigate to Configure > Server Defaults > Advanced.

    2. 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.

    3. 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.

Read a different version of :