Oracle GlassFish Server 3.0.1 Administration Guide

About System Security in GlassFish Server

Security is about protecting data, that is, how to prevent unauthorized access or damage to data that is in storage or in transit. The GlassFish Server is built on the Java security model, which uses a sandbox where applications can run safely, without potential risk to systems or users. System security affects all the applications in the GlassFish Server environment.

System security features include the following:


Authentication is the way in which an entity (a user, an application, or a component) determines that another entity is who it claims to be. An entity uses security credentials to authenticate itself. The credentials might be a user name and password, a digital certificate, or something else. Usually, servers or applications require clients to authenticate themselves. Additionally, clients might require servers to authenticate themselves. When authentication is bidirectional, it is called mutual authentication.

When an entity tries to access a protected resource, GlassFish Server uses the authentication mechanism configured for that resource to determine whether to grant access. For example, a user can enter a user name and password in a web browser, and if the application verifies those credentials, the user is authenticated. The user is associated with this authenticated security identity for the remainder of the session.

Authentication Types

Within its deployment descriptors, an application specifies the type of authentication that it uses. GlassFish Server supports the following types of authentication:


Uses the server's built-in login dialog box. The communication protocol is HTTP (SSL optional). There is no user-credentialed encryption unless using SSL.


The application provides its own custom login and error pages. The communication protocol is HTTP (SSL optional). There is no user-credentialed encryption unless using SSL.


The server authenticates the client using a public key certificate. The communication protocol is HTTPS (HTTP over SSL). User-credentialed encryption is SSL.


The server authenticates a user based on a user name and a password. The authentication is performed by transmitting the password in an encrypted form which is much more secure than the simple Base64 encoding used by BASIC authentication. The communication protocol is HTTPS.


Passwords are your first line of defense against unauthorized access to the components and data of GlassFish Server. For Information about how to use passwords for GlassFish Server, see Administering Passwords.

Master Password and Keystores

The master password is an overall shared password and is the most sensitive piece of data in the system. It is never used for authentication and is never transmitted over the network. You can choose to enter the master password manually when required, or obscure it in a file.

The master password is the password for the secure keystore. When a new GlassFish Server domain is created, a new self-signed certificate is generated and stored in the relevant keystore, which is locked using the master password (default password changeit). If the master password is not the default (that is, you have changed it), you are prompted for the master password. After the correct master password is entered, the domain starts.

Administration Password

The administration password, also known as the admin password, is used to invoke the Administration Console and the asadmin utility. This password is usually set during installation, but it can be changed. For instructions, see To Change the Administration Password.

Encoded Passwords

Files that contain encoded passwords need to be protected using file system permissions. These files include the following:

For instructions, see To Set a Password From a File.

Web Browsers and Password Storage

Most web browsers can save login credentials entered through HTML forms. This function can be configured by the user and also by applications that employ user credentials. If the function is enabled, then credentials entered by the user are stored on their local computer and retrieved by the browser on future visits to the same application. This function is convenient for users, but can also be a security risk. The stored credentials can be captured by an attacker who gains access to the computer, either locally or through some remote compromise. Further, methods have existed whereby a malicious web site can retrieve the stored credentials for other applications, by exploiting browser vulnerabilities or through application-level cross-domain attacks.

The easiest way to globally prevent browsers from storing credentials entered into an HTML form is to include the attribute autocomplete="off" within the FORM tag or within the relevant INPUT tags. However, this workaround is not possible when an HTML form is not used to input login credentials. This is often the case with dynamic pages generated through scripting languages, like the login page for the GlassFish Server Administration Console. To prevent your web browser from saving login credentials for the GlassFish Server Administration Console, choose “No” or “Never for this page” when prompted by the browser during login.

Password Aliases

To avoid storing passwords in the domain configuration file in clear text, you can create an alias for a password. This process is also known as encrypting a password. For more information, see Administering Password Aliases.

Single Sign-on

With single sign-on, a user who logs in to one application becomes implicitly logged in to other applications that require the same authentication information. Single sign-on is based on groups. All web applications whose deployment descriptor defines the same group and uses the same authentication method (BASIC, FORM, or CLIENT-CERT) share single sign-on.

On GlassFish Server, single sign-on is enabled by default for virtual servers, allowing multiple applications in one virtual server to share the user authentication state.


Authorization, also known as access control, is the means by which users are granted permission to access data or perform operations. After a user is authenticated, the user's level of authorization determines what operations the owner can perform. A user's authorization is based on the user's role.


A role defines which applications and what parts of each application users can access and what those users or groups can do with the applications. For example, in a personnel application, all employees might be able to see phone numbers and email addresses, but only managers have access to salary information. This application would define at least two roles: employee and manager. Only users in the manager role are allowed to view salary information.

A role is different from a group 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, the personnel application specify 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.

Roles are defined in the deployment descriptor for the application. The application developer or deployer maps roles to one or more groups in the deployment descriptor for each application. When the application is being packaged and deployed, the application specifies mappings between users, groups, and roles, as illustrated in the following figure.

Figure 11–1 Role Mapping

Figure shows how users are assigned to groups, how users
and groups are assigned to roles, and how applications use groups and roles.

Java Authorization Contract for Containers

Java Authorization Contract for Containers (JACC) is the part of the Java EE specification that defines an interface for pluggable authorization providers. This enables you to set up third-party plug-in modules to perform authorization. By default, the GlassFish Server provides a simple, file-based authorization engine that complies with the JACC specification. You can also specify additional third-party JACC providers.

JACC providers use the Java Authentication and Authorization Service (JAAS) APIs. JAAS enables services to authenticate and enforce access controls upon users. JAAS implements a Java technology version of the standard Pluggable Authentication Module (PAM) framework.

JSR 196 allows you to develop plugins at different layers. You can define plugins that change the way new authentication mechanism are configured, such as, AuthConfigProvider and AuthConfigFactory. You can also define new authentication mechanisms, such as ServerAuthModule and ClientAuthModule.


Auditing is the means used to capture security-related events for the purpose of evaluating the effectiveness of security measures. GlassFish Server uses audit modules to capture audit trails of all authentication and authorization decisions. GlassFish Server provides a default audit module, as well as the ability to customize the audit modules.

For administration instructions, see Administering Audit Modules.


A firewall controls the flow of data between two or more networks, and manages the links between the networks. A firewall can consist of both hardware and software elements. The following guidelines pertain primarily to GlassFish Server:

Certificates and SSL

The following topics are addressed here:

For administration instructions, see Administering JSSE Certificates.


Certificates, also called digital certificates, are electronic files that uniquely identify people and resources on the Internet. Certificates also enable secure, confidential communication between two entities. There are different kinds of certificates:

Certificates are based on public key cryptography, which uses pairs of digital keys (very long numbers) to encrypt, or encode, information so the information can be read only by its intended recipient. The recipient then decrypts (decodes) the information to read it. A key pair contains a public key and a private key. The owner distributes the public key and makes it available to anyone. But the owner never distributes the private key, which is always kept secret. Because the keys are mathematically related, data encrypted with one key can only be decrypted with the other key in the pair.

Certificates are issued by a trusted third party called a Certification Authority (CA). The CA is analogous to a passport office: it validates the certificate holder's identity and signs the certificate so that it cannot be forged or tampered with. After a CA has signed a certificate, the holder can present it as proof of identity and to establish encrypted, confidential communications. Most importantly, a certificate binds the owner's public key to the owner's identity.

In addition to the public key, a certificate typically includes information such as the following:

Certificates are governed by the technical specifications of the X.509 format. To verify the identity of a user in the certificate realm, the authentication service verifies an X.509 certificate, using the common name field of the X.509 certificate as the principal name.

Certificate Chains

A certificate chain is a series of certificates issued by successive CA certificates, eventually ending in a root CA certificate.

Web browsers are preconfigured with a set of root CA certificates that the browser automatically trusts. Any certificates from elsewhere must come with a certificate chain to verify their validity.

When a certificate is first generated, it is a self-signed certificate. A self-signed certificate is one for which the issuer (signer) is the same as the subject (the entity whose public key is being authenticated by the certificate). When the owner sends a certificate signing request (CSR) to a CA, then imports the response, the self-signed certificate is replaced by a chain of certificates. At the bottom of the chain is the certificate (reply) issued by the CA authenticating the subject's public key. The next certificate in the chain is one that authenticates the CA's public key. Usually, this is a self-signed certificate (that is, a certificate from the CA authenticating its own public key) and the last certificate in the chain.

In other cases, the CA can return a chain of certificates. In this situation, the bottom certificate in the chain is the same (a certificate signed by the CA, authenticating the public key of the key entry), but the second certificate in the chain is a certificate signed by a different CA, authenticating the public key of the CA to which you sent the CSR. Then, the next certificate in the chain is a certificate authenticating the second CA's key, and so on, until a self-signed root certificate is reached. Each certificate in the chain (after the first) thus authenticates the public key of the signer of the previous certificate in the chain.

Certificate Files

During GlassFish Server installation, a certificate is generated in Java Secure Socket Extension (JSSE) format suitable for internal testing. By default, GlassFish Server stores its certificate information in certificate databases in the domain-dir/config directory:

Keystore file

The key3.db file contains GlassFish Server certificate, including its private key. The keystore file is protected with a password.

Each keystore entry has a unique alias. After installation, the GlassFish Server keystore has a single entry with an alias of s1as.

Truststore file

The cert8.db file contains the GlassFish Server trusted certificates, including public keys for other entities. For a trusted certificate, the server has confirmed that the public key in the certificate belongs to the certificate's owner. Trusted certificates generally include those of CAs.

By default, GlassFish Server is configured with a keystore and truststore that will work with the example applications and for development purposes.

Secure Sockets Layer

Secure Sockets Layer (SSL) is the most popular standard for securing Internet communications and transactions. Secure web applications use HTTPS (HTTP over SSL). The HTTPS protocol uses certificates to ensure confidential and secure communications between server and clients. In an SSL connection, both the client and the server encrypt data before sending it. Data is decrypted upon receipt.

When a Web browser (client) wants to connect to a secure site, an SSL handshake happens, like this:

  1. The browser sends a message over the network requesting a secure session (typically, by requesting a URL that begins with https instead of http).

  2. The server responds by sending its certificate (including its public key).

  3. The browser verifies that the server's certificate is valid and is signed by a CA whose certificate is in the browser's database (and who is trusted). It also verifies that the CA certificate has not expired.

  4. If the certificate is valid, the browser generates a one time, unique session key and encrypts it with the server's public key. The browser then sends the encrypted session key to the server so that they both have a copy.

  5. The server decrypts the message using its private key and recovers the session key.

After the handshake, the client has verified the identity of the Web site, and only the client and the Web server have a copy of the session key. From this point forward, the client and the server use the session key to encrypt all their communications with each other. Thus, their communications are ensured to be secure.

The newest version of the SSL standard is called Transport Layer Security (TLS). The GlassFish Server supports the SSL 3.0 and the TLS 1.0 encryption protocols.

To use SSL, GlassFish Server must have a certificate for each external interface or IP address that accepts secure connections. The HTTPS service of most web servers will not run unless a certificate has been installed. For instructions on applying SSL to HTTP listeners, see To Configure an HTTP Listener for SSL.


A cipher is a cryptographic algorithm used for encryption or decryption. SSL and TLS protocols support a variety of ciphers used to authenticate the server and client to each other, transmit certificates, and establish session keys.

Some ciphers are stronger and more secure than others. Clients and servers can support different cipher suites. During a secure connection, the client and the server agree to use the strongest cipher that they both have enabled for communication, so it is usually sufficient to enable all ciphers.

Name-based Virtual Hosts

Using name-based virtual hosts for a secure application can be problematic. This is a design limitation of the SSL protocol itself. The SSL handshake, where the client browser accepts the server certificate, must occur before the HTTP request is accessed. As a result, the request information containing the virtual host name cannot be determined prior to authentication, and it is therefore not possible to assign multiple certificates to a single IP address.

If all virtual hosts on a single IP address need to authenticate against the same certificate, the addition of multiple virtual hosts probably will not interfere with normal SSL operations on the server. Be aware, however, that most browsers will compare the server's domain name against the domain name listed in the certificate, if any (applicable primarily to official, CA-signed certificates). If the domain names do not match, these browsers display a warning. In general, only address-based virtual hosts are commonly used with SSL in a production environment.

Tools for Managing System Security

GlassFish Server provides the following tools for managing system security:

Administration Console

The Administration Console is a browser-based utility used to configure security for the entire server. Tasks include managing certificates, users, groups, and realms, and performing other system-wide security tasks. For a general introduction to the Administration Console, see Administration Console.

The asadmin utility

The asadmin command-line utility performs many of the same tasks as the Administration Console. You might be able to do some things with the asadmin utility that you cannot do with the Administration Console. For a general introduction to asadmin, see asadmin Utility.

The keytool utility

The keytool Java Platform, Standard Edition (Java SE) command-line utility is used for managing digital certificates and key pairs. For more information, see Administering JSSE Certificates.

The policytool utility

The policytool J2SE graphical utility is used for managing system-wide Java security policies. As an administrator, you rarely use policytool.

For more information about using keytool, policytool, and other Java security tools, see Summary of Tools for Java Platform Security .