Sun Java System Application Server Enterprise Edition 8.1 2005Q2 Administration Guide

- Previous: Admin Console Tasks for Security
- Next: Admin Console Tasks for JACC Providers

# Admin Console Tasks for Realms

- To create a realm

- To edit a realm

- To delete a realm

- To set the default realm

- Additional Information for Specific Realms

## To create 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.

1. In the Admin Console tree component, expand the Configurations node.

2. Select the instance to configure:

   - To configure a particular instance, expand the instance’s config node. For example, the default instance, `server`, expand the `server-config` node.

   - To configure the default settings for all instances, expand the `default-config` node.

3. Expand the Security node.

4. Select the Realms node.

5. On the Realms page, click New.

   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 the following table.

   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.

   1. Click Add Property.

   2. In the Name field, enter the name of the property.

      - For a description of `file` realm properties, see Editing the file and admin-realm Realms.

      - For a description of `certificate` realm properties, see Editing the certificate Realm.

      - For a description of `ldap` realm properties, see Creating an ldap Realm.

      - For a description of `solaris` realm properties, see Creating the solaris Realm.

      - For a description of custom realm properties, see Creating a Custom Realm.

   3. In the Value field, enter the value of the property.

9. Click OK.

##### Equivalent asadmin command

`create-auth-realm`

## To edit a realm

1. In the Admin Console tree component, expand the Configurations node.

2. Select the instance to configure:

   - To configure a particular instance, expand the instance’s config node. For example, the default instance, `server`, expand the `server-config` node.

   - To configure the default settings for all instances, expand the `default-config` node.

3. Expand the Security node.

4. Expand the Realms node.

5. Select the name of an existing realm.

   The Edit Realm page displays.

6. Edit existing properties and their values as desired.

7. To add additional properties, click the Add Properties button.

   The page displays a new row. Enter a valid property name and property value.

   - For a description of `file` realm properties, see Editing the file and admin-realm Realms.

   - For a description of `certificate` realm properties, see Editing the certificate Realm.

   - For a description of `ldap` realm properties, see Creating an ldap Realm.

   - For a description of `solaris` realm properties, see Creating the solaris Realm.

   - For a description of custom realm properties, see Creating a Custom Realm.

8. Click Save to save the changes.

## To delete a realm

1. In the Admin Console tree component, expand the Configurations node.

2. Select the instance to configure:

   - To configure a particular instance, expand the instance’s config node. For example, the default instance, `server`, expand the `server-config` node.

   - To configure the default settings for all instances, expand the `default-config` node.

3. Expand the Security node.

4. Select the Realms node.

5. Click in the box beside the realm to be deleted.

6. Click Delete.

##### Equivalent asadmin command

`delete-auth-realm`

## To set the default realm

The default realm is the realm that the Application Server uses for authentication and authorization if an application’s deployment descriptor does not specify a realm.

1. In the Admin Console tree component, expand the Configurations node.

2. Select the instance to configure:

   - To configure a particular instance, expand the instance’s config node. For example, the default instance, `server`, expand the `server-config` node.

   - To configure the default settings for all instances, expand the `default-config` node.

3. Select the Security node.

   The Security page displays.

4. In the Default Realm field, pick the desired realm from the drop-down list.

5. Click Save to save the changes or Load Defaults to delete changes and restore the Application Server default values.

6. Restart the server if Restart Required displays in the console.

## Additional Information for Specific Realms

This section covers the following topics:

- Creating an ldap Realm

- Creating the solaris Realm

- Creating a Custom Realm

- Editing the certificate Realm

- Editing the file and admin-realm Realms

- Managing Users with Network Security Services (NSS)

- Managing file Realm Users

- Configuring Mutual Authentication

### 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 To create a realm for adding a new realm, and add the properties shown in the following table.

Table 9–2 Required properties for `ldap` realm

Property Name | Description | Value
--- | --- | ---
directory | LDAP URL of the directory server. | LDAP URL of the form `ldap://`hostname`:`portFor 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 the following table.

Table 9–3 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 the following table.

Table 9–4 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 create a custom realm

1. Follow the procedure outline in To create 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 for a custom realm shown in the following table.

   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, domain-dir`/config/login.conf`, and add the fully-qualified class name of the JAAS `LoginModule` at the end of the file, as follows:

       realmName {
           fully-qualified-LoginModule-classname required;
       };

   For example,

       myCustomRealm {
           com.foo.bar.security.customrealm.simpleCustomLoginModule required;
       };

5. Copy the `LoginModule` class and all dependent classes into the directory domain-dir`/lib/classes`.

6. Restart the Server if Restart Required displays in the console.

7. Make sure that the realm is properly loaded.

   Check domain-dir`/logs/server.log` to make sure the server loaded the realm. The server should invoke the realm’s `init()` method.

### Editing the certificate Realm

The `certificate` realm supports SSL authentication. This realm sets up the user identity in the Application Server’s security context, and populates it with user data obtained from cryptographically verified client certificates in the truststore and keystore files (see About Certificate Files). Add users to these files using `certutil`.

With the `certificate` realm, J2EE containers handle authorization processing based on each user’s Distinguished Name (DN) from his or her certificate. The DN is the name of the entity whose public key the certificate identifies. This name uses the X.500 standard, so it is intended to be unique across the Internet. For more information on key stores and trust stores, refer to the `certutil` documentation at Using Network Security Services (NSS) Tools.

The following table lists the optional properties for the `certificate` realm.

Table 9–5 Optional properties for `certificate` realm

Property | Description
--- | ---
assign-groups | A comma-separated list of group names. All clients who present valid certificates are assigned to these groups. For example, `employee,manager`, where these are the names of user groups.
jaas-context | Type of login module to use for this realm. For the `certificate` realm, the value must be `certificateRealm`.

### Editing the file and admin-realm Realms

The server maintains all user, group, and password information in a file named `keyfile` for the `file` realm and `admin-keyfile` for the `admin-realm`. For both, the `file` property specifies the location of the keyfile. The following table shows required properties for a `file` realm.

Table 9–6 Required properties for file realms

Property name | Description | Default Value
--- | --- | ---
file | Full path and name of the keyfile. | domain-dir`/config/keyfile`
jaas-context | Type of login module to use for this realm. | `fileRealm` is the only valid value

The `keyfile` is initially empty, so users must be added before the `file` realm is used. For instructions, see Managing file Realm Users.

The `admin-keyfile` initially contains the admin user name, the admin password in an encrypted format, and the group to which this user belongs, which is `asadmin` by default. For more information on adding users to the `admin-realm`, read To grant access to administration tools.

Note –

Users in the group `asadmin` in the `admin-realm` are authorized to use the Admin Console and `asadmin` tools. Add only users to this group that have server administrative privileges.

### Managing Users with Network Security Services (NSS)

In the Enterprise Edition only, you can manage users using the Admin Console as discussed in Managing file Realm Users or you can manage users using NSS tools. Network Security Services (NSS) is a set of libraries designed to support cross-platform development of security-enabled client and server applications. Applications built with NSS can support SSL v2 and v3, TLS, PKCS #5, PKCS #7, PKCS #11, PKCS #12, S/MIME, X.509 v3 certificates, and other security standards. For detailed information, link to the following URLs:

- Network Security Services (NSS) at `http://www.mozilla.org/projects/security/pki/nss/`

- NSS Security Tools at `http://www.mozilla.org/projects/security/pki/nss/tools/`

- Overview of NSS at `http://www.mozilla.org/projects/security/pki/nss/overview.html`

### Managing file Realm Users

Manage `file` realm users with the Admin Console. Users and groups in the `file` realm are listed in the keyfile, whose location is specified by the `file` property.

Note –

It is also possible to use these steps to add users to any file realm, including the `admin-realm`. Simply substitute the name of the target realm in place of the `file` realm referenced in this section.

A user in the `file` realm can belong to a J2EE group, a category of users classified by common traits. For example, customers of an e-commerce application might belong to the `CUSTOMER` group, but the big spenders would belong to the `PREFERRED` group. Categorizing users into groups makes it easier to control the access of large numbers of users.

Initially after installation of the Application Server, the only user is the administrator entered during installation. By default, this user belongs to the group `asadmin`, in the realm `admin-realm`, which gives rights to modify the Application Server. Any users assigned to this group will have administrator privileges, that is, they will have access to the `asadmin` tool and the Admin Console.

To manage `file` realm users, perform these tasks:

- To access the File Users page

- To add a user

- To edit user information

- To delete a user

#### To access the File Users page

1. In the Admin Console tree component, expand the Configurations node.

2. Select the instance to configure:

   - To configure a particular instance, expand the instance’s config node. For example, the default instance, `server`, expand the `server-config` node.

   - To configure the default settings for all instances, expand the `default-config` node.

3. Expand the Security node.

4. Expand the Realms node.

5. Select the `file` node.

6. Click the Manage Users button from the Edit Realm page.

   The File Users page displays. In this page, perform the following tasks:

   - To add a user

   - To edit user information

   - To delete a user

#### To add a user

1. Click New to add a new user to the `file` realm.

2. Enter the following information on the File Users page:

   - User ID (required) - The name of the user.

   - Password (required) - The user password.

   - Confirm Password (required) - The user password again, for verification.

   - Group List (optional) - A comma-separated list of the groups to which the user belongs. These groups do not need to be defined elsewhere.

3. Click OK to add this user to the list of users in the `file` realm. Click Cancel to quit without saving.

##### Equivalent asadmin command

`create-file-user`

#### To edit user information

1. In the User ID column, click the name of the user to be modified.

   The Edit File Realm User page displays.

2. Change the user password by entering a new password in the Password and Confirm Password fields.

3. Change the groups to which the user belongs by adding or deleting groups in the Group List field.

   Separate group names with commas. Groups need not be previously defined.

4. Click Save to save this user to the list of users in the `file` realm.

   Click Close to quit without saving.

#### To delete a user

1. Select the checkbox to the left of the name of the user(s) to be deleted.

2. Click Delete.

3. Click Close to return to the Edit Realm page.

##### Equivalent asadmin command

`delete-file-user`

### Configuring Mutual Authentication

- Enabling Mutual SSL Authentication in an Application

- To enable mutual authentication for all the applications

In mutual authentication, both server and client-side authentication are enabled. To test mutual authentication, a client with a valid certificate must exist. For information on mutual authentication, see the Security chapter of The J2EE 1.4 Tutorial at `http://java.sun.com/j2ee/1.4/docs/tutorial/doc/index.html`.

#### Enabling Mutual SSL Authentication in an Application

To enable mutual authentication for a specific application, use `deploytool` to set the method of authentication to `Client-Certificate`. For more information about using `deploytool`, refer to the Security chapter of The J2EE 1.4 Tutorial at `http://java.sun.com/j2ee/1.4/docs/tutorial/doc/index.html`.

#### To enable mutual authentication for all the applications

The Application Server uses the `certificate` realm for HTTPS authentication.

1. In the Admin Console tree component, expand the Configurations node.

2. Select the instance to configure:

   - To configure a particular instance, expand the instance’s config node. For example, the default instance, `server`, expand the `server-config` node.

   - To configure the default settings for all instances, expand the `default-config` node.

3. Expand the Security node.

4. Expand the Realms node.

5. Select the `certificate` realm.

6. Click the Add Property button.

   1. In the Name field, enter `clientAuth`.

   2. In the Value field, enter `true`.

7. Click Save.

8. Restart the Application Server if Restart Required displays in the console.

   After restarting the server, client authentication is required for all applications that use the `certificate` realm.

- Previous: Admin Console Tasks for Security
- Next: Admin Console Tasks for JACC Providers

- © 2010, Oracle Corporation and/or its affiliates