Admin Console Tasks for 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.

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

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.

Expand the Security node.

Select the Realms node.

On the Realms page, click New.

The Create Realm page
is displayed.

Enter a name for the realm in the Name field.

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

Add the required properties and any desired optional properties
for the 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 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:

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

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.

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

Restart the Server if Restart Required displays in the console.

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:

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.

Equivalent asadmin command

Configuring Mutual Authentication

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.

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

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.

Expand the Security node.

Expand the Realms node.

Select the certificate realm.

Click the Add Property button.

In the Name field, enter clientAuth.

In the Value field, enter true.

Click Save.

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.