Running Secure Admin

This section describes how to run secure admin. The section begins with prerequisites for running secure admin.

Prerequisites for Running Secure Admin

Before running GlassFish Server with secure admin enabled, you must make sure that:

1. The DAS is installed, initialized, and running.

2. If one or more remote instances are installed and initialized, they must not be running.

3. Any administration clients you require are installed.

4. The DAS communicates on the -—adminport you configure when you create the domain, and defaults to 4848. An instance communicates on the ASADMIN_LISTENER_PORT system property you specify for the instance.

5. The user name and password sent by remote administration clients (asadmin, administration console, browsers, and IDEs) must exist in the realm and be in the admin group.

6. The keystore and truststore for the domain exist. (They are created by default when you create the domain or install GlassFish Server.)

   If you are not using the default self-signed certificates, you must add your own valid certificates and CA root in the keystore and truststore, respectively.

7. If you are not using the default self-signed certificates, create two aliases corresponding to certificates in the keystore and truststore: one that the DAS will use for authenticating itself in administration traffic, and one that the instances will use for authenticating itself in administration traffic.

An Alternate Approach: Using A User Name and Password for Internal Authentication and Authorization

By default, secure admin uses the GlassFish Server self-signed certificates, via the aliases corresponding to these certificates, to authenticate the DAS and instances with each other and to authorize secure admin operations. Specifically, the DAS uses the (s1as) alias for authenticating itself and authorizing access in administration traffic, and instances use the (glassfish-instance) alias for authenticating themselves and authorizing access in secure admin traffic.

As described in Using Your Own Certificates, you can instead use your own certificates and their associated aliases for authenticating and authorizing the DAS and instances in administration traffic.

As an alternative to this certificate-based authentication and authorization, you can instead use the enable-secure-admin-internal-user(1) subcommand to instruct all servers in the domain to authenticate to each other, and to authorize admin operations submitted to each other, using an existing admin user name and password rather than SSL certificates.

You might want to use the enable-secure-admin-internal-user(1) subcommand if your use case favors the use of a user name and password combination over the use of SSL certificates and aliases.

This generally means that you must:

1. Create a valid admin user.

   asadmin> create-file-user --authrealmname admin-realm --groups 
   asadmin newAdminUsername

2. Create a password alias for the just-created password.

   asadmin> create-password-alias passwordAliasName

3. Use that user name and password for inter-process authentication and admin authorization.

   asadmin>  enable-secure-admin-internal-user 
   --passwordalias passwordAliasName
   newAdminUsername

The following example allows secure admin to use a user name and password alias for authentication and authorization between the DAS and instances, instead of certificates.

asadmin>  enable-secure-admin-internal-user 
--passwordalias passwordAliasName
newAdminUsername

If GlassFish Server finds at least one secure admin internal user, then if secure admin is enabled GlassFish Server processes will not use SSL authentication and authorization with each other and will instead use user name password pairs.

Most users who use this subcommand will need to set up only one secure admin internal user. If you set up more than one secure admin internal user, you should not make any assumptions about which user name and password pair GlassFish Server will choose to use for any given admin request.

As a general practice, you should not use the same user name and password pair for internal admin communication and for admin user login. That is, create at least one admin account specifically for internal admin communication.

You can use the disable-secure-admin-internal-user(1) subcommand to disable secure admin from using the user name (instead of SSL certificates) to authenticate the DAS and instances with each other and to authorize admin operations. To disable multiple user names for authenticating and authorizing access in secure admin, run the disable-secure-admin-internal-user subcommand multiple times.

You can use the list-secure-admin-internal-users(1) subcommand to list the user names for which GlassFish Server authenticate the DAS and instances with each other and authorizes admin operations.

Example of Running enable-secure-admin

The following example shows how to enable secure admin for a domain using the default admin alias and the default instance alias. You must restart the DAS immediately after enabling secure admin.

asadmin> enable-secure-admin

Command enable-secure-admin executed successfully.

The following example shows how to enable secure admin for a domain using an admin alias adtest and an instance alias intest. You can also use this command to modify an existing secure admin configuration to use different aliases.

asadmin> enable-secure-admin --adminalias adtest --instancealias intest

The following example shows how to disable secure admin:

asadmin> disable-secure-admin

Command disable-secure-admin executed successfully.

You can use the following command to see the current state of secure admin in a domain:

asadmin> get secure-admin.enabled

secure-admin.enabled=false

Command get executed successfully.