Sun Java System Application Server Platform Edition 8.1 2005Q2 Update 2 Developer's Guide

- Previous: Container Security
- Next: JACC Support

# Realm Configuration

This section covers the following topics:

- Supported Realms

- How to Configure a Realm

- How to Set a Realm for an Application or Module

- Creating a Custom Realm

## Supported Realms

The following realms are supported in the Application Server:

- `file` - Stores user information in a file. This is the default realm when you first install the Application Server.

- `ldap` - Stores user information in an LDAP database.

- `certificate` - Sets up the user identity in the Application Server security context, and populates it with user data obtained from cryptographically verified client certificates.

- `solaris` - Allows authentication using Solaris `username+password` data. This realm is only supported on Solaris 9.

For detailed information about configuring each of these realms, see the Sun Java System Application Server Platform Edition 8.1 2005Q2 Update 2 Administration Guide.

## How to Configure a Realm

You can configure a realm in one of these ways:

- In the Administration Console, open the Security component under the relevant configuration and go to the Realms page. For details, see the Sun Java System Application Server Platform Edition 8.1 2005Q2 Update 2 Administration Guide.

- Use the `asadmin create-auth-realm` command to configure realms on local servers. For details, see the Sun Java System Application Server Platform Edition 8.1 2005Q2 Update 2 Reference Manual.

## How to Set a Realm for an Application or Module

The following deployment descriptor elements have optional `realm` or `realm-name` data subelements or attributes that override the domain’s default realm:

- `sun-application` element in `sun-application.xml`

- `web-app` element in `web.xml`

- `as-context` element in `sun-ejb-jar.xml`

- `client-container` element in `sun-acc.xml`

- `client-credential` element in `sun-acc.xml`

If modules within an application specify conflicting realms, these are ignored. If present, the realm defined in `sun-application.xml` is used, otherwise the domain’s default realm is used.

For example, a realm is specified in `sun-application.xml` as follows:

    <sun-application>
        ...
        <realm>ldap</realm>
    </sun-application>

For more information about the deployment descriptor files and elements, see Appendix A, Deployment Descriptor Files.

## Creating a 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 the Application Server. For more information about JAAS, refer to the JAAS specification for Java 2 SDK, v 1.4, available at `http://java.sun.com/products/jaas/`.

Custom realms must extend the `com.sun.appserv.security.``AppservPasswordLoginModule` class. This class extends `javax.security.auth.spi.``LoginModule`. Custom realms must not extend `LoginModule` directly.

Custom login modules must provide an implementation for one abstract method defined in `AppservPasswordLoginModule`:

    abstract protected void authenticateUser() throws LoginException

This method performs the actual authentication. The custom login module must not implement any of the other methods, such as `login()`, `logout()`, `abort()`, `commit()`, or `initialize()`. Default implementations are provided in `AppservPasswordLoginModule` which hook into the Application Server infrastructure.

The custom login module can access the following protected object fields, which it inherits from `AppservPasswordLoginModule`. These contain the user name and password of the user to be authenticated:

    protected String _username;
    protected String _password;

The `authenticateUser()` method must end with the following sequence:

    String[] grpList;
    // populate grpList with the set of groups to which
    // _username belongs in this realm, if any
    return commitUserAuthentication(_username, _password,
      _currentRealm, grpList);

Custom realms must also implement a `Realm` class which extends the `com.sun.appserv.security.AppservRealm` class.

Custom realms must implement the following methods:

    public void init(Properties props) throws BadRealmException,
    NoSuchRealmException

This method is invoked during server startup when the realm is initially loaded. The `props` argument contains the properties defined for this realm in `domain.xml`. The realm can do any initialization it needs in this method. If the method returns without throwing an exception, the Application Server assumes the realm is ready to service authentication requests. If an exception is thrown, the realm is disabled.

    public String getAuthType()

This method returns a descriptive string representing the type of authentication done by this realm.

    public abstract Enumeration getGroupNames(String username) throws
    InvalidOperationException, NoSuchUserException

This method returns an `Enumeration` (of `String` objects) enumerating the groups (if any) to which the given `username` belongs in this realm.

- Previous: Container Security
- Next: JACC Support

- © 2010, Oracle Corporation and/or its affiliates