Creating a Realm

The Application Server comes preconfigured with three realms: file, certificate, and admin-realm. It is also possible to create ldap, solaris, and custom realms. Generally, you will have one realm of each type on a server, but on the Application Server there are two file realms: file and admin-realm. These are two realms of the same type used for two different purposes. It is also possible to have a different certificate database for each virtual server on your system.

To create a security realm, follow these steps.

  1. In the Admin Console tree component, expand the Configuration node.
  2. Expand the Security node.
  3. Select the Realms node.
  4. On the Realms page, click New.
  5. The Create Realm page is displayed.

  6. Enter a name for the realm in the Name field.
  7. Specify the class name for the realm being created. Valid choices are shown in Table 0-35:

    Table 0-35  Valid values for realm class name 

    Realm Name

    Class Name

    file

    com.sun.enterprise.security.auth.realm.file.FileRealm

    certificate

    com.sun.enterprise.security.auth.realm.certificate.CertificateRealm

    ldap

    com.sun.enterprise.security.auth.realm.ldap.LDAPRealm

    solaris

    com.sun.enterprise.security.auth.realm.solaris.SolarisRealm

    custom

    Name of login realm class

  8. Add the required properties and any desired optional properties for the realm.
  9. To add a property:

    1. Click Add Property.
    2. In the Name field, enter the name of the property.
    3. For a description of file realm properties, see "Editing the file and admin-realm Realms".
    4. For a description of certificate realm properties, see "Editing the certificate Realm".
    5. For a description of ldap realm properties, see "Creating an ldap Realm".
    6. For a description of solaris realm properties, see "Creating the solaris Realm".
    7. For a description of custom realm properties, see "Creating a Custom Realm".
    8. In the Value field, enter the value of the property.
  10. Click OK.

Equivalent asadmin command: create-auth-realm

Creating an ldap Realm

The ldap realm performs authentication using information from an LDAP server. User information includes user name, password, and the groups to which the user belongs. To use an LDAP realm, the users and groups must already be defined in your LDAP directory.

To create an LDAP realm, follow the steps in "Creating a Realm" for adding a new realm, then add the properties as shown in Table 0-36.

Table 0-36  Required properties for ldap realm 

Property Name

Description

Value

directory

LDAP URL of the directory server.

LDAP URL of the form ldap://hostname:port
For example, ldap://myldap.foo.com:389.

base-dn

Base Distinguished Name (DN) for the location of user data, which can be at any level above the user data, since a tree scope search is performed. The smaller the search tree, the better the performance.

Domain for the search, for example: dc=siliconvalley, dc=BayArea, dc=sun, dc=com.

jaas-context

Type of login module to use for this realm.

Must be ldapRealm.

Optional properties for the ldap realm are shown in Table 0-37:

Table 0-37  Optional properties for ldap realm 

Property Name

Description

Default

search-filter

Search filter to use to find the user.

uid=%s (%s expands to the subject name).

group-base-dn

Base DN for the location of group data.

Same as the base-dn, but it can be tuned if necessary.

group-search-filter

Search filter to find group memberships for the user.

uniquemember=%d (%d expands to the user element DN).

group-target

LDAP attribute name that contains group name entries.

CN

search-bind-dn

Optional DN used to authenticate to the directory for performing the search-filter lookup. Only required for directories that do not allow anonymous search.

 

search-bind-password

LDAP password for the DN given in search-bind-dn.

 

Example

For example, suppose an LDAP user, Joe Java, is defined in the LDAP directory as follows:

uid=jjava,ou=People,dc=acme,dc=com
uid=jjava
givenName=joe
objectClass=top
objectClass=person
objectClass=organizationalPerson
objectClass=inetorgperson
sn=java
cn=Joe Java

Using the example code, when creating or editing the ldap realm, you can enter the values as shown in Table 0-38.

Table 0-38  Example ldap realm values 

Property Name

Property Value

directory

LDAP URL to your server, for example: ldap://ldap.acme.com:389

base-dn

ou=People,dc=acme,dc=com.

Can be rooted higher, for example dc=acme, dc=com, but searches would traverse a larger part of the tree, reducing performance.

jaas-context

ldapRealm

Creating the solaris Realm

The solaris realm gets user and group information from the underlying Solaris user database, as determined by the system’s configuration. The solaris realm invokes the underlying PAM infrastructure for authenticating. If the configured PAM modules require root privileges, the domain must run as root to use this realm. For details, see the Solaris documentation for security services.

The solaris realm has one required property, jaas-context that specifies the type of login module to use. The property value must be solarisRealm.

Note: The solaris realm is supported only for Solaris 9 or later.

Creating a Custom Realm

In addition to the four built-in realms, you can also create custom realms that store user data in some other way, such as in a relational database. Development of a custom realm is outside the scope of this document. For more information, see the Application Server Developer's Guide chapter titled Securing Applications.

As an administrator, the main thing you need to know is that a custom realm is implemented by a class (called the LoginModule) derived from the Java Authentication and Authorization Service (JAAS) package.

To configure the Application Server to use a custom realm:

  1. Follow the procedure outline in "Creating a Realm", entering the name of the custom realm and the name of the LoginModule class. Any unique name can be used for the custom realm, for example myCustomRealm.
  2. Add the properties shown in Table 0-39:

    Table 0-39  Valid properties for a custom realm 

    Property Name

    Property Value

    jaas-context

    LoginModule class name, for example simpleCustomRealm

    auth-type

    Description of the realm, for example “A simple example custom realm”.

  3. Click OK.
  4. Edit the domain's login configuration file, install_dir/domains/domain_name/config/login.conf, and add the fully-qualified class name of the JAAS LoginModule at the end of the file, as follows:
  5. realmName {
      fully-qualified-LoginModule-classname required;
    };

    For example,

    myCustomRealm {
      com.foo.bar.security.customrealm.simpleCustomLoginModule required;
    };
  6. Copy the LoginModule class and all dependent classes into the directory install_dir/domains/domain_name/lib/classes.
  7. Restart the Server if Restart Required displays in the console.
  8. Make sure that the realm is properly loaded.
  9. Check install_dir/domains/domain_name/logs/server.log to make sure the server loaded the realm. The server should invoke the realm’s init() method.

See also:


Legal Notices