Sun Java System Web Server 6.1 SP6 Programmer's Guide to Web Applications

Realm Configuration

This section provides an overview of the configuration characteristics of the supported realms. For detailed information about configuring realms, see the Sun Java System Web Server 6.1 SP6 Administrator’s Guide.

The section describes the following realms:

File

The file realm is the default realm when you first install Sun Java System Web Server, and has the following configuration characteristics:

Name: file
Classname: com.iplanet.ias.security.auth.realm.file.FileRealm

Required properties are as follows:

file: The name of the file that stores user information. By default this file is instance_dir/config/keyfile.
jaas-context: The value must be fileRealm.

The user information file is initially empty, so you must add users before you can use the file realm.

LDAP

The LDAP realm allows you to use an LDAP database for user security information, and has the following configuration characteristics:

Name: ldap
Classname: com.iplanet.ias.security.auth.realm.ldap.LDAPRealm

Required properties are as follows:

directory: The LDAP URL to your server.
base-dn: The base DN for the location of user data. This base DN 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.
jaas-context: The value must be ldapRealm.

You can add the following optional properties to tailor the LDAP realm behavior:

search-filter: The search filter to use to find the user. The default is uid=%s (%s expands to the subject name).
group-base-dn: The base DN for the location of group data. By default it is same as the base-dn, but it can be tuned if necessary.
group-search-filter: The search filter to find group memberships for the user. The default is uniquemember=%d (%d expands to the user element DN).
group-target: The LDAP attribute name that contains group name entries. The default is CN.
search-bind-dn: An 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: The LDAP password for the DN given in search-bind-dn.

You must create the desired user(s) in your LDAP directory. You can do this from the Sun™ Java System Directory Server console, or through any other administration tool that supports LDAP and your directory's schema. User and group information is stored in the external LDAP directory.

The principal-name used in the deployment descriptors must correspond to your LDAP user information.

Solaris

The Solaris realm allows authentication using Solaris user name and password data. This realm is supported only on Solaris 9, and has the following configuration characteristics:

Name: solaris
Classname: com.iplanet.ias.security.auth.realm.file.SolarisRealm

Required properties are as follows:

jaas-context: The value must be solarisRealm.

Users and groups are stored in the underlying Solaris user database, as determined by the system’s PAM (Pluggable Authentication Module) configuration.

Note –

The Solaris realm invokes the underlying PAM infrastructure for authentication. If the configured PAM modules require root privileges, the instance must run as root to use this realm. For details, see the "Using Authentication Services (Tasks)" chapter in the Solaris 9 System Administration Guide: Security Services.

Certificate

The certificate realm supports SSL authentication. The certificate realm sets up the user identity in Sun Java System Web Server's security context and populates it with user data from the client certificate. The J2SE containers then handle authorization processing based on each user's DN from his or her certificate. The certificate realm has the following configuration characteristics:

Name: certificate
Classname: com.iplanet.ias.security.auth.realm.certificate.CertificateRealm

You can add the following optional property to tailor the certificate realm behavior:

assign-groups: If this property is set, its value is taken to be a comma-separated list of group names. All clients presenting valid certificates are assigned membership to these groups for the purposes of authorization decisions in the web container.

When you deploy an application, you must specify CLIENT-CERT as the authentication mechanism in the web.xml file as follows:

<login-config>
        <auth-method>CLIENT-CERT</auth-method>
</login-config>

You must obtain a client certificate and install it in your browser to complete the setup for client certificate authentication. For details on how to set up the server and client certificates, see the Sun Java System Web Server 6.1 SP6 Administrator’s Guide.

You can configure the server instance for SSL authentication in these ways:

Configure an SSLPARAMS element in server.xml, then restart the server. For more information about the server.xml file, see the Sun Java System Web Server 6.1 SP6 Administrator’s Configuration File Reference.
Use the Administration interface as described in the Sun Java System Web Server 6.1 SP6 Administrator’s Guide.

Note –

In most cases, it is not necessary to configure a certificate realm in server.xml when using CLIENT-CERT authentication in web applications. Since the CLIENT-CERT authentication method inherently implies certificate-based authentication, Sun Java System Web Server will internally use a certificate realm even if one is not configured in server.xml. You can still configure a certificate realm if you want to specify properties for it (for example, assign-groups).

Custom Realm

You can create a custom realm by providing a Java™ Authentication and Authorization Service (JAAS) login module and a realm implementation. Note that client-side JAAS login modules are not suitable for use with Sun Java System Web Server. For more information about JAAS, refer to the JAAS specification for Java 2 SDK, v1.4, available here:

http://java.sun.com/products/jaas/

A sample application that uses a custom realm is available with Sun Java System Web Server at the following location:

server_root/plugins/java/samples/webapps/security

Native Realm

The native realm is a special realm that provides a bridge between the core Sun Java System Web Server ACL-based authentication and the J2SE/Servlet authentication model. By using the native realm for Java web applications, it becomes possible to have the ACL subsystem perform the authentication (instead of having the Java web container do so) and yet have this identity available for Java web applications.

This functionality is provided by pluggable realm called NativeRealm, which acts as a bridge between the J2SE security subsystem and the access control security subsystem.

Depending on whether a security constraint is configured for a web application, the two modes of operation described below are supported by the native realm:

If a security constraint is defined in the application’s deployment descriptor file, web.xml, the web container carries out normal authentication and authorization processing. When the NativeRealm realm is invoked for validating user information, the task of verification is delegated to the core auth-db specified in the realm configuration. See the Sun Java System Web Server 6.1 SP6 Administrator’s Guide for more information on how to configure auth-db in dbswitch.conf and server.xml.

For example (classname= is all on one line, with no spaces):
```
<AUTHREALM name="native"
classname="com.iplanet.ias.security.auth.realm.webcore.
NativeRealm">
        <PROPERTY name="auth-db" value="name">
         <PROPERTY name="jaas-context" value="nativeRealm">
</AUTHREALM>
```
If a security constraint is not defined in the application’s deployment descriptor file web.xml when using NativeRealm, the Java web container does not carry out authentication and authorization tasks. These tasks are left to the core access control lists (ACLs). ACLs are collections of rules that follow a hierarchy and determine whether access should be granted or denied for the requested resource. The ACLs yield the user’s identity, which is then made available to the Java web application. In other words, if the servlet later invokes a principal’s identity with the request.getUserPrincipal() method, the correct user identity will be returned.

In this scenario it is not necessary to provide an auth-db to the NativeRealm configuration, since the access control list that was applied to the given request is already bound to an auth-db.

For example:
```
<AUTHREALM name="native"
classname="com.iplanet.ias.security.auth.realm.webcore.
NativeRealm">
</AUTHREALM>
```

For more details about access control lists, see the Sun Java System Web Server 6.1 SP6 Administrator’s Guide.

Note –

While it is possible to apply both ACL access control rules and web.xml security constraints on a single application, this usage is discouraged. It may lead to duplicate authentication prompts or otherwise confusing behavior. You should always pick either core ACL or J2SE web.xml-based access control mechanisms for a given web application.