Sun Java System Web Server 7.0 Update 1 Administrator's Guide

Managing Authentication Realms

The Java EE based security model provides for security realms that identify and authenticate users.

The authentication process verifies users through a Java realm. A realm consists of a set of users, optional group mappings, and authentication logic that can validate authentication requests. Once an authentication request is validated by a configured realm and the security context established, this identity is applied to all subsequent authorization decisions.

Note –

The Java realms are analogous to the auth-dbs (Authentication Databases) with the difference that while auth-dbs are used by the ACL engine (based on rules in your ACL file), the Java Realms are used by the Java Servlet access control rules (specified in each web application's web.xml file).

A server instance may have any number of configured realms. The configuration information is present in the auth-realm element in the server.xml file.

The following table defines the different types of realms supported in Sun Java System Web Server 7.0 Update 1

Table 11–8 Types of Realms




The file realm is the default realm when you first install the Sun Java System Web Server. This realm, easy and simple to set up, represents a significant convenience to developers.

The file realm authenticates users against user data stored in a text file. The Java Realms are analogous to the auth-dbs (Authentication Databases) with the difference that while auth-dbs are used by the ACL engine (based on rules in your ACL file), the Java Realms are used by the Java Servlet access control rules (specificed in each web application's web.xml).


The ldap realm allows you to use an LDAP database for user security information. An LDAP directory service is a collection of attributes with unique identifiers. The ldap realm is ideal for deployment to production systems.

In order to authenticate users against the ldap realm, you must create the desired user(s) in your LDAP directory. You can do this from the Administration Server’s Users & Groups tab. You can also perform this action from your LDAP directory product’s user management console.


The PAM (aka Solaris) realm delegates authentication to the Solaris PAM stack. As with the PAM auth-db, this realm is only supported on Solaris 9 and 10 and the server instance must be running as root.  


The certificate realm supports SSL authentication. The certificate realm sets up the user identity in the Sun Java System Web Server’s security context and populates it with user data from the client certificate. The Java EE containers then handle authorization processing based on each user’s DN from his or her certificate. This realm authenticates users with SSL or TLS client authentication through X.509 certificates.


The native realm is a special realm that provides a bridge between the core ACL-based authentication model and the Java EE/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.

When an authentication operation is invoked, the Native realm delegates this authentication to the core authentication subsystem. From the user’s perspective this is essentially equivalent to, for example, the LDAP realm delegating authentication to the configured LDAP server. When group membership queries are processed by the Native realm, they are also delegated to the core authentication subsystem. From the Java web modules and the developers perspective, the Native realm is no different from any of the other Java realms which are available for use with web modules. 


You can build realms for other databases, such as Oracle, to suit your specific needs by using pluggable JAAS login modules and a realm implementation. 

The following section describes the steps involved in adding a new authentication realm.

ProcedureTo Add a Authentication Realm

  1. Select the configuration.

    Select the configuration for which you need to add a new authentication realm. Click Configurations tab and select the configuration.

  2. Click on Java > Security tab.

  3. Click New Authentication Button.

  4. Provide Realm Details.

    • Name — Enter a short name for the realm. This name is used to refer to the realm from, for example, web.xml.

    • Class — If you are configuring a custom realm, enter the full Java class name which implements your custom realm. There is no need to enter a class for any of the built-in realms.

    • Type — Select the type of realm. See previous section where Java Realm types are discussed.

    • Properties — Add realm specific properties. For instance property name="file" value="instance_dir/config/keyfile" and property name="jaas-context" value="fileRealm.

    Note –

    Using CLI

    For adding an authentication realm through CLI, execute the following command.

    wadm> create-auth-realm --user=admin --password-file=admin.pwd --host=serverhost 
    --port=8989 --config=config1 basic

    See CLI Reference, create-auth-realm(1).

    Specify the name of a built-in authentication realm type. The type can be file, ldap, pam, native or certificate.