| Skip Navigation Links | |
| Exit Print View | |
|
Oracle GlassFish Server 3.1 Security Guide |
1. Administering System Security
2. Administering User Security
3. Administering Message Security
4. Administering Security in Cluster Mode
5. Managing Administrative Security
Secure Administration Overview
How Secure Admin Works: The Big Picture
Functions Performed by Secure Admin
Which Administration Account is Used?
What Authentication Methods Are Used for Secure Administration?
Understanding How Certificate Authentication is Performed
Self-Signed Certificates and Trust
An Alternate Approach: Using Distinguished Names to Specify Certificates
Considerations When Running GlassFish Server With Default Security
Prerequisites for Running Secure Admin
An Alternate Approach: Using A User Name and Password for Internal Authentication and Authorization
Example of Running enable-secure-admin
Additional Considerations When Creating Local Instances
Upgrading an SSL-Enabled Secure GlassFish Installation to Secure Admin
6. Running in a Secure Environment
Secure admin is a domain-wide setting. It affects the DAS and all instances and all administration clients. This section describes the following topics:
What Authentication Methods Are Used for Secure Administration?
An Alternate Approach: Using Distinguished Names to Specify Certificates
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 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.
If only one administration account exists in the realm, GlassFish Server 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, GlassFish Server 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 GlassFish Server 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.
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.
Table 5-1 shows which authentication methods are employed when secure admin is enabled or disabled.
Table 5-1 Authentication Methods Employed
|
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:
SSL on the instance asks the DAS to provide an SSL/TLS certificate.
The DAS sends the certificate with the alias you specified using the --adminalias option when you ran the enable-secure-admin subcommand.
SSL on the instance makes sure the certificate is valid and GlassFish Server 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.
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.
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.
The self-signed certificates that GlassFish Server 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 Figure 5-1.
Figure 5-1 Sample Browser Response to 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. )
D:\glassfish3\glassfish\bin>asadmin enable-secure-admin
Command enable-secure-admin executed successfully.
D:\glassfish3\glassfish\bin>asadmin stop-domain domain1
Waiting for the domain to stop .......
Command stop-domain executed successfully.
D:\glassfish3\glassfish\bin>asadmin start-domain domain1
Waiting for domain1 to start ..............................
Successfully started the domain : domain1
domain Location: D:\glassfish3\glassfish\domains\domain1
Log File: D:\glassfish3\glassfish\domains\domain1\logs\server.log
Admin Port: 4848
Command start-domain executed successfully.
D:\glassfish3\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.
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 GlassFish Server 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
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 enable-secure-admin-principal(1) subcommand provides an alternate approach. enable-secure-admin-principal instructs GlassFish Server 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 GlassFish Server 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, GlassFish Server 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:
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 GlassFish Server 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:
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, GlassFish Server 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 GlassFish Server 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 GlassFish Server 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:
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 disable-secure-admin-principal(1) 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 list-secure-admin-principals(1) subcommand to list the certificates for which GlassFish Server accepts admin requests from clients.
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, GlassFish Server includes a unique, generated "domain ID" that servers use to ensure that admin requests from other GlassFish Servers 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."
|