docs/security-guide/src/main/asciidoc/administrative-security.adoc

type=page
status=published
title=Managing Administrative Security
next=running-in-secure-environment.html
prev=security-in-cluster-mode.html
~~~~~~

= Managing Administrative Security

[[GSSCG00039]][[gknqh]]


[[managing-administrative-security]]
== 5 Managing Administrative Security

This chapter describes how to manage administrative security by using
the secure administration feature.

This chapter assumes that you are familiar with security features such
as authentication, authorization, and certificates. If you are not,
first see link:system-security.html#ablnk[Administering System Security].

Instructions for accomplishing the tasks specific to {productName} by
using the Administration Console are contained in the Administration
Console online help.

* link:#gkocp[Secure Administration Overview]
* link:#gkofl[How Secure Admin Works: The Big Picture]
* link:#gkofe[Considerations When Running {productName} With Default Security]
* link:#gkomz[Running Secure Admin]
* link:#gkolu[Additional Considerations When Creating Local Instances]
* link:#gkqah[Secure Admin Use Case]
* link:#gkodn[Upgrading an SSL-Enabled Secure GlassFish Installation to Secure Admin]

[[gkocp]][[GSSCG00162]][[secure-administration-overview]]

=== Secure Administration Overview

The secure administration feature allows an administrator to secure all
administrative communication between the domain administration server
(DAS), any remote instances, and administration clients such as the
`asadmin` utility, the administration console, and REST clients.

In addition, secure administration helps to prevent DAS-to-DAS and
instance-to-instance traffic, and carefully restricts
administration-client-to-instance traffic.

The secure administration feature, which is henceforth referred to as
secure admin, provides a secure environment, in which you can be
confident that rogue users or processes cannot intercept or corrupt
administration traffic or impersonate legitimate {productName} components.

When you install {productName} or create a new domain, secure admin
is disabled by default. When secure admin is disabled, {productName}
does not encrypt administrative communication among the system
components and does not accept administrative connections from remote hosts.

The following subcommands enable and disable secure admin:

* enable-secure-admin +
The `enable-secure-admin` subcommand turns on
secure admin. {productName} uses SSL encryption to protect subsequent
administrative traffic and will accept remote administrative
connections. Enabling secure admin affects the entire domain, including
the DAS and all instances. The DAS must be running, and not any
instances, when you run `enable-secure-admin`. You must restart the DAS
immediately after enabling secure admin, and then start any instances
you want to run.
+
[NOTE]
====
The `enable-secure-admin` subcommand fails if any administrative user
has a blank password.
====

* disable-secure-admin +
The `disable-secure-admin` subcommand turns off
secure admin. {productName} no longer encrypts administrative
messages and will no longer accept remote administration connections.
Disabling secure admin affects the entire domain, including the DAS and
all instances. The DAS must be running , and not any instances, when you
run `disable-secure-admin`. You must restart the DAS immediately after
disabling secure admin, and then start any instances you want to run.
+
If secure admin is not enabled, this subcommand has no effect.

This section describes how to use these commands to run secure admin,
and the implications of doing so.

[[gkofl]][[GSSCG00163]][[how-secure-admin-works-the-big-picture]]

=== How Secure Admin Works: The Big Picture

Secure admin is a domain-wide setting. It affects the DAS and all
instances and all administration clients. This section describes the
following topics:

* link:#gkqce[Functions Performed by Secure Admin]
* link:#gkocv[Which Administration Account is Used?]
* link:#gkodi[What Authentication Methods Are Used for Secure Administration?]
* link:#gkpex[Understanding How Certificate Authentication is Performed]
* link:#gkoey[What Certificates Are Used?]
* link:#glgmy[An Alternate Approach: Using Distinguished Names to Specify Certificates]
* link:#gkqjj[Guarding Against Unwanted Connections]

[[gkqce]][[GSSCG00227]][[functions-performed-by-secure-admin]]

==== Functions Performed by Secure Admin

The `enable-secure-admin` subcommand performs the following functions.
Subsequent sections describe these functions in more detail.

* Enables the secure admin behavior, optionally setting which aliases
  are to be used for identifying the DAS and instance certificates.

* Adjusts all configurations in the domain, including default-config.

* Adjusts Grizzly settings:
** SSL/TLS is enabled in the DAS's admin listener and the instances'
   admin listeners.
** Port unification (that is, HTTP and HTTPS are handled by the same port),
   http—to—https redirection, and client authentication
  (client-auth=want) are enabled.
** Configures SSL to use the administration truststore.
** Configures SSL to use the administration keystore and the correct
   alias (for the self-signed cert) for authenticating itself.
   (You can use your own certificate instead, as described in link:#gkped[
   Using Your Own Certificates].

+
The Grizzly configuration on the DAS and each instance is identical,
with the exception that the DAS uses the `s1as` alias for SSL/TLS
authentication and the instances use the `glassfish-instance` alias.
(These alias names are the default, and you can change them.) +
A server restart is required to change the Grizzly adapter behavior. +
The restart also synchronizes the restarted instances. When you start
the instances, the DAS delivers the updated configuration to the instances.

[[gkocv]][[GSSCG00228]][[which-administration-account-is-used]]

==== Which Administration Account is Used?

If only one administration account exists in the realm, {productName}
treats that account as the current default administration account. In
this case, when you run an `asadmin` command, you do not need to specify
the username. If a password for that username is required, you need to
specify it, typically by using the `--passwordfile` option or by letting
`asadmin` prompt you for it.

By default, {productName} includes a single account for user "admin"
and an empty password. Therefore, if you make no other changes before
you enable secure admin, "admin" is the initial default username and no
password is required. You need to decide whether enabling secure admin
without also requiring a password makes sense in your environment.

If multiple admin accounts exist, then {productName} does not
recognize any admin username as the default. You must then specify a
valid username via the `-—user` option when you use the `asadmin`
command (or by or defining the `AS_ASDMIN_USER` environment variable),
and its associated password (if the associated password is not empty).

The username and password used for a login attempt must match the
username and password (if required) for an account defined in the realm,
and you must have set up the account as a member of the admin group.

[[gkodi]][[GSSCG00229]][[what-authentication-methods-are-used-for-secure-administration]]

==== What Authentication Methods Are Used for Secure Administration?

The secure admin feature enforces security via the following
authentication methods:

* The DAS and instances authenticate to each other via mutual (two-way)
SSL/TLS certificate authentication. The DAS authenticates to clients via
one-way SSL/TLS certificate authentication.
+
The domain creation process creates a default keystore and truststore,
plus a default private key for the DAS. Secure admin uses this initial
configuration to set up the truststore so that the DAS and instances
always trust each other.
* Remote administration clients (`asadmin`, administration console,
browsers, and IDEs) must accept the public certificate presented by the
DAS. If accepted, remote administration clients then send a user name
and password (HTTP Basic authentication) in the HTTP Authorization
header. The receiving DAS or instance makes sure those credentials are
valid in its realm, and authenticates and authorizes the user.
* A locally-running `asadmin` (that is, connecting to an instance on the
same host) authenticates and authorizes to the co-located instance using
a locally-provisioned password.
* Credentials or other sensitive information sent over the network are
always encrypted if secure admin is enabled. No credentials are sent in
the clear if secure admin is enabled. (If secure admin is disabled,
credentials are sent in the clear.) Messages between administration
clients and the DAS, between the DAS and remote instances, and between
local administration clients and instances are encrypted using SSL/TLS.
This is true even if you explicitly set the `asadmin` `-—secure` option
to false.

link:#gkobl[Table 5-1] shows which authentication methods are employed
when secure admin is enabled or disabled.

[[sthref35]][[gkobl]]

Table 5-1 Authentication Methods Employed

[width="100%",cols="30%,30%,40%",options="header",]
|===
|Access Method |When Secure Admin is Disabled |When Secure Admin is Enabled

|Remote administration access to the DAS
|Rejected.
|Username/password authentication. (Client must also accept server certificate.)

|Communication between DAS and instances
|Cleartext messages. No mutual authentication.
|SSL-encrypted messages. SSL mutual authentication using certificates.

|Communication between administration clients and DAS
|Cleartext messages. No DAS authentication.
|SSL-encrypted messages. DAS uses SSL certificate server authentication.

|Local asadmin client to instance on same node
|Cleartext messages. Locally-provisioned password mechanism is used.
|SSL-encrypted messages. Locally-provisioned password mechanism is used.
|===


[[gkpex]][[GSSCG00230]][[understanding-how-certificate-authentication-is-performed]]

==== Understanding How Certificate Authentication is Performed

The domain creation process creates a primary (private) key and a
self-signed certificate for the DAS, and a separate private key and
self-signed certificate for remote instances.

Then, when you enable secure admin, the following actions are performed:

* Both private keys are stored in the domain-wide DAS keystore file, keystore.jks.
* Both public certificates are stored in the domain-wide DAS truststore
  file, cacerts.jks.

When the DAS sends a message to an instance:

1. SSL on the instance asks the DAS to provide an SSL/TLS certificate.
2. The DAS sends the certificate with the alias you specified using the
`--adminalias` option when you ran the `enable-secure-admin` subcommand.
3. SSL on the instance makes sure the certificate is valid and
{productName} makes sure that the security Principal associated with
the incoming request (provided automatically by Grizzly and the SSL/TLS
Java implementation) matches the Principal associated with the
adminalias from the instance's truststore.

[[gkoey]][[GSSCG00231]][[what-certificates-are-used]]

==== What Certificates Are Used?

When you enable secure admin, you can optionally set the `--adminalias`
and `--instancealias` options that tell secure admin which aliases to
use for the DAS and instance certificates.

The DAS uses the alias associated with the `--instancealias` option to
check incoming requests that use SSL/TLS cert authentication.
Conversely, instances use the alias associated with the `--adminalias`
option to check incoming requests with certificate authentication.

By default, `--adminalias` of the `enable-secure-admin` subcommand uses
the `s1as` alias, and the `--instancealias` option uses the
`glassfish-instance` alias, both of which identify the default
self-signed certificates.

You can use your tool of choice, such as keytool, to list the default
self-signed certificates in the keystore, similar to the following:

[NOTE]
====
You can list the contents of the keystore without supplying a password.
However, for a request that affects the private key, such as the
keytool.exe `--certreq` option, the keystore password is required. This
is the master password and has a default value of changeit unless you
change it with the `change-master-password` subcommand.
====

[source]
----
keytool.exe -list -keystore keystore.jks
Enter keystore password:

*****************  WARNING WARNING WARNING  *****************
* The integrity of the information stored in your keystore  *
* has NOT been verified!  In order to verify its integrity, *
* you must provide your keystore password.                  *
*****************  WARNING WARNING WARNING  *****************

Keystore type: JKS
Keystore provider: SUN

Your keystore contains 2 entries

glassfish-instance, Jan 3, 2011, PrivateKeyEntry,
Certificate fingerprint (MD5): 06:A4:83:84:57:52:9C:2F:E1:FD:08:68:BB:2D:ED:E8
s1as, Jan 3, 2011, PrivateKeyEntry,
Certificate fingerprint (MD5): 8B:7D:5A:4A:32:36:1B:5D:6A:29:66:01:B0:A3:CB:85
----

The `--adminalias` and `--instancealias` values are maintained. Because
of this design, normal instance creation operations (create-instance
over SSH and create-local-instance) apply the up-to-date keystore,
truststore, and configuration to each instance.

[[gkpfi]][[GSSCG00201]][[self-signed-certificates-and-trust]]

===== Self-Signed Certificates and Trust

The self-signed certificates that {productName} uses might not be
trusted by clients by default because a certificate authority does not
vouch for the authenticity of the certificate. If you enable secure
admin and then contact the DAS using an administration client, that
client will detect whether the certificate is automatically trusted.

Browsers will warn you, let you view the certificate, and ask you to
reject the certificate, accept it once, or accept it indefinitely, as
shown in link:#gkqpv[Figure 5-1].

[[GSSCG00002]][[gkqpv]]


.*Figure 5-1 Sample Browser Response to Untrusted Certificate*
image:img/accept-certif.png[
"This screen shot shows how a browser might respond to an untrusted certificate."]


Similarly, the first time `asadmin` receives an untrusted certificate,
it displays the certificate and lets you accept it or reject it, as
follows: (If you accept it, `asadmin` also accepts that certificate in
the future. )

[source]
----
D:\glassfish7\glassfish\bin>asadmin enable-secure-admin
Command enable-secure-admin executed successfully.


D:\glassfish7\glassfish\bin>asadmin stop-domain domain1
Waiting for the domain to stop .......
Command stop-domain executed successfully.

D:\glassfish7\glassfish\bin>asadmin start-domain domain1
Waiting for domain1 to start ..............................
Successfully started the domain : domain1
domain  Location: D:\glassfish7\glassfish\domains\domain1
Log File: D:\glassfish7\glassfish\domains\domain1\logs\server.log
Admin Port: 4848
Command start-domain executed successfully.

D:\glassfish7\glassfish\bin>asadmin list-domains
[
[
  Version: V3
  Subject: CN=machine.oracle.com, OU=GlassFish, O=Oracle Corporation, L=San
ta Clara, ST=California, C=US
  Signature Algorithm: SHA1withRSA, OID = 1.2.840.113549.1.1.5

  Key:  Sun RSA public key, 1024 bits
  modulus: 916043595073784449632358756374297330881618062298549101072702252458856
74079656358328568800001548507219262910864311924824938195045822088563459253216383
21100660819657204757523896415606833471499564071226722478056407102318862796797465
6245090519956376357288295037519504394674686082145398885236913866246525691704749
  public exponent: 65537
  Validity: [From: Tue Jan 04 14:30:08 EST 2011,
               To: Fri Jan 01 14:30:08 EST 2021]
  Issuer: CN=machine.oracle.com, OU=GlassFish, O=Oracle Corporation, L=Sant
a Clara, ST=California, C=US
  SerialNumber: [    4d237540]

Certificate Extensions: 1
[1]: ObjectId: 2.5.29.14 Criticality=false
SubjectKeyIdentifier [
KeyIdentifier [
0000: AF 8B 90 1E 51 9A 80 1B   EB A4 D9 C6 01 8A A0 FD  ....Q...........
0010: DE EC 83 8A                                        ....
]
]

]
  Algorithm: [SHA1withRSA]
  Signature:
0000: 3F 2B 30 CE 97 0B 5E F3   72 0E 60 18 8D 3B 04 DC  ?+0...^.r.`..;..
0010: 26 E6 7A 6F D0 19 CC 26   1D 90 C0 DE 33 4E 53 FB  &.zo...&....3NS.
0020: DC E7 AE 78 9E BA EF 14   86 57 36 D4 3E 9B C9 FB  ...x.....W6.>...
0030: C0 B4 EF 72 27 D9 4F 79   1F 89 91 B8 96 26 33 64  ...r'.Oy.....&3d
0040: 9F 4B 04 4B 83 B9 BF 4D   54 B4 8F 75 17 1A 51 BD  .K.K...MT..u..Q.
0050: F3 69 94 CE 90 95 08 55   2C 07 D2 23 AC AE EC 6D  .i.....U,..#...m
0060: 84 B6 3D 00 FB FE 92 50   37 1A 2D 00 F1 21 5C E6  ..=....P7.-..!\.
0070: 1F 39 26 B2 5D C1 FD C8   B1 4F CC EE 26 84 B8 B5  .9&.]....O..&...

]
Do you trust the above certificate [y|N] -->
----

`asadmin` saves certificates you accept in the file `.asadmintruststore`
in your log-in default directory. You do not generally need to work with
the file directly, but if you delete or move the file, `asadmin` will
prompt you again when it receives untrusted certificates.

Some `asadmin` commands such as run-script can contact an instance
directly to retrieve information (but not to make configuration
changes). The instances do not use the same certificate as the DAS, so
in these cases `asadmin` then prompts you to accept or reject the
instance certificate.

[[gkped]][[GSSCG00202]][[using-your-own-certificates]]

===== Using Your Own Certificates

By default, `--adminalias` of the `enable-secure-admin` subcommand uses
the `s1as` alias, and the `--instancealias` option uses the
`glassfish-instance` alias, both of which identify the default
self-signed certificates.

You can instead have {productName} use your own certificates for this
purpose by first adding your certificates to the keystore and
truststore, and then running `enable-secure-admin` and specifying the
aliases for your certificates.

It is also possible to use `s1as` and `glassfish-instance` as the alias
names for your own certificates. A benefit of doing so is that you would
not have to specify alias names with the `enable-secure-admin`
subcommand.

In addition, your own certificate identified by the `s1as` alias would
be used in all other cases within the domain where the `s1as` alias is
used (by default), such as in the SSL configuration of the IIOP and
http-listener-2 listeners, and as the `encryption.key.alias` and
`signature.key.alias` used for provider configuration in the SOAP
authentication layer for Message Security configuration.

You may find the wide-reaching effect of using the `s1as` alias with
your own certificate to be either a useful feature or an unintended
consequence. Therefore, you should understand the implications of using
the `s1as` alias before doing so.

If you decide to use the `s1as` and `glassfish-instance` aliases with
your own certificates, you will first need to disable secure admin (if
enabled) and then change or delete the exiting `s1as` alias from both
the `keystore.jks` keystore and `cacerts.jks` truststore for the DAS.
You can use the `--changealias` or`--delete` option of `keytool` to
accomplish this. Then, import your own certificates.

When you enable secure admin, the DAS and the instances then have copies
of the same keystore and truststore

[[glgmy]][[GSSCG00232]][[an-alternate-approach-using-distinguished-names-to-specify-certificates]]

==== An Alternate Approach: Using Distinguished Names to Specify Certificates

By default, the DAS uses the alias associated with the `--instancealias`
option to check incoming requests that use SSL/TLS cert authentication.
Conversely, instances use the alias associated with the `--adminalias`
option to check incoming requests with certificate authentication.

The link:reference-manual/enable-secure-admin-principal.html#GSRFM00131[
`enable-secure-admin-principal`] subcommand
provides an alternate approach. `enable-secure-admin-principal`
instructs {productName} to accept admin requests when accompanied by
an SSL certificate with the specified distinguished name (DN).

[NOTE]
====
Any certificate you specify with `enable-secure-admin-principal` must
either be issued by a trusted certificate authority or, if it is
self-signed, must already be in the {productName} truststore.
====

For example, assume that you write your own admin client that uses the
REST interface. When your client establishes the connection, it can
choose which certificate to use for its client cert. You would then
specify the DN of this certificate to `enable-secure-admin-principal`.

You must specify either the DN or the `--alias` option of the
`enable-secure-admin-principal` subcommand.

If you specify the DN, {productName} records the value you specify as
the DN. You specify the DN as a comma-separated list in quotes. For
example,
`"CN=system.amer.oracle.com,OU=GlassFish,O=Oracle Corporation,L=Santa Clara,ST=California,C=US"`.

[NOTE]
====
The `enable-secure-admin-principal` subcommand accepts the string you
enter and does not immediately validate it. However, secure admin must
be able to match the DN you specify in order to use it.
====

If you have sufficient privileges to view the content of the keystore,
you can use keytool to display the DN of a certificate:

[source]
----
keytool.exe -v -list -keystore keystore.jks
Enter keystore password:

Keystore type: JKS
Keystore provider: SUN

Your keystore contains 2 entries

Alias name: glassfish-instance
Creation date: Jul 7, 2011
Entry type: PrivateKeyEntry
Certificate chain length: 1
Certificate[1]:
Owner: CN=systemname.amer.oracle.com-instance, OU=GlassFish,
O=Oracle Corporation, L=Santa Clara, ST=California, C=US
Issuer: CN=systemname.amer.oracle.com-instance, OU=GlassFish, O=Oracle Corporation,
 L=Santa Clara, ST=California, C=US
Serial number: 4e15d6e7
Valid from: Thu Jul 07 11:55:19 EDT 2011 until: Sun Jul 04 11:55:19 EDT 2021
Certificate fingerprints:
         MD5:  05:6E:01:D6:CE:9D:29:DA:55:D9:10:5E:BE:CC:55:05
         SHA1: 2A:6D:A2:52:A5:2B:ED:DE:CD:B4:76:4A:65:9D:B5:79:A6:EA:3C:10
         Signature algorithm name: SHA1withRSA
         Version: 3

Extensions:

#1: ObjectId: 2.5.29.14 Criticality=false
SubjectKeyIdentifier [
KeyIdentifier [
0000: 96 99 36 B6 CF 60 1E 8A   AE 25 75 4E C8 34 AA AB  ..6..`...%uN.4..
0010: E1 3B CF 03                                        .;..
]
]
----

If you use the "`--alias` aliasname" form, then {productName} looks
in its truststore for a certificate with the specified alias and uses
the DN associated with that certificate. alias-name must be an alias
associated with a certificate currently in the truststore. Therefore,
you may find it most useful for self-signed certificates for which you
know the alias.

If you have sufficient privileges to view the contents of the
truststore, you can use keytool to display the alias of a certificate:

[source]
----
keytool.exe -v -list -keystore cacerts.jks
Enter keystore password:
:
:
Alias name: glassfish-instance
Creation date: Jul 7, 2011
Entry type: trustedCertEntry

Owner: CN=systemname.amer.oracle.com-instance, OU=GlassFish, O=Oracle Corporation,
L=Santa Clara, ST=California, C=US
Issuer: CN=systemname.amer.oracle.com-instance, OU=GlassFish, O=Oracle Corporation,
 L=Santa Clara, ST=California, C=US
Serial number: 4e15d6e7
Valid from: Thu Jul 07 11:55:19 EDT 2011 until: Sun Jul 04 11:55:19 EDT 2021
Certificate fingerprints:
         MD5:  05:6E:01:D6:CE:9D:29:DA:55:D9:10:5E:BE:CC:55:05
         SHA1: 2A:6D:A2:52:A5:2B:ED:DE:CD:B4:76:4A:65:9D:B5:79:A6:EA:3C:10
         Signature algorithm name: SHA1withRSA
         Version: 3

Extensions:

#1: ObjectId: 2.5.29.14 Criticality=false
SubjectKeyIdentifier [
KeyIdentifier [
0000: 96 99 36 B6 CF 60 1E 8A   AE 25 75 4E C8 34 AA AB  ..6..`...%uN.4..
0010: E1 3B CF 03                                        .;..
]
]
----

When you run `enable-secure-admin`, {productName} automatically
records the DNs for the admin alias and the instance alias, whether you
specify those values or use the defaults. You do not need to run
`enable-secure-admin-principal` yourself for those certificates.

Other than these certificates, you must run
`enable-secure-admin-principal` for any other DN that {productName}
should authorize to send admin requests. This includes DNs corresponding
to trusted certificates (those with a certificate chain to a trusted
authority.)

You can run `enable-secure-admin-principal` multiple times so that
{productName} accepts admin requests from a client sending a
certificate with any of the DNs you specify.

The following example shows how to specify a DN for authorizing access
in secure administration:

[source]
----
asadmin> enable-secure-admin-principal
"CN=system.amer.oracle.com,OU=GlassFish,
O=Oracle Corporation,L=Santa Clara,ST=California,C=US"

Command enable-secure-admin-principal executed successfully.
----

You can use the link:reference-manual/disable-secure-admin-principal.html#GSRFM00123[`disable-secure-admin-principal`]
subcommand to disable a specific certificate for authenticating and
authorizing access in secure admin. You must specify either the DN or
the `--alias` option of the `disable-secure-admin-principal` subcommand.
To disable multiple certificates for authenticating and authorizing
access in secure admin, run the `disable-secure-admin-principal`
subcommand multiple times.

You can use the link:reference-manual/list-secure-admin-principals.html#GSRFM00200[`list-secure-admin-principals`]
subcommand to list the certificates for which {productName} accepts
admin requests from clients.

[[gkqjj]][[GSSCG00233]][[guarding-against-unwanted-connections]]

==== Guarding Against Unwanted Connections

Secure admin guards against unwanted connections in several ways:

* DAS-to-DAS, instance-to-instance:

** The DAS and the instances have copies of the same truststore, which
contains the public certificate of the DAS and the separate public
certificate that is used by all instances. In addition, {productName}
includes a unique, generated "domain ID" that servers use to ensure that
admin requests from other {productName}s originate from the correct
domain.

** DAS-to-other-DAS communication is not authenticated because each
different DAS will have its own self-signed certificate that is not in
the truststore of the other DAS.

** DAS-to-itself communication is unlikely unless you were to
misconfigure the admin listener port for an instance on the same host so
it is the same as for the DAS. Similarly, instance-to-instance traffic
is unlikely unless you were to misconfigure listener ports for instances
on the same host.
+
To prevent both of these situations, both cases are handled by making
sure that the connecting Principal (alias) is not the running Principal.
secure admin ensures that if the client has authenticated using SSL/TLS
client authentication that the Principal associated with the remote
client is not the same as the current process. That is, the DAS makes
sure that the Principal is not itself. Similarly, each instance ensures
that the client is not an instance. (The instances share the same
self-signed certificate and therefore are mapped to the same Principal.)
* Remote client-to-instance:
+
Remote `asadmin` clients are unable to connect directly to instances. If
the user on host "test1" runs a local command but specifies a remote
instance on host "test2," `asadmin` on test1 will read and send that
locally-provisioned password. The instance on "test2" will have a
different locally-provisioned password and so the authentication attempt
will fail.
+
Therefore, a user on "test1" will not be able to run a remote command
targeting an instance on "test2."

[[gkofe]][[GSSCG00164]][[considerations-when-running-glassfish-server-with-default-security]]

=== Considerations When Running {productName} With Default Security

In {productName}, the default admin account is username "admin" with
an empty password. Admin clients provide empty credentials or none at
all, and all are authenticated and authorized as that default admin
user. None of the participants (clients, DAS, or instances) encrypts
network messages.

If this level of security is acceptable in your environment, no changes
are needed and you do not need to enable secure administration. Imposing
a heightened level of security is optional.

However, consider link:#gkode[Table 5-2], which shows which operations
are accepted and rejected when secure admin is disabled.


[NOTE]
====
When secure admin is disabled, {productName} does allow remote
monitoring (read-only) access via the REST interface.
====


[[sthref37]][[gkode]]

Table 5-2 Accepted and Rejected Operations if Secure Admin is Disabled

[width="100%",cols="30%,25%,45%",options="header",]
|===
|Operation |Run From Same System as DAS |Run From Remote System

|`start-local-instance`
|Functions as expected
|Cannot sync with DAS.
The instance starts but cannot communicate with the DAS.
DAS will not see the instance.

|Any other `asadmin` subcommand
|Functions as expected
|Rejected. A user sees the username/password prompt, but even correct entries are rejected.

|Commands that use SSH. For example, `create-instance`.
|Functions as expected; requires prior SSH configuration.
|Functions as expected; requires prior SSH configuration.
|===


[[gkomz]][[GSSCG00165]][[running-secure-admin]]

=== Running Secure Admin

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

[[gkokc]][[GSSCG00234]][[prerequisites-for-running-secure-admin]]

==== Prerequisites for Running Secure Admin

Before running {productName} 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 {productName}.)
+
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.

[[glgmh]][[GSSCG00235]][[an-alternate-approach-using-a-user-name-and-password-for-internal-authentication-and-authorization]]

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

By default, secure admin uses the {productName} 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 link:#gkped[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
link:reference-manual/enable-secure-admin-internal-user.html#GSRFM00130[
`enable-secure-admin-internal-user`] 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.

[NOTE]
====
If secure admin is enabled, all {productName} processes continue to
use SSL encryption to secure the content of the admin messages,
regardless of how they authenticate to each other.
====

You might want to use the
link:reference-manual/enable-secure-admin-internal-user.html#GSRFM00130[
`enable-secure-admin-internal-user`] 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.
+
[source]
----
asadmin> create-file-user --authrealmname admin-realm --groups
asadmin newAdminUsername
----
2. Create a password alias for the just-created password.
+
[source]
----
asadmin> create-password-alias passwordAliasName
----
3. Use that user name and password for inter-process authentication and
admin authorization.
+
[source]
----
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.

[source]
----
asadmin> enable-secure-admin-internal-user
--passwordalias passwordAliasName
newAdminUsername
----

If {productName} finds at least one secure admin internal user, then
if secure admin is enabled {productName} 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 {productName} 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 link:reference-manual/disable-secure-admin-internal-user.html#GSRFM00122[`disable-secure-admin-internal-user`]
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 link:reference-manual/list-secure-admin-internal-users.html#GSRFM00199[`list-secure-admin-internal-users`]
subcommand to list the user names for which {productName}
authenticate the DAS and instances with each other and authorizes admin
operations.

[[gkqby]][[GSSCG00236]][[example-of-running-enable-secure-admin]]

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

[NOTE]
====
The only indicator that secure admin is enabled is the successful status
from the `enable-secure-admin` subcommand. When secure admin is running,
the DAS and instances do not report the secure admin status.
====

[source]
----
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.

[source]
----
asadmin> enable-secure-admin --adminalias adtest --instancealias intest
----

The following example shows how to disable secure admin:
[source]
----
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:
[source]
----
asadmin> get secure-admin.enabled
secure-admin.enabled=false
Command get executed successfully.
----

[[gkolu]][[GSSCG00166]][[additional-considerations-when-creating-local-instances]]

=== Additional Considerations When Creating Local Instances

If you use `xxx-local-instance` commands to set up local instances,
either leave secure admin disabled, or enable it before you create or
start the instances and leave it that way.

However, if you use `xxx-instance` commands over SSH to manage remote
instances, you can enable and disable secure admin, although this is not
recommended because it can result in an inconsistent security model.

[[gkqah]][[GSSCG00167]][[secure-admin-use-case]]

=== Secure Admin Use Case

This section describes a simple secure admin use case.

In the
`asadmin --secure=false --user me --passwordfile myFile.txt cmd ...` use
case, the user submits a command with `--secure` set to false, and
supplies password credentials.

The important concept to note is that `asadmin` uses HTTPS because of
the DAS redirection, even though the command sets `--secure` to false.
`asadmin` sends the HTTP Authorization header along with the redirected request.

In addition to the flow described here, certificate authentication is
also performed as described in link:#gkqax[Table 5-3]. Also, the
credentials that the user supplies are assumed to be valid administrator
credentials for the DAS.

[[sthref38]][[gkqax]]

Table 5-3 asadmin --secure=false, With Username and Password

[width="100%",cols="34%,33%,33%",options="header",]
|===
|asadmin |Grizzly |AdminAdapter

|Sends HTTP request, no authorization header (because the transport is not secure).
|
|

|
|Returns 3xx status and redirects HTTP to HTTPS.
|

|Follows redirection, this time adding the Authorization header (because transport is now HTTPS).
|
|

|
|
|Authenticates admin user and password from HTTP Authorization
header in the realm Executes command, and responds with success status.
|===


[[gkodn]][[GSSCG00168]][[upgrading-an-ssl-enabled-secure-glassfish-installation-to-secure-admin]]

=== Upgrading an SSL-Enabled Secure GlassFish Installation to Secure Admin

If you enable secure admin on an SSL-enabled {productName}
installation, secure admin uses the existing <ssl cert-nickname> value
as the DAS adminalias for secure admin.