Chapter 5. Configuring Realms

This chapter shows how to configure OpenAM realms, which are used to group configuration and identities together. For example, you might have one realm for OpenAM administrators and agents, and another realm for users. In this two-realm setup, the OpenAM administrator can login to the administrative realm to manage the services, but cannot authenticate as OpenAM administrator to the realm that protects web sites with HR and financial information.

OpenAM associates a realm with at least one identity repository and authentication process. OpenAM also associates the realm with authorization policies and entitlements for users, and privileges for administrators. Each realm can have its own configuration for services.

When you first configure OpenAM, OpenAM sets up the default / (Top Level Realm), containing OpenAM configuration data, and allowing authentication using the identity repository you choose during initial configuration. The top level realm might hold the overall configuration for Example.com for instance.

You create new realms to subdivide authentication, and authorization, and to delegate management of sub-realms. For example, your organization might require separate realms for payroll, human resources, and IT management domains and their applications.

Procedure 5.1. To Create a New Realm

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

  1. Login to the OpenAM console as OpenAM Administrator, amadmin.

  2. On the Access Control tab > Realms table, click New... to open the New Realm page, where you configure the realm.

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

    Realm/DNS aliases must follow standard FQDN conventions, such as hr.example.com or pay.example.com.

  3. Save your work after defining the configuration for the new realm.

You configure a realm through the console starting from the Access Control tab > Realms table. By default the new realm inherits configuration from the global configuration. The default identity repository is the one you choose when configuring OpenAM after deployment. The default authentication mechanism corresponds to that identity repository as well. You can, however, constrain authentication to rely on different data stores, and set policy for agents to define authorization in the realm.

Procedure 5.2. To Delegate Administration

You can delegate administration in a realm. OpenAM grants administrative capabilities to members of groups having administrative privileges.

You can grant privileges through the OpenAM console as described below, or by using the ssoadm add-privileges command.

  1. On the Access Control tab > Realms table, click the realm for which you want to delegate administration to view the realm configuration.

  2. On the Privileges tab, click the name of the group to whom you intend to grant access.

  3. Select the administrative privileges to delegate for the realm, and then save your work.

    When using the ssoadm add-privileges command, the privilege names are as follow.

    AgentAdmin

    Read and write access to all configured Agents

    EntitlementRestAccess

    REST calls for Policy Evaluation

    FederationAdmin

    Read and write access to all federation metadata configurations

    LogAdmin

    Read and write access to all log files

    LogRead

    Read access to all log files

    LogWrite

    Write access to all log files

    PolicyAdmin

    Read and write access only for policy properties

    PrivilegeRestAccess

    REST calls for managing entitlements

    PrivilegeRestReadAccess

    REST calls for searching entitlements

    RealmAdmin

    Read and write access to all realm and policy properties

Procedure 5.3. To Delegate Policy Management

When you delegate access management for a realm, you might want to delegate policy management. You can delegate policy management by creating a referral.

  1. In the OpenAM console, browse to Access Control > Realm Name > Policies, where Realm Name is the realm from which you intend to delegate policy.

  2. Click the New Referral... button in the Policies table.

  3. In the New Referral screen, provide at minimum a name for the referral.

  4. Set up Rules to identify the resources that the Referral applies to.

    When defining Rules to match resources, specify Resource Names as you would for Policies.

    For example, you specify a URL Policy Agent rule to create policies for all resources under http://example.com/ by creating rules for http://example.com/, for http://example.com/*, and also for http://example.com/*?*. When used at the end of a rule * matches one or more characters, rather than zero or more characters.

  5. Set up referrals to identify the realms to which to delegate policy management.

    You can delegate to peer realms or sub realms (child realms), but not to parent realms.

  6. Save your work.

    At this point you can let the realm administrator know that she can create policies in her realm for the resources you specified in the rules of the referral.

Procedure 5.4. To Configure a Data Store for a Realm

When you first set up a realm, the new realm inherits the data store from the parent realm. Yet, if your administrators are in one realm and your users in another, your new child realm might retrieve users from a different data store.

  1. In the OpenAM console, browse to Access Control > Realm Name > Data Stores.

  2. Click New... in the Data Stores table to create a data store profile, and to provide the information needed to connect to the data store.

  3. In the first screen, name the data store and select the type of data store to use.

    Most data stores are directory services, though the Database Repository lets you connect to an SQL database through JDBC.

  4. In the second screen, provide information on how to connect to your data store, and then click Finish to save your work.

    See the chapter on authentication for hints on connecting to Active Directory, LDAP directory, and JDBC data sources.

  5. Click the Subjects tab, and make sure the connection to your new data store is working, by searching for a known identity.

    By default the Subjects list only retrieves 100 entries from the data store. Narrow your search if you do not see the identity you are looking for in the list.

  6. If you no longer need the connection to the inherited data store in this realm, then you can delete its entry in the Data Stores table.

    Also, once you change the data store for a realm, you might opt to change the authentication module configuration as described in the chapter on authentication to use your realm data store, rather than the inherited settings.

Procedure 5.5. To Configure a Web or J2EE Agent For Login to a Realm

You might choose to configure your agent in one realm, yet have your real users authenticate through another realm. In this case, you want your agents to redirect users to authenticate to their realm, rather than the agent realm.

  1. In the OpenAM console, browse to Access Control > Realm Name > Agents > Web or J2EE Agent Type > Agent Name > OpenAM Services.

  2. Add login and logout URLs, including the realm in the query string.

    For example, if your Realm Name is hr, and you access OpenAM at http://openam.example.com:8080/openam:

    • Login URL: http://openam.example.com:8080/openam/UI/Login?realm=hr

    • Logout URL: http://openam.example.com:8080/openam/UI/Logout?realm=hr

  3. Save your work.