Chapter 7 Administering User Security

This chapter provides instructions for administering user security in the Sun GlassFish^TM Enterprise Server v3 Prelude environment by using the asadmin command-line utility.

Enterprise Server enforces its authentication and authorization policies upon realms, users, and groups. This chapter assumes that you are familiar with security features such as authentication, authorization, and certificates. If you are not, see Chapter 6, Administering System Security.

The following topics are addressed here:

• Administering Authentication Realms

• Administering File Users

Instructions for accomplishing these tasks by using the Administration Console are contained in the Administration Console online help.

Administering Authentication Realms

An authentication realm, also called a security policy domain or security domain, is a scope over which the Enterprise Server defines and enforces a common security policy. Enterprise Server is preconfigured with the file, certificate, and admin-realm realms. In addition, you can set up ldap, jdbc, solaris, or custom realms. An application can specify which realm to use in its deployment descriptor. If the application does not specify a realm, Enterprise Server uses its default realm (file).

file realm

Enterprise Server stores user credentials locally in a file named keyfile. The file realm is the initial default realm.

admin-realm realm

The admin-realm is also a file realm and stores administrator user credentials locally in a file named admin-keyfile.

certificate realm

Enterprise Server stores user credentials in a certificate database. When using the certificate realm, the server uses certificates with the HTTPS protocol to authenticate web clients.

ldap realm

Enterprise Server gets user credentials from a Lightweight Directory Access Protocol (LDAP) server such as the Directory Server. LDAP is a protocol for enabling anyone to locate organizations, individuals, and other resources such as files and devices in a network, whether on the public Internet or on a corporate intranet. Consult your LDAP server documentation for information on managing users and groups in the ldap realm.

jdbc realm

Enterprise Server gets user credentials from a database. The server uses the database information and the enabled jdbc realm option in the configuration file.

Custom realm

You can create other repositories for user credentials, such as a relational database or third-party components. For more information on custom realms, see the Administration Console online help.

The Enterprise Server authentication service can govern users in multiple realms.

The following tasks and information are used to administer authentication realms:

• To Create an Authentication Realm

• To List Authentication Realms

• To Delete an Authentication Realm

• To Configure a JDBC Realm

To Create an Authentication Realm

The remote create-auth-realm command enables you to create an authentication realm.

1. Ensure that the server is running.

   Remote commands require a running server.

2. Create a realm by using the create-auth-realm(1) command.

Example 7–1 Creating a Realm

The following example command creates a realm named db:

asadmin create-auth-realm --classname com.iplanet.ias.security.auth.realm.DB.Database 
--property defaultuser=admin:Password=admin db

Information similar to the following is displayed:

Command create-auth-realm executed successfully.

See Also

To see the full syntax and options of the command, type asadmin create-auth-realm --help at the command line.

To List Authentication Realms

The remote list-auth-realms command enables you to list the existing authentication realms.

1. Ensure that the server is running.

   Remote commands require a running server.

2. List realms by using the list-auth-realms(1) command.

Example 7–2 Listing Realms

The following example command lists the authentication realms on localhost:

asadmin list-auth-realms

Information similar to the following is displayed:

db
certificate
file
admin-realm
Command list-auth-realms executed successfully.

See Also

To see the full syntax and options of the command, type asadmin list-auth-realms --help at the command line.

To Delete an Authentication Realm

The remote delete-auth-realm command enables you to delete an existing authentication realm.

1. Ensure that the server is running.

   Remote commands require a running server.

2. Obtain the exact name of the realm that you are deleting.

   To list the existing realms:

   asadmin list-auth-realms

3. If necessary, notify users that the realm is being deleted.

4. Delete the realm by using the delete-auth-realm(1) command.

5. To apply your changes, restart Enterprise Server.

   1. Stop Enterprise Server.

      For instructions, see To Stop a Domain (or Server).

   2. Start Enterprise Server.

      For instructions, see To Start a Domain (or Server).

Example 7–3 Deleting a Realm

The following example command deletes an authentication realm named db localhost:

asadmin delete-auth-realm db

Information similar to the following is displayed:

Command delete-auth-realm executed successfully.

See Also

To see the full syntax and options of the command, type asadmin delete-auth-realm --help at the command line.

To Configure a JDBC Realm

Enterprise Server enables you to specify a user's credentials (user name and password) in the jdbc realm instead of in the connection pool. Using the jdbc realm instead of the connection pool prevents other applications from browsing the database tables for user credentials.

By default, storage of passwords as clear text is not supported in the jdbc realm. Under normal circumstances, passwords should not be stored as clear text.

1. Create the database tables in which to store user credentials for the realm.

   How you create the database tables depends on the database that you are using.

2. Add user credentials to the database tables that you created.

   How you add user credentials to the database tables depends on the database that you are using.

3. Create a jdbc realm.

   For instructions, see To Create an Authentication Realm.

4. Modify the deployment descriptor to specify the jdbc realm.

   Modify the deployment descriptor that is associated with your application.

   For more information about how to specify a realm, see How to Configure a Realm in Sun GlassFish Enterprise Server v3 Prelude Developer’s Guide.

5. Assign security roles to users in the realm.

   To assign a security role to a user, add a security-role-mapping element to the deployment descriptor that you modified.

Example 7–4 Assigning a Security Role

The following example shows a security-role-mapping element that assigns the security role Employee to user Calvin:

<security-role-mapping>
    <role-name>Employee</role-name>
    <principal-name>Calvin</principal-name>
  </security-role-mapping>

Administering File Users

A user is an individual (or application program) identity that is defined in Enterprise Server. A user who has been authenticated is sometimes called a principal.

As the administrator, you are responsible for integrating users into the Enterprise Server environment so that their credentials are securely established and they are provided with access to the applications and services that they are entitled to use.

The following tasks are used to manage users:

• To Create a File User

• To List File Users

• To List File Groups

• To Update a File User

• To Delete a File User

To Create a File User

The remote create-file-user command enables you to create a new user by adding a new entry to the keyfile. The entry includes the user name, password, and any groups for the user. Multiple groups can be specified by separating the groups with colons (:).

Creating a new file realm user is a dynamic event and does not require server restart.

1. Ensure that the server is running.

   Remote commands require a running server.

2. If the user will belong to a particular group, list the current file groups:

   asadmin list-file-groups –user admin –passwordfile passwords.txt

3. Create a file user by using the create-file-user(1) command.

Example 7–5 Creating a User

The following example command create user Jennifer on the default realm file (no groups are specified):

asadmin create-file-user --user admin 
--passwordfile=c:\tmp\asadminpassword.txt Jennifer

Information similar to the following is displayed:

Command create-file-user executed successfully.

See Also

To see the full syntax and options of the command, type asadmin create-file-user --help at the command line.

To List File Users

The remote list-file-users command enables you to list the users that are in the keyfile.

1. Ensure that the server is running.

   Remote commands require a running server.

2. List users by using the list-file-users(1) command.

Example 7–6 Listing File Users

The following example command lists file users on the default file realm file:

asadmin list-file-users

Information similar to the following is displayed:

Jennifer
Command list-file-users executed successfully.

See Also

To see the full syntax and options of the command, type asadmin list-file-users --help at the command line.

To List File Groups

A group is a category of users classified by common traits, such as job title or customer profile. For example, users of an e-commerce application might belong to the customer group, and the big spenders might also belong to the preferred group. Categorizing users into groups makes it easier to control the access of large numbers of users. A group is defined for an entire server and realm. A user can be associated with multiple groups of users.

A group is different from a role in that a role defines a function in an application, while a group is a set of users who are related in some way. For example, in the personnel application there might be groups such as full-time, part-time, and on-leave. Users in these groups are all employees (the employee role). In addition, each user has its own designation that defines an additional level of employment.

The remote list-file-groups command lists groups for a file user, or all file groups if the --name option is not specified.

1. Ensure that the server is running.

   Remote commands require a running server.

2. List file groups by using the list-file-groups(1)command.

Example 7–7 Listing Groups for a User

The following example command lists the groups for user joesmith:

asadmin list-file-groups --name joesmith

Information similar to the following is displayed:

staff
manager
Command list-file-groups executed successfully

To Update a File User

The remote update-file-user command enables you to modify the information in the keyfile for a specified user.

1. Ensure that the server is running.

   Remote commands require a running server.

2. Update the user information by using the update-file-user(1) command.

3. To apply your changes, restart Enterprise Server.

   1. Stop Enterprise Server.

      For instructions, see To Stop a Domain (or Server).

   2. Start Enterprise Server.

      For instructions, see To Start a Domain (or Server).

Example 7–8 Updating a User

The following command updates the groups for user Jennifer:

asadmin update-file-user --passwordfile 
c:\tmp\asadminpassword.txt --groups 
staff:manager:engineer Jennifer

Information similar to the following is displayed:

Command update-file-user executed successfully.

See Also

To see the full syntax and options of the command, type asadmin update-file-user --help at the command line.

To Delete a File User

The remote delete-file-user command enables you to remove a user entry from the keyfile by specifying the user name.

1. Ensure that the server is running.

   Remote commands require a running server.

2. Obtain the exact name of the file user that you are deleting.

   To list the existing file users:

   asadmin list-file-users

3. Delete the user by using the delete-file-user(1) command.

Example 7–9 Deleting a User

The following example command deletes user Jennifer from the default file realm:

asadmin delete-file-user Jennifer

Information similar to the following is displayed:

Command delete-file-user executed successfully.

See Also

To see the full syntax and options of the command, type asadmin delete-file-user --help at the command line.