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 administration realms. In addition, you can set up LDAP, JDBC, digest, 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.

Administration realm

The administration 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 about 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.

Digest realm

Digest Authentication authenticates a user based on a user name and a password. However, the authentication is performed by transmitting the password in an encrypted form.

Solaris realm

Enterprise Server gets user credentials from the Solaris operating system. This realm is supported on the Solaris 9 and Solaris 10 operating systems. Consult your Solaris documentation for information about managing users and groups in the Solaris realm.

Custom realm

You can create other repositories for user credentials, such as a relational database or third-party components. For more information about custom realms, see the Administration Console online help. For instructions on creating a custom realm, see Creating a Custom Realm in Sun GlassFish Enterprise Server v3 Application Development Guide.

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 Update an Authentication Realm

• To Delete an Authentication Realm

• To Configure a JDBC or Digest Authentication Realm

To Create an Authentication Realm

Use the create-auth-realm subcommand in remote mode to create an authentication realm.

1. Ensure that the server is running.

   Remote subcommands require a running server.

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

   Information about properties for this subcommand is included in this help page.

Creating a Realm

This example creates a realm named db.

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

See Also

You can also view the full syntax and options of the subcommand by typing asadmin help create-auth-realm at the command line.

For information on creating a custom realm, see Creating a Custom Realm in Sun GlassFish Enterprise Server v3 Application Development Guide.

To List Authentication Realms

Use the list-auth-realms subcommand in remote mode to list the existing authentication realms.

1. Ensure that the server is running.

   Remote subcommands require a running server.

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

Listing Realms

This example lists the authentication realms on localhost.

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

See Also

You can also view the full syntax and options of the subcommand by typing asadmin help list-auth-realms at the command line.

To Update an Authentication Realm

Use the set subcommand to modify an existing authentication realm.

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

2. Modify the values for the specified thread pool by using the set(1) subcommand.

   The thread pool is identified by its dotted name.

3. To apply your changes, restart Enterprise Server.

   See To Restart a Domain.

To Delete an Authentication Realm

Use the delete-auth-realm subcommand in remote mode to delete an existing authentication realm.

1. Ensure that the server is running.

   Remote subcommands require a running server.

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

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

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

5. To apply your changes, restart Enterprise Server. See To Restart a Domain.

Deleting a Realm

This example deletes an authentication realm named db.

asadmin> delete-auth-realm db
Command delete-auth-realm executed successfully.

See Also

You can also view the full syntax and options of the subcommand by typing asadmin help delete-auth-realm at the command line.

To Configure a JDBC or Digest Authentication 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 type realm instead of the connection pool prevents other applications from browsing the database tables for user credentials.

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 connection pool for the database.

   See To Create a JDBC Connection Pool.

4. Create a JDBC resource for the database.

   To Create a JDBC Resource

5. Create a realm.

   For instructions, see To Create an Authentication Realm.

   ---

   Note - The JAAS context should be jdbcDigestRealm for digest authentication or jdbcRealm for other authentication types.

   ---

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

   Modify the deployment descriptor that is associated with your application.

   • For an enterprise application in an Enterprise Archive (EAR) file, modify the sun-application.xml file.

   • For a web application in a Web Application Archive (WAR) file, modify the web.xml file.

   • For an enterprise bean in an EJB JAR file, modify the sun-ejb-jar.xml file.

   For more information about how to specify a realm, see How to Configure a Realm in Sun GlassFish Enterprise Server v3 Application Development Guide.

7. 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.

8. Verify that the database is running.

   If needed, see To Start the Database

9. To apply the authentication, restart the server.

   See To Restart a Domain.

Assigning a Security Role

This 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>