This section contains the following topics:
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 realm using the Admin Console, go to Configuration > Security > Realms > New. Enter a name for the realm and specify the class name for the realm you are creating. Class names for different realms 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.
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.
For more details on creating a realm, click Help in the Admin Console.
Equivalent asadmin command.
Use the create-auth-realm asadmin command to create a realm. For details, see create-auth-realm(1).
In the Admin Console, go to Configuration > Security > Realms and select the realm you want to edit. The Edit Realm page will display, where you can make changes to the current configuration.
For details on editing or deleting a realm, click Help in the Admin Console.
Equivalent asadmin command.
Use the delete-auth-realmcommand to delete a realm. For details, delete-auth-realm(1).
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.
In the Admin Console, go to Configuration > Security and select the required realm from the Default Realm drop-down list. Click Save.
For more details, click Help in the Admin Console.
This section covers the following topics:
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, and add the properties shown in the following table.
Table 8–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 8–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. |
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 8–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 |
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.
The solaris realm is supported only for Solaris 9 or later.
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 Chapter 5, Securing Applications, in Sun Java System Application Server Platform Edition 9 Developer’s Guide in the Application Server Developer's Guide.
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.
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.
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”. |
Click OK.
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; }; |
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.
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 keytool. For more information, see chapter titled Security at Java EE 5 Tutorial.
With the certificate realm, Java EE 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 keytool documentation at http://java.sun.com/j2se/1.5.0/docs/tooldocs/solaris/keytool.html.
The following table lists the optional properties for the certificate realm.
Table 8–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. |
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 8–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 Granting Access to Administration Tools.
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.
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
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.
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 JavaEE 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 the following tasks:
Add a user.
Edit user information.
Delete a user.
To access the File Users page in the Admin Console, go to Configuration > Security > Realms > File > Edit Realm > Manage Users. For detailed information on performing these tasks, click Help in the Admin Console.
Equivalent asadmin commands.
The same tasks can be performed from the asadmin command line utility. For more information, see
create-file-user: See create-file-user(1).
update-file-user: See update-file-user(1).
delete-file-userdelete-file-user(1).
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 Java EE 5 Tutorial.
To enable mutual authentication for a specific application, use NetBeans to set the method of authentication to Client-Certificate. For more information on using NetBeans, see the Java EE 5 Tutorial.
The Application Server uses the certificate realm for HTTPS authentication. To enforce client authentication for all applications that use the certificate realm, in the Admin Console, go to Configuration > Security > Realms > certificate realm. Click Add Property and enter the following values and click Save:
In the Name field, enter clientAuth.
In the Value field, enter true.
Restart the Application Server if Restart Required displays in the console.