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

Chapter 8 Managing Users and Groups

This chapter describes how to add, delete, and edit the users and groups who can access your server.

Accessing Information About Users and Groups

The Administration Server provides access to your application data about user accounts, group lists, access privileges (ACL), organization units, and other user- and group-specific information.

User and group information is stored either in flat files in text format or in a directory server such as the Sun Java System Directory Server, which supports Lightweight Directory Access Protocol (LDAP). LDAP is an open directory access protocol that runs over TCP/IP and is scalable to a global size and millions of entries.

About Directory Services

A directory server such as the Sun Java System Directory Server enables you to manage all your user information from a single application. You can also configure the directory server to allow your users to retrieve directory information from multiple, easily accessible network locations.

In Web Server 7.0, you can configure three different types of directory services to authenticate and authorize users and groups. If no other directory service is configured, the new directory service created will be set to the value default, irrespective of its type.

When you createa directory service, the server.xml file is updated with the directory service details.

Types of Directory Services

The different types of directory services supported by Web Server 7.0 are:

Note –

If you want to set up distributed administration, the default directory service must be an LDAP-based directory service.

Understanding Distinguished Names (DNs)

A user is an individual in your LDAP database, such as an employee of your company. A group is two or more users who share a common attribute. An organizational unit is a subdivision within your company.

Each user and group in your enterprise is represented by a Distinguished Name (DN) attribute. A DN attribute is a text string that contains identifying information for an associated user, group, or object. You use DNs whenever you make changes to a user or group directory entry. For example, you need to specify DN information each time you create or modify directory entries, set up access controls, and set up user accounts for applications such as mail or publishing.

Web Server

The preceding figure shows a sample DN representation. The following example represents a typical DN for an employee of Sun Microsystems:

uid=doe,,cn=John Doe,o=Sun Microsystems Inc.,c=US

The abbreviations before each equal sign in this example have the following meanings:

DNs may include a variety of name-value pairs. They are used to identify both certificate subjects and entries in directories that support LDAP.

Using LDIF

If you do not currently have a directory, or if you want to add a new subtree to an existing directory, you can use the Directory Server’s Administration Server LDIF import function. This function accepts a file containing LDIF and attempts to build a directory or a new subtree from the LDIF entries. You can also export your current directory to LDIF using the Directory Server’s LDIF export function. This function creates an LDIF-formatted file that represents your directory. Add or edit entries using the ldapmodify command along with the appropriate LDIF update statements.

To add entries to the database using LDIF, first define the entries in an LDIF file, then import the LDIF file from Directory Server.

Working With the Authentication Database

The Authentication Database, also referred to as auth-db, represents a database of known users and the mechanism for authenticating client requests against that database. The server can have multiple auth-db entries configured at the same time and these may be of the same type. The auth-db user databases are used by the ACL processing module.

The server supports the following authentication databases:

  1. LDAP — The user data is stored in an LDAP directory server, such as the Sun Java System Directory Server.

  2. File — The user data is stored in a disk file. This auth-db is particularly convenient for development or small deployments where no centralized user management is available (or desired). The file auth-db supports several different file formats:

    1. keyfile — The keyfile format stores a list of users (and optional group memberships for each user). The password is stored as a one-way (unrecoverable) hash. This is the default format.

    2. digestfile — The digestfile is very similar to the keyfile and also supports the HTTP Digest authentication method.

    3. htaccess — The htaccess is a legacy format and should never be used for new installations or adding new users.

  3. PAM — PAM is the new auth-db supported by Web Server . The PAM auth-db delegates the authentication to the Solaris PAM stack, this enables existing Solaris users on the web server system to authenticate to the web server as well.

    Note –

    PAM auth-db is only supported in Solaris 9 and 10 (or higher) and the web server instance must be running as root.

  4. Kerberos- The gssapi authentication method works with a Kerberos user repository. Web Server 7.0 Update 7 release introduces a suitable auth-db of type Kerberos for use with the gssapi authentication method. The gssapi authentication can only be used with a Kerberos auth-db and vice versa. Compatible browsers (such as IE and Firefox) can authenticate using this method if the user running the browser has a valid Kerberos ticket. The protocol is described in the (now expired) IETF draft draft-brezak-spnego-http-04.txt.

    The gssapi authentication method and the Kerberos auth-db are only supported in Solaris (the client browser may be on any Kerberos-enabled platform). The Kerberos auth-db is configured in server.xml as are all other auth-db elements:


    The default web server principal is "HTTP/hostname" where hostname is the server's hostname. The Kerberos auth-db supports two optional properties which can be used to modify this default:

    servicename Default is HTTP

    hostname Default is the hostname associated with the request.

    For example, the configuration below is equivalent to not specifying servicename:


    The above auth-db element can be added in GUI. To configure perform the following tasks:

    1. Click the Edit Configuration link from Common Tasks Page 

    2. Click the created configuration. 

    3. Click the Access Control tab. 

    4. Under the Authentication Databases tab click New button. 

    5. Under the Database type Kerberos type will be visible. This option is visible only on Solaris platforms. 

    6. Enter the values and click on OK button to create auth-db of type Kerberos

    In order to use the Kerberos authentication, the web server instance must have access to a Kerberos keytab file containing the key for this HTTP/hostname (or as given in the auth-db configuration) principal. Refer to the ktadd command of kadmin(1M) for information on creating this file. By default, the server expects to find a file named keytab in the config directory of the instance. This name and location can be changed with the optional <krb5-keytab-file> element in server.xml.

    The following server.xml configuration is thus equivalent to omitting the <krb5-keytab-file> element (all file paths in server.xml are relative to the config directory of the instance):


    The above needs to be manually added in server.xml if one needs to override the default location.

    A sample ACL entry which instructs the server to require Kerberos authentication for the content under /krb5:

    acl "uri=/krb5/";
    authenticate (user) {
        method = "gssapi";
        database = "my-kerberos";
    deny (all) user="anyone";
    allow (all) user="all";

Creating an Authentication Database

FTo create an authentication database through the Administration Console, click Configurations > Configuration Name > Access Control > Authentication Databases > New button. Check out the Administration Console Inline help for field descriptions. Based on the selected Authentication Database, the fields change. For example, for PAM based Authentication DB, only the authentication DB name is required.

The options required to create an Authentication Database are enumerated here:


  • Authentication Database Name

  • Host Name

  • Port

  • Base DN

Key FIle 

  • Authentication Database Name

  • File Path

Digest File 

  • Authentication Database Name

  • File Path


  • Authentication Database Name


  • Authentication Database Name

To create an authentication database through CLI, execute the following command.

wadm> create-authdb --user=admin --password-file=admin.pwd 
--host=serverhost --port=8989 --config=config1 
--url=ldap://,dc=sun,dc=com LDAP1

See CLI Reference, create-authdb(1).

In the previous example, a URL has been specified for the authentication database. The type of authentication database is specified in this URL scheme. For example, ldap://ds.example.come/dc=example,dc=com configures an LDAP directory server as an authentication database.

Setting Up Users and Groups

The Administration Server enables editing user accounts, group lists, access privileges, organization units, and other user- and group-specific information for both LDAP and File auth-db types.

ProcedureTo Add a User

  1. Click the Configuration tab to see a list of users and select the configuration you need.

  2. Click the Access Control > Users tab.

  3. Click the New button.

  4. Add User Information.

    Enter the user id and password. Optionally enter the group which the user belongs to. The user ID must be unique. In case of LDAP based authentication DB, the Administration Server ensures that the user ID is unique by searching the entire directory from the search base (base DN) down to see if the user ID is in use. Be aware, however, that if you use the Directory Server ldapmodify command line utility (if available) to create a user, that it does not ensure unique user IDs.

    Note –

    Using CLI

    To create a user through CLI, execute the following command.

    wadm> create-user --user=admin --password-file=admin.pwd --host=serverhost 
    --port=8989 --config=config1 --authdb=KEYFILE1 --full-name=keyfile-config1-u1 

    See CLI Reference, create-user(1).

ProcedureTo Add a Group

  1. Select the configuration from the configuration list. Click Configurations tab to get the list.

  2. Click Access Control > Groups tab.

  3. Click the New button.

  4. Enter the Group Name.

  5. From the Add Users To Group section, search and add existing users to the group.

    Note –

    Creating a group in an authentication database like keyfile or digestfile requires atleast one user to be specified.

    Note –

    Using CLI

    To create a group through CLI, execute the following command.

    wadm> create-group --user=admin --password-file=admin.pwd --host=serverhost
    --port=8989 --config=config1 --authdb=LDAP1 group1

    See CLI Reference, create-group(1).

ProcedureTo Delete a User

  1. Select the configuration from the configuration list. Click Configurations tab to get the list.

  2. Click the Access Control > Users tab.

  3. Select the authentication database from which you need to delete the user.

  4. Enter the User ID in the Search Users text box and click the Search button.

  5. Select the user from the UserID column and click the Delete button.

    Caution – Caution –

    Deleting users from a keyfile or digestfile authentication database will delete any associated groups even if the groups contain no members. Groups without members are not allowed in keyfile or digestfile authentication databases.

    Note –

    Using CLI

    To delete a user through CLI, execute the following command.

    wadm> delete-user --user=admin --password-file=admin.pwd --host=serverhost 
    --port=8989 --config config1 --authdb KEYFILE1 user1

    See CLI Reference, delete-user(1).

ProcedureTo Delete a Group

  1. Select the configuration from the configuration list. Click Configurations tab to get the list.

  2. Click the Access Control > Groups tab.

  3. Select the authentication database from which you need to delete the group.

  4. Enter the Group Name in the Search Users text box and click the Search button.

  5. Select the group from the Group Name column and click the Delete button.

    Note –

    Deleting a group does not delete the users belonging to the group. You have to delete the users manually or reassign groups.

    Note –

    Using CLI

    To delete a group through CLI, execute the following command.

    wadm> delete-group --user=admin --password-file=admin.pwd --host=serverhost
    --port=8989 --config config1 --authdb LDAP1 group1

    See CLI Reference, delete-group(1).

Static and Dynamic Groups

A group is a set of objects in an LDAP database. In Web Server 7.0 a group consists of users who share a common attribute. For example, the set of objects might be the number of employees who work in the marketing division of your company. These employees might belong to a group called Marketing.

For LDAP services, there are two ways to define membership of a group: statically and dynamically. Static groups enumerate their member objects explicitly. A static group is a CN and contains uniqueMembers and/or memberURLs and/or memberCertDescriptions. In static groups, the members do not share a common attribute except for the CN=<Groupname> attribute.

Dynamic groups allow you to use a LDAP URL to define a set of rules that match only for group members. In Dynamic Groups, the members do share a common attribute or set of attributes that are defined in the memberURL filter. For example, if you need a group that contains all employees in Sales, and they are already in the LDAP database under

ou=Sales,,” you’d define a dynamic group with the following memberurl:


This group would subsequently contain all objects that have an uid attribute in the tree below the “ou=Sales,o=sun” point; thus, all the Sales members.

For static and dynamic groups, members can share a common attribute from a certificate if you use the memberCertDescription. Note that these attributes will only work if the ACL uses the SSL method.

Once you create a new group, you can add users, or members, to it.

Static Groups

For LDAP services, the Administration Server enables you to create a static group by specifying the same group attribute in the DNs of any number of users. A static group doesn’t change unless you add a user to it or delete a user from it.

Guidelines for Creating Static Groups

Consider the following guidelines when using the Administration Server forms to create new static groups:

Dynamic Groups

A dynamic group has an objectclass of groupOfURLs, and has zero or more memberURL attributes, each of which is a LDAP URL that describes a set of objects.

For LDAP services, Web Server enables you to create a dynamic group when you want to group users automatically based on any attribute, or when you want to apply ACLs to specific groups which contain matching DNs. For example, you can create a group that automatically includes any DN that contains the attribute department=marketing. If you apply a search filter for department=marketing, the search returns a group including all DNs containing the attribute department=marketing. You can then define a dynamic group from the search results based on this filter. Subsequently, you can define an ACL for the resulting dynamic group.

How Web Server Implements Dynamic Groups

Web Server implements dynamic groups in the LDAP server schema as objectclass = groupOfURLs. A groupOfURLS class can have multiple memberURL attributes, each one consisting of an LDAP URL that enumerates a set of objects in the directory. The members of the group would be the union of these sets. For example, the following group contains just one member URL:


This example describes a set that consists of all objects below "" whose department is "marketing." The LDAP URL can contain a search base DN, a scope and filter, however, not a hostname and port. This means that you can only refer to objects on the same LDAP server. All scopes are supported.

The DNs are included automatically, without your having to add each individual to the group. The group changes dynamically, because Web Server performs an LDAP server search each time a group lookup is needed for ACL verification. The user and group names used in the ACL file correspond to the cn attribute of the objects in the LDAP database.

Note –

Web Server uses the cn (commonName) attribute as group name for ACLs.

The mapping from an ACL to an LDAP database is defined both in the dbswitch.conf configuration file (which associates the ACL database names with actual LDAP database URLs) and the ACL file (which defines which databases are to be used for which ACL). For example, if you want base access rights on membership in a group named "staff," the ACL code looks up an object that has an object class of groupOf<anything> and a CN set to "staff." The object defines the members of the group, either by explicitly enumerating the member DNs (as is done for groupOfUniqueNames for static groups), or by specifying LDAP URLs (for example, groupOfURLs).

Groups Can Be Static and Dynamic

A group object can have both objectclass = groupOfUniqueMembers and objectclass = groupOfURLs; therefore, both "uniqueMember" and "memberURL" attributes are valid. The group’s membership is the union of its static and dynamic members.

Dynamic Group Impact on Server Performance

There is a server performance impact when using dynamic groups. If you are testing group membership, and the DN is not a member of a static group, Web Server checks all dynamic groups in the database’s baseDN. Web Server accomplishes this task by checking if each memberURL matches by checking its baseDN and scope against the DN of the user, and then performing a base search using the user DN as baseDN and the filter of the memberURL. This procedure can amount to a large number of individual searches.

Guidelines for Creating Dynamic Groups

Consider the following guidelines when using the Administration Server to create new dynamic groups:

Table 8–1 Dynamic Groups: Required Parameters

Parameter Name  



The Distinguished Name (DN) of the search base, or point from which all searches are performed in the LDAP directory. This parameter is often set to the suffix or root of the directory, such as "".


A list of the attributes to be returned by the search. To specify more than one, use commas to delimit the attributes (for example, "cn,mail,telephoneNumber"); if no attributes are specified, all attributes are returned. Note that this parameter is ignored for dynamic group membership checks.


The scope of the search, which can be one of these values: 

  • base retrieves information only about the distinguished name (<base_dn>) specified in the URL.

  • one retrieves information about entries one level below the distinguished name (<base_dn>) specified in the URL. The base entry is not included in this scope.

  • sub retrieves information about entries at all levels below the distinguished name (<base_dn>) specified in the URL. The base entry is included in this scope.

    This parameter is required.


Search filter to apply to entries within the specified scope of the search. If you are using the Administration Server forms, you must specify this attribute. Note that the parentheses are required. 

This parameter is required. 

Note that the <attributes>, <scope>, and <(filter)> parameters are identified by their positions in the URL. If you do not want to specify any attributes, you still need to include the question marks delimiting that field.