Oracle GlassFish Server 3.0.1 Administration Guide

Part II Security Administration

Chapter 11 Administering System Security

The following topics are addressed here:

Instructions for accomplishing many of these tasks by using the Administration Console are contained in the Administration Console online help.

Additional instructions on configuring security is contained in Chapter 12, Administering User Security and Chapter 13, Administering Message Security.

Information on application security is contained in Chapter 5, Securing Applications, in Oracle GlassFish Server 3.0.1 Application Development 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

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:

BASIC: 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.
FORM: 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.
CLIENT-CERT: The server authenticates the client using a public key certificate. The communication protocol is HTTPS (HTTP over SSL). User-credentialed encryption is SSL.
DIGEST: 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

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:

domain-dir/master-password

This file contains the encoded master password and should be protected with file system permissions 600.
Any password file created to pass as an argument by using the --passwordfile argument to the asadmin utility should be protected with file system permissions 600.

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

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.

Roles

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

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.

Firewalls

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:

In general, firewalls should be configured so that clients can access the necessary TCP/IP ports.

For example, if the HTTP listener is operating on port 8080, configure the firewall to allow HTTP requests on port 8080 only. Likewise, if HTTPS requests are set up for port 8081, you must configure the firewalls to allow HTTPS requests on port 8081.
If direct Remote Method Invocations over Internet Inter-ORB Protocol (RMI-IIOP) access from the Internet to EJB modules is required, open the RMI-IIOP listener port as well.

Note –
Opening the RMI-IIOP listener port is strongly discouraged because it creates security risks.
In double firewall architecture, you must configure the outer firewall to allow for HTTP and HTTPS transactions. You must configure the inner firewall to allow the HTTP server plug-in to communicate with GlassFish Server behind the firewall.

Certificates and SSL

The following topics are addressed here:

For administration instructions, see Administering JSSE Certificates.

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:

Personal certificates are used by individuals.
Server certificates are used to establish secure sessions between the server and clients through secure sockets layer (SSL) technology.

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:

The name of the holder and other identification, such as the URL of the web server using the certificate, or an individual's email address
The name of the CA that issued the certificate
An expiration date

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:

The browser sends a message over the network requesting a secure session (typically, by requesting a URL that begins with https instead of http).
The server responds by sending its certificate (including its public key).
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.
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.
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.

Ciphers

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 .

Administering Passwords

There are multiple ways to administer passwords. You can rely on administrators to keep passwords secret and change the passwords regularly. You can set up files for storing passwords so that asadmin subcommands can access these files rather than having users type the commands. You can encrypt passwords by setting up aliases so that sensitive passwords are not visible in the domain.xml file.

The following topics are addressed here:

To Change the Master Password

The master password master gives access to the crypto store used with the domain, be that an NSS cert8.db trust store or a Java JKS keystore. This password is not tied to a UNIX user. This overall shared password is the most sensitive piece of data in your system. The master password is never used for authentication and is never transmitted over the network.

You can choose to type the password manually when required, or to obscure the password in a password file. If there is no password file, you are prompted for the master password. If there is a password file, but you want to change access to require prompting, remove the file. The default master password is changeit.

Use the change-master-password subcommand in local mode to modify the master password.

When the master password is changed, it is re-saved in the master-password keystore, which is a Java JCEKS type keystore.

Before You Begin

This subcommand will not work unless the domain is stopped.

Stop the domain whose password you are changing.

See To Stop a Domain.

Change the master password for the domain by using the change-master-password(1) subcommand.

You are prompted for the old and new passwords. All dependent items are re-encrypted.

Start the domain.

See To Start a Domain.

Example 11–1 Changing the Master Password

The change-master-password subcommand is interactive in that you are prompted for the old master password as well as the new master password. This example changes the master password for domain44ps:

asadmin> change-master-password domain44ps

If you have already logged into the domain using the login login(1) subcommand, you are prompted for the new master password:

Please enter the new master password>
Please enter the new master password again>

If you are not logged into the domain, you are prompted for both the old and the new master passwords:

Please enter the master password again>
Please enter the new master password>
Please enter the new master password again>

Information similar to the following is displayed:

Master password changed for domain44ps

To Change the Administration Password

Use the change-admin-password subcommand in remote mode to change the administration password. The default administration password is admin. You are prompted for the old and new admin passwords, with confirmation.

Note –

If you accepted the default admin user with no password during zip installation, you can add a password to this user. If there is a single user called admin that does not have a password, you are not prompted for login information. Any other situation requires login.

Encrypting the admin password is strongly encouraged.

Before You Begin

If you want to change the admin password before creating an alias for the password (encrypting), you can use the set subcommand with syntax similar to the following:

asadmin set --user admin server.jms-service.jms-host.default_JMS_host.admin-password=
new_pwd

Ensure that the server is running.

Remote subcommands require a running server.

Change the admin password by using the change-admin-password(1) subcommand.

Enter the old and new admin passwords when prompted.

Restart GlassFish Server.

See To Restart a Domain.

Example 11–2 Changing the Admin Password

This example changes the admin password for user anonymous from adminadmin to newadmin:

asadmin> change-admin-password --user anonymous

You are prompted to enter the old and the new admin passwords:

Enter admin password>adminadmin
Enter new admin password>newadmin
Enter new admin password again>newadmin

Information similar to the following is displayed:

Command change-admin-password executed successfully.

To Set a Password From a File

Instead of typing the password at the command line, you can access the password for a command from a file such as passwords.txt. The --passwordfile option of the asadmin utility takes the name of the file that contains the passwords. The entry for a password in the file must have the AS_ADMIN_ prefix followed by the password name in uppercase letters.

The following other types of passwords can be specified:

AS_ADMIN_MASTERPASSWORD
AS_ADMIN_USERPASSWORD
AS_ADMIN_ALIASPASSWORD

Edit the password file.

For example, to specify the password for the domain administration server (DAS), add an entry similar to the following to the password file, where adminadmin is the administrator password:
```
AS_ADMIN_PASSWORD=adminadmin 
```

Save the password file.

You can now specify the password file in an asadmin subcommand. In This example, passwords.txt is the file that contains the password:
asadmin>delete-jdbc-resource --user admin --password passwords.txt jdbc/DerbyPool

Troubleshooting

If AS_ADMIN_PASSWORD has been exported to the global environment, specifying the --passwordfile option will produce a warning about using the --passwordfile option. To prevent this warning situation from happening, unset AS_ADMIN_PASSWORD.

Administering Password Aliases

A password alias is used to indirectly access a password so that the password itself does not appear in cleartext in the domain's domain.xml configuration file.

Storing passwords in cleartext format in system configuration files is common in many open source projects. In addition to GlassFish Server, Apache Tomcat, Maven, and Subversion, among others, store and pass passwords in cleartext format. However, storing and passing passwords in cleartext can be a security risk, and may violate some corporate security policies. In such cases, you can use password aliases.

The following topics are addressed here:

To Create a Password Alias

Use the create-password-alias subcommand in remote mode to create an alias for a password in the domain's keystore. The password corresponding to the alias name is stored in an encrypted form in the domain configuration file. The create-password-alias subcommand takes both a secure interactive form, in which users are prompted for all information, and a more script-friendly form, in which the password is propagated on the command line.

You can also use the set(1) subcommand to remove and replace the password in the configuration file. For example:

asadmin set --user admin server.jms-service.jms-host.default_JMS_host.
admin-password='${ALIAS=jms-password}'

Ensure that the server is running.

Remote subcommands require a running server.

Go to the directory where the configuration file resides.

By default, the configuration file is located in domain-dir/config.

Create the password alias by using the create-password-alias(1) subcommand.

Type the password for the alias when prompted.

Add the alias to a password file.

In the password file, for example, passwords.txt, add the following line: AS_ADMIN_PASSWORD=${ALIAS=admin-password-alias}, where admin-password-alias is the new password alias.

Stop the GlassFish Server domain.

See To Stop a Domain.

Start the domain specifying the file that contains the alias.

Use the following syntax:
start-domain --user admin --passwordfile /path-to/passwords.txt domain1

Example 11–3 Creating a Password Alias

This example creates the new jms-password alias for the admin user:

asadmin> create-password-alias --user admin jms-password

You are prompted to type the password for the alias:

Please enter the alias password>secret-password
Please enter the alias password again>secret-password
Command create-password-alias executed successfully.

To List Password Aliases

Use the list-password-aliases subcommand in remote mode to list existing the password aliases.

Ensure that the server is running.

Remote subcommands require a running server.

List password aliases by using the list-password-aliases(1) subcommand.

Example 11–4 Listing Password Aliases

This example lists the existing password aliases:

asadmin> list-password aliases
jmspassword-alias
Command list-password-aliases executed successfully

To Delete a Password Alias

Use the delete-password-alias subcommand in remote mode to delete an existing password alias.

Ensure that the server is running.

Remote subcommands require a running server.

List all aliases by using the list-password-aliases(1) subcommand.

Delete a password alias by using the list-password-aliases(1) subcommand.

Example 11–5 Deleting a Password Alias

This example deletes the password alias jmspassword-alias:

asadmin> delete-password-alias jmspassword-alias
Command list-password-aliases executed successfully

To Update a Password Alias

Use the update-password-alias subcommand in remote mode to change the password for an existing password alias. The update-password-alias subcommand takes both a secure interactive form, in which the user is prompted for all information, and a more script-friendly form, in which the password is propagated on the command line.

Ensure that the server is running.

Remote subcommands require a running server.

Update an alias by using the update-password-alias(1) subcommand.

Type the password when prompted.

Example 11–6 Updating a Password Alias

This example updates the password for the jmspassword-alias alias:

asadmin> update-password-allias /home/password.txt jsmpassword-alias

You are prompted to type the new password for the alias:

Please enter the alias password>new-secret-password
Please enter the alias password again>new-secret-password
Command update-password-alias executed successfully

Administering Audit Modules

The following topics are addressed here:

To Create an Audit Module

Use the create-audit-module subcommand in remote mode to create an audit module for the add-on component that implements the audit capabilities.

Ensure that the server is running.

Remote subcommands require a running server.

Create an audit module by using the create-audit-module(1) subcommand.

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

Example 11–7 Creating an Audit Module

This example creates an audit module named sampleAuditModule:

asadmin> create-audit-module 
--classname com.sun.appserv.auditmodule --property defaultuser=
admin:Password=admin sampleAuditModule
Command create-audit-module executed successfully.

To List Audit Modules

Use the list-audit-modules subcommand in remote mode to list the audit modules on one of the following targets:

Server instance, server (the default)
Specified server instance
Specified configuration

Ensure that the server is running.

Remote subcommands require a running server.

List the audit modules by using the list-audit-modules(1) subcommand.

Example 11–8 Listing Audit Modules

This example lists the audit modules on localhost:

asadmin> list-audit-modules
audit-module : default
audit-module : sampleAuditModule
Command list-audit-modules executed successfully.

To Delete an Audit Module

Use the delete-audit-module subcommand in remote mode to delete an existing audit module.

Ensure that the server is running.

Remote subcommands require a running server.

List the audit modules by using the list-audit-modules(1) subcommand.

Delete an audit module by using the delete-audit-module(1) subcommand.

Example 11–9 Deleting an Audit Module

This example deletes sampleAuditModule:

asadmin> delete-audit-module sampleAuditModule
Command delete-audit-module executed successfully.

Administering JSSE Certificates

In the developer profile, the GlassFish Server 3.0.1 uses the JSSE format on the server side to manage certificates and key stores. In all profiles, the client side (appclient or stand-alone) uses the JSSE format.

The J2SE SDK ships with the keytool utility, which enables you to set up and work with Java Secure Socket Extension (JSSE) digital certificates. You can administer public/private key pairs and associated certificates, and cache the public keys (in the form of certificates) of their communicating peers.

The following topics are addressed here:

To Generate a Certificate by Using `keytool`

By default, the keytool utility creates a keystore file in the directory where the utility is run.

Before You Begin

To run the keytool utility, your shell environment must be configured so that the J2SE /bin directory is in the path, otherwise the full path to the utility must be present on the command line.

Change to the directory that contains the keystore and truststore files.

Always generate the certificate in the directory containing the keystore and truststore files. The default is domain-dir/config.

Generate the certificate in the keystore file, keystore.jks, using the following command format:
keytool -genkey -alias keyAlias-keyalg RSA -keypass changeit -storepass changeit keystore keystore.jks
Use any unique name as your keyAlias. If you have changed the keystore or private key password from the default (changeit), substitute the new password for changeit. The default key password alias is s1as.

A prompt appears that asks for your name, organization, and other information.

Export the generated certificate to the server.cer file (or client.cer if you prefer), using the following command format:
keytool -export -alias keyAlias-storepass changeit -file server.cer -keystore keystore.jks

If a certificate signed by a certificate authority is required, see To Sign a Certificate by Using keytool.

Create the cacerts.jks truststore file and add the certificate to the truststore, using the following command format:
keytool -import -v -trustcacerts -alias keyAlias -file server.cer -keystore cacerts.jks -keypass changeit
If you have changed the keystore or private key password from the default (changeit), substitute the new password.

Information about the certificate is displayed and a prompt appears asking if you want to trust the certificate.

Type yes, then press Enter.

Information similar to the following is displayed:
Certificate was added to keystore [Saving cacerts.jks]

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

Example 11–10 Creating a Self-Signed Certificate in a JKS Keystore by Using an RSA Key Algorithm

RSA is public-key encryption technology developed by RSA Data Security, Inc.

keytool  -genkey -noprompt -trustcacerts -keyalg RSA -alias ${cert.alias} 
-dname  ${dn.name} -keypass ${key.pass} -keystore ${keystore.file} 
-storepass ${keystore.pass}

Example 11–11 Creating a Self-Signed Certificate in a JKS Keystore by Using a Default Key Algorithm

keytool -genkey -noprompt -trustcacerts -alias ${cert.alias} -dname  
${dn.name} -keypass ${key.pass} -keystore ${keystore.file} -storepass 
${keystore.pass}

Example 11–12 Displaying Available Certificates From a JKS Keystore

keytool -list -v  -keystore ${keystore.file} -storepass ${keystore.pass}

Example 11–13 Displaying Certificate information From a JKS Keystore

keytool -list -v  -alias ${cert.alias} -keystore ${keystore.file} 
-storepass ${keystore.pass}

To Sign a Certificate by Using `keytool`

After creating a certificate, the owner must sign the certificate to prevent forgery. E-commerce sites, or those for which authentication of identity is important, can purchase a certificate from a well-known Certificate Authority (CA).

Note –

If authentication is not a concern, for example if private secure communications are all that is required, you can save the time and expense involved in obtaining a CA certificate by using a self-signed certificate.

Follow the instructions on the CA's web site for generating certificate key pairs.

Download the generated certificate key pair.

Save the certificate in the directory containing the keystore and truststore files. The default is domain-dir/config.

In your shell, change to the directory containing the certificate.

Import the certificate into the local keystore and, if necessary, the local truststore using the following command format:
keytool -import -v -trustcacerts -alias keyAlias -file server.cer -keystore cacerts.jks -keypass changeit -storepass changeit
If the keystore or private key password is not the default password, then substitute the new password for the default (changeit).

To apply your changes, restart GlassFish Server.

See To Restart a Domain.

Example 11–14 Importing an RFC/Text-Formatted Certificate Into a JKS Keystore

Certificates are often stored using the printable encoding format defined by the Internet Request for Comments (RFC) 1421 standard instead of their binary encoding. This certificate format, also known as Base 64 encoding, facilitates exporting certificates to other applications by email or through some other mechanism.

keytool -import -noprompt -trustcacerts -alias ${cert.alias} -file 
${cert.file} -keystore ${keystore.file} -storepass ${keystore.pass}

Example 11–15 Exporting a Certificate From a JKS Keystore in PKCS7 Format

The reply format defined by the Public Key Cryptography Standards #7, Cryptographic Message Syntax Standard, includes the supporting certificate chain in addition to the issued certificate.

keytool -export -noprompt -alias ${cert.alias} -file ${cert.file} 
-keystore ${keystore.file} -storepass ${keystore.pass}

Example 11–16 Exporting a Certificate From a JKS Keystore in RFC/Text Format

keytool -export -noprompt -rfc -alias ${cert.alias} -file 
${cert.file} -keystore ${keystore.file} -storepass ${keystore.pass}

To Delete a Certificate by Using `keytool`

Use the keytool -delete command to delete an existing certificate.

Delete a certificate using the following command format:

keytool -delete
 -alias keyAlias
 -keystore keystore-name
 -storepass password

Example 11–17 Deleting a Certificate From a JKS Keystore

keytool -delete -noprompt -alias ${cert.alias}  -keystore ${keystore.file} 
-storepass ${keystore.pass}

Chapter 12 Administering User Security

This chapter provides instructions for administering user security in the Oracle GlassFish Server environment by using the asadmin command-line utility. GlassFish Server enforces its authentication and authorization policies upon realms, users, and groups. This chapter assumes that you are familiar with security features such as authentication, authorization, and certificates. If you are not, see Chapter 11, Administering System Security.

The following topics are addressed here:

Instructions for accomplishing these tasks by using the Administration Console are contained in the Administration Console online help.

Administering Authentication Realms

The following topics are addressed here:

Overview of Authentication Realms

An authentication realm, also called a security policy domain or security domain, is a scope over which the GlassFish Server defines and enforces a common security policy. GlassFish Server is preconfigured with the file, certificate, and administration realms. In addition, you can set up LDAP, JDBC, digest, Oracle Solaris, or custom realms. An application can specify which realm to use in its deployment descriptor. If the application does not specify a realm, GlassFish Server uses its default realm (file).

File realm

GlassFish 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

GlassFish 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

GlassFish Server can get user credentials from a Lightweight Directory Access Protocol (LDAP) server such as Oracle Virtual Directory (OVD), Oracle Internet Directory (OID), and Oracle Directory Server Enterprise Edition. 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.

See To Configure LDAP Authentication with OID and OVD for instructions on configuring GlassFish Server to work with an OVD/OID LDAP provider.

JDBC realm

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

Oracle Solaris realm

GlassFish Server gets user credentials from the Oracle Solaris operating system. This realm is supported on the Oracle Solaris 9 and Oracle Solaris 10 operating systems. Consult your Oracle Solaris documentation for information about managing users and groups in the Oracle 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 Oracle GlassFish Server 3.0.1 Application Development Guide.

The GlassFish Server authentication service can govern users in multiple realms.

To Create an Authentication Realm

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

Ensure that the server is running.

Remote subcommands require a running server.

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

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

Example 12–1 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.

To List Authentication Realms

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

Ensure that the server is running.

Remote subcommands require a running server.

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

Example 12–2 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.

To Update an Authentication Realm

Use the set subcommand to modify an existing authentication realm.

Note –

A custom realm does not require server restart.

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

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

The thread pool is identified by its dotted name.

To apply your changes, restart GlassFish 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.

Ensure that the server is running.

Remote subcommands require a running server.

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

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

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

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

Example 12–3 Deleting a Realm

This example deletes an authentication realm named db.

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

To Configure a JDBC or Digest Authentication Realm

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

Note –

By default, storage of passwords as clear text is not supported in the JDBC realm. Under normal circumstances, passwords should not be stored as clear text.

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.

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.

Create a JDBC connection pool for the database.

See To Create a JDBC Connection Pool.

Create a JDBC resource for the database.

To Create a JDBC Resource

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.

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 Oracle GlassFish Server 3.0.1 Application Development Guide.

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.

Verify that the database is running.

If needed, see To Start the Database

To apply the authentication, restart the server.

See To Restart a Domain.

Example 12–4 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>

To Configure LDAP Authentication with OID and OVD

This procedure explains how to configure GlassFish Server to use LDAP authentication with Oracle Virtual Directory (OVD) or Oracle Internet Directory (OID).

Install Oracle Enterprise Manager 11g and the latest Enterprise Manager patches, if they are not installed already.

Instructions for installing Oracle Enterprise Manager are provided in the Oracle Enterprise Manager documentation set.

Install the Oracle Identity Management Suite (IDM) 11g and Patch Set 2 or later, if they are not installed already.

Instructions for installing the Oracle Identity Management suite are provided in the Oracle Fusion Middleware Installation Guide for Oracle Identity Management.

Configure SSL for Oracle Internet Directory (OID), if it is not configured already.

Instructions for configuring SSL for OID are provided in the SSL chapter of the Oracle Internet Directory Administrator's Guide.

Using Oracle Wallet Manager, export an SSL self-signed certificate you want to use with GlassFish Server.

Instructions for using Oracle Wallet Manager to create and export SSL certificates are provided in the Configure Oracle Internet Directory for SSL section of the SSL chapter in the Oracle Internet Directory Administrator's Guide.

On the GlassFish Server side, use the keytool command import the certificate you exported with Oracle Wallet Manager.

The keytool command is available in the $JAVA_HOME/bin directory. Use the following syntax:
keytool -importcert -alias "alias-name" -keystore domain-dir/config/cacerts.jks -file cert-name
alias-name

Name of an alias to use for the certificate

domain-dir

Name of the domain for which the certificate is used

cert-name

Name of the certificate that you exported with Oracle Wallet Manager.

For example, to import a certificate named ovd.cer for a GlassFish Server domain in /glassfishv3/glassfish/domains/domain1, using an alias called “OVD self-signed certificate,” you would use the following command:
keytool -importcert -alias "OVD self signed certificate" -keystore \ /glassfishv3/glassfish/domains/domain1/config/cacerts.jks -file ovd.cer

Restart the GlassFish Server domain.

See To Restart a Domain.

Use the Oracle Enterprise Manager ldapmodify command to enable Anonymous Bind for OID/OVD.

For example:
ldapmodify -D cn=orcladmin -q -p portNum -h hostname -f ldifFile
In this example, the LDIF file might contain the following:
dn: cn=oid1,cn=osdldapd,cn=subconfigsubentry changetype: modify replace: orclAnonymousBindsFlag orclAnonymousBindsFlag: 1
To disable all anonymous binds, you would use a similar LDIF file with the last line changed to:
orclAnonymousBindsFlag: 0
See Managing Anonymous Binds in the Oracle Fusion Middleware Administrator's Guide for Oracle Internet Directory for complete instructions on the ldapmodify command.

To Enable LDAP Authentication on the GlassFish Server DAS

This procedure explains how to enable LDAP authentication for logins to the GlassFish Server Domain Administration Server (DAS). Logging in to the DAS is typically only performed by GlassFish Server administrators who want to use the GlassFish Server Administration Console or asadmin command. See To Configure LDAP Authentication with OID and OVD for instructions on enabling general LDAP authentication for GlassFish Server.

Before You Begin

Ensure that you have followed the configuration instructions in To Configure LDAP Authentication with OID and OVD

Use the asadmin configure-ldap-for-admin subcommand to enable user authentication to the GlassFish Server DAS.

Use the following syntax:

asadmin configure-ldap-for-admin --basedn "dn-list" --url [ldap|ldaps]://ldap-url --ldap-group group-name

dn-list: basedn parameters
ldap-url: URL and port number for the LDAP server; can use standard (ldap) or secure (ldaps) protocol
group-name: LDAP group name for allowed users, as defined on the LDAP server.

For example:

asadmin configure-ldap-for-admin --basedn "dc=red,dc=iplanet,dc=com" \
--url ldap://interopoel54-1:3060 --ldap-group sqestaticgroup

asadmin configure-ldap-for-admin --basedn "dc=red,dc=iplanet,dc=com" \
--url ldaps://interopoel54-1:7501 --ldap-group sqestaticgroup

Administering File Users

A user is an individual (or application program) identity that is defined in GlassFish Server. A user who has been authenticated is sometimes called a principal.

As the administrator, you are responsible for integrating users into the GlassFish Server environment so that their credentials are securely established and they are provided with access to the applications and services that they are entitled to use.

The following topics are addressed here:

To Create a File User

Use the create-file-user subcommand in remote mode to create a new user by adding a new entry to the keyfile. The entry includes the user name, password, and any groups for the user. Multiple groups can be specified by separating the groups with colons (:).

Creating a new file realm user is a dynamic event and does not require server restart.

Ensure that the server is running.

Remote subcommands require a running server.

If the user will belong to a particular group, see the current groups by using the list-file-groups(1) subcommand.

Create a file user by using the create-file-user(1) subcommand.

Example 12–5 Creating a User

This example create user Jennifer on the default realm file (no groups are specified).

asadmin> create-file-user --user admin 
--passwordfile=c:\tmp\asadminpassword.txt Jennifer
Command create-file-user executed successfully.

To List File Users

Use the list-file-users subcommand in remote mode to list the users that are in the keyfile.

Ensure that the server is running.

Remote subcommands require a running server.

List users by using the list-file-users(1) subcommand.

Example 12–6 Listing File Users

This example lists file users on the default file realm file.

asadmin> list-file-users
Jennifer
Command list-file-users executed successfully.

To List File Groups

A group is a category of users classified by common traits, such as job title or customer profile. For example, users of an e-commerce application might belong to the customer group, and the big spenders might also belong to the preferred group. Categorizing users into groups makes it easier to control the access of large numbers of users. A group is defined for an entire server and realm. A user can be associated with multiple groups of users.

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

Use the list-file-groups subcommand in remote mode to list groups for a file user, or all file groups if the --name option is not specified.

Ensure that the server is running.

Remote subcommands require a running server.

List file groups by using the list-file-groups(1) subcommand.

Example 12–7 Listing Groups for a User

This example lists the groups for user joesmith.

asadmin> list-file-groups --name joesmith
staff
manager
Command list-file-groups executed successfully

To Update a File User

Use the update-file-user subcommand in remote mode to modify the information in the keyfile for a specified user.

Ensure that the server is running.

Remote subcommands require a running server.

Update the user information by using the update-file-user(1) subcommand.

To apply your changes, restart GlassFish Server.

See To Restart a Domain.

Example 12–8 Updating a User

The following subcommand updates the groups for user Jennifer.

asadmin> update-file-user --passwordfile c:\tmp\asadminpassword.txt --groups 
staff:manager:engineer Jennifer
Command update-file-user executed successfully.

To Delete a File User

Use the delete-file-user subcommand in remote mode to remove a user entry from the keyfile by specifying the user name. You cannot delete yourself, that is, the user you are logged in as cannot be deleted during your session.

Ensure that the server is running.

Remote subcommands require a running server.

List users by using the list-file-users(1) subcommand.

Delete the user by using the delete-file-user(1) subcommand.

Example 12–9 Deleting a User

This example deletes user Jennifer from the default file realm.

asadmin> delete-file-user Jennifer
Command delete-file-user executed successfully.

Chapter 13 Administering Message Security

This chapter provides information and procedures on configuring the message layer security for web services in the GlassFish Server environment.

Note –

Message security (JSR 196) is supported only in the Full Platform Profile of GlassFish Server, not in the Web Profile.

The following topics are addressed here:

Some of the material in this chapter assumes a basic understanding of security and web services concepts. For more information about security, see About System Security in GlassFish Server.

Instructions for accomplishing the tasks in this chapter by using the Administration Console are contained in the Administration Console online help.

About Message Security in GlassFish Server

Message security enables a server to perform end-to-end authentication of web service invocations and responses at the message layer. Security information is inserted into messages so that it travels through the networking layers and arrives with the intact message at the message destination(s). Message security differs from transport layer security in that message security can be used to decouple message protection from message transport so that messages remain protected after transmission.

Web services deployed on GlassFish Server are secured by binding SOAP layer message security providers and message protection policies to the containers in which the applications are deployed, or to web service endpoints served by the applications. SOAP layer message security functionality is configured in the client-side containers of GlassFish Server by binding SOAP layer message security providers and message protection policies to the client containers or to the portable service references declared by client applications.

Message-level security can be configured for the entire GlassFish Server or for specific applications or methods. Configuring message security at the application level is discussed in the Oracle GlassFish Server 3.0.1 Application Development Guide.

The following topics are addressed here:

Security Tokens and Security Mechanisms

WS-Security is a specification that provides a communications protocol for applying security to web services. The security mechanisms implement the specification. Web Services Interoperability Technologies (WSIT) implements WS-Security so as to provide interoperable message content integrity and confidentiality, even when messages pass through intermediary nodes before reaching their destination endpoint. WS-Security as provided by WSIT is in addition to existing transport-level security, which can still be used.

The Simple Object Access Protocol (SOAP) layer message security providers installed with GlassFish Server can be used to employ username/password and X.509 certificate security tokens to authenticate and encrypt SOAP web services messages.

Username Tokens. GlassFish Server uses username tokens in SOAP messages to authenticate the message sender. The recipient of a message containing a username token (within embedded password) validates that the message sender is authorized to act as the user (identified in the token) by confirming that the sender knows the password of the user.

When using a username token, a valid user database must be configured on GlassFish Server.
Digital Signatures. GlassFish Server uses XML digital signatures to bind an authentication identity to message content. Clients use digital signatures to establish their caller identity. Digital signatures are verified by the message receiver to authenticate the source of the message content (which might be different from the sender of the message.)

When using digital signatures, valid keystore and truststore files must be configured on GlassFish Server.
Encryption. The purpose of encryption is to modify the data so that it can only be understood by its intended audience. This is accomplished by substituting an encrypted element for the original content. When based on public key cryptography, encryption can be used to establish the identity of the parties who are authorized to read a message.

When using encryption, a Java Cryptography Extension (JCE) provider that supports encryption must be installed.

Authentication Providers

The authentication layer is the message layer on which authentication processing must be performed. GlassFish Server enforces web services message security at the SOAP layer. The types of authentication that are supported include the following:

Sender authentication, including username-password authentication
Content authentication, including XML digital signatures

GlassFish Server invokes authentication providers to process SOAP message layer security. The message security providers provide information such as the type of authentication that is required for the request and response messages. The following message security providers are included with GlassFish Server:

Client-side Provider. A client-side provider establishes (by signature or username/password) the source identity of request messages and/or protects (by encryption) request messages such that they can only be viewed by their intended recipients. A client-side provider also establishes its container as an authorized recipient of a received response (by successfully decrypting it) and validates passwords or signatures in the response to authenticate the source identity associated with the response. Client-side providers configured in GlassFish Server can be used to protect the request messages sent and the response messages received by server-side components (servlets and EJB components) acting as clients of other services.

The default client provider is used to identify the client—side provider to be invoked for any application for which a specific client provider has not been bound.
Server-side Provider. A server-side provider establishes its container as an authorized recipient of a received request (by successfully decrypting it), and validates passwords or signatures in the request to authenticate the source identity associated with the request. A server-side provider also establishes (by signature or username/password) the source identity of response messages and/or protects (by encryption) response messages such that they can only be viewed by their intended recipients. Server-side providers are only invoked by server-side containers.

The default server provider is used to identify the server—side provider to be invoked for any application for which a specific server provider has not been bound.

Message Protection Policies

A request policy defines the authentication policy requirements associated with request processing performed by the authentication provider. Policies are expressed in message sender order such that a requirement that encryption occur after content would mean that the message receiver would expect to decrypt the message before validating the signature. The response policy defines the authentication policy requirements associated with response processing performed by the authentication provider.

Message protection policies are defined for request message processing and response message processing. The policies are expressed in terms of requirements for source and/or recipient authentication. The providers apply specific message security mechanisms to cause the message protection policies to be realized in the context of SOAP web services messages.

Source Authentication Policy. A source authentication policy represents a requirement that the identity of the entity that sent a message or that defined the content of a message be established in the message such that it can be authenticated by the message receiver.
Recipient Authentication Policy. A recipient authentication policy represents a requirement that the message be sent such that the identity of the entities that can receive the message can be established by the message sender.

Request and response message protection policies are defined when a security provider is configured into a container. Application-specific message protection policies (at the granularity of the web service port or operation) can also be configured within the GlassFish Server deployment descriptors of the application or application client. In any situation where message protection policies are defined, the request and response message protection policies of the client must be equivalent t) the request and response message protection policies of the server. For more information about defining application-specific message protection policies, see Chapter 5, Securing Applications, in Oracle GlassFish Server 3.0.1 Application Development Guide

Application-Specific Web Services Security

Application-specific web services security functionality is configured (at application assembly) by defining the message-security-binding elements in the GlassFish Server deployment descriptors of the application. These message-security-binding elements are used to associate a specific security provider or message protection policy with a web service endpoint or service reference, and might be qualified so that they apply to a specific port or method of the corresponding endpoint or referenced service.

For information about defining application-specific message protection policies, see Chapter 5, Securing Applications, in Oracle GlassFish Server 3.0.1 Application Development Guide.

Message Security Administration

When GlassFish Server is installed, SOAP layer message security providers are configured in the client and server-side containers of GlassFish Server, where they are available for binding for use by the containers, or by individual applications or clients deployed in the containers. During installation, the default providers are configured with a simple message protection policy that, if bound to a container, or to an application or client in a container, would cause the source of the content in all request and response messages to be authenticated by XML digital signature.

GlassFish Server administrative interfaces can be used as follows:

To modify the message protection policies enforced by the providers
To bind the existing providers for use by the server-side containers of GlassFish Server
To create new security provider configurations with alternative message protection policies

Analogous administrative operations can be performed on the SOAP message layer security configuration of the application client container. If you want web services security to protect all web services applications deployed on GlassFish Server. See Enabling Message Security for Application Clients.

By default, message layer security is disabled on GlassFish Server. To configure message layer security for the GlassFish Server see Enabling Default Message Security Providers for Web Services.

In most cases, you must restart GlassFish Server after performing administrative tasks. This is especially true if you want the effects of the administrative change to be applied to applications that were already deployed on GlassFish Server at the time the operation was performed.

Message Security Tasks

The general implementation tasks for message security include some or all of the following:

If you are using a version of the Java SDK prior to version 1.5.0, and using encryption technology, configuring a JCE provider
If you are using a username token, verifying that a user database is configured for an appropriate realm

When using a username/password token, an appropriate realm must be configured and a user database must be configured for the realm.
Managing certificates and private keys, if necessary
Enabling the GlassFish Server default providers
Configuring new message security providers

Message Security Roles

In GlassFish Server, the administrator and the application deployer are expected to take primary responsibility for configuring message security. In some situations, the application developer might also contribute.

System Administrator

The system administrator is responsible for the following message security tasks:

Administering server security settings and certificate databases
Administering keystore and truststore files
Configuring message security providers on GlassFish Server
Turning on message security
(If needed) Installing the samples server

Application Deployer

The application deployer is responsible for the following message security tasks:

Specifying (at application reassembly) any required application-specific message protection policies if such policies have not already been specified by the developer/assembler.
Modifying GlassFish Server deployment descriptors to specify application-specific message protection policies information (message-security-binding elements) to web service endpoint and service references.

Application Developer/Assembler

The application developer/assembler is responsible for the following message security tasks:

Determining if an application-specific message protection policy is required by the application

If so, the developer ensures that the required policy is specified at application assembly time.
Specifying how web services should be set up for message security

Message security can be set up by the administrator so that all web services are secured, or by the application deployer when the security provider or protection policy bound to the application must be different from that bound to the container.
Turning on message security if authorized to do so by the administrator

Sample Application for Web Services

GlassFish Server includes a sample application named xms. The xms application features a simple web service that is implemented by both a Java EE EJB endpoint and a Java servlet endpoint. Both endpoints share the same service endpoint interface. The service endpoint interface defines a single operation, sayHello, which takes a string argument, and returns a String composed by pre-pending Hello to the invocation argument.

The xms sample application is provided to demonstrate the use of GlassFish Server WS-Security functionality to secure an existing web services application. The instructions which accompany the sample describe how to enable the WS-Security functionality of GlassFish Server such that it is used to secure the xms application. The sample also demonstrates the binding of WS-Security functionality directly to the application as described in Application-Specific Web Services Security application.

For information about compiling, packaging, and running the xms sample application, Chapter 5, Securing Applications, in Oracle GlassFish Server 3.0.1 Application Development Guide.

The xms sample application is installed in the following directory: as-install/samples/webservices/security/ejb/apps/xms/

Enabling Default Message Security Providers for Web Services

By default, message security is disabled on GlassFish Server. Default message security providers have been created, but are not active until you enable them. After the providers have been enabled, message security is enabled.

The following topics are addressed here:

To Enable a Default Server Provider

To enable message security for web services endpoints deployed in GlassFish Server, you must specify a security provider to be used by default on the server side. If you enable a default provider for message security, you also need to enable providers to be used by clients of the web services deployed in GlassFish Server.

Specify the default server provider by using the set(1) subcommand.

Use the following syntax:

asadmin  set --port admin-port 
server-config.security-service.message-security-config.SOAP.
default_provider=ServerProvider

To apply your changes to applications that are already running, restart GlassFish Server.

See To Restart a Domain.

To Enable a Default Client Provider

To enable message security for web service invocations originating from deployed endpoints, you must specify a default client provider. If you enabled a default client provider for GlassFish Server, you must ensure that any services invoked from endpoints deployed in GlassFish Server are compatibly configured for message layer security.

Specify the default client provider by using the set(1) subcommand.

Use the following syntax:

asadmin  set --port admin-port 
server-config.security-service.message-security-config.SOAP.
default_client_provider=ClientProvider

To apply your changes to applications that are already running, restart GlassFish Server.

See To Restart a Domain.

Configuring Message Protection Policies

The following topics are addressed here:

Message Protection Policy Mapping

The following table shows message protection policy configurations and the resulting message security operations performed by the WS-Security SOAP message security providers for that configuration.

Table 13–1 Message Protection Policy Mapping to WS-Security SOAP Operations


Message Protection Policy	Resulting WS-Security SOAP message protection operations
`auth-source="sender"`	The message contains a `wsse:Security` header that contains a `wsse:UsernameToken` (with password).
`auth-source="content"`	The content of the SOAP message Body is signed. The message contains a `wsse:Security` header that contains the message Body signature represented as a `ds`:`Signature`.
`auth-source="sender"` `auth-recipient="before-content"` OR `auth-recipient="after-content"`	The content of the SOAP message Body is encrypted and replaced with the resulting `xend:EncryptedData`. The message contains `a wsse:Security` header that contains a `wsse:UsernameToken (with password)` and an `xenc:EncryptedKey`. The `xenc:EncryptedKey` contains the key used to encrypt the SOAP message body. The key is encrypted in the public key of the recipient.
`auth-source="content"` `auth-recipient="before-content"`	The content of the SOAP message Body is encrypted and replaced with the resulting `xend:EncryptedData`. The `xenc:EncryptedData` is signed. The message contains `a wsse:Security` header that contains an `xenc:EncryptedKey` and a `ds`:`Signature`. The `xenc:EncryptedKey` contains the key used to encrypt the SOAP message body. The key is encrypted in the public key of the recipient.
`auth-source="content"` `auth-recipient="after-content"`	The content of the SOAP message Body is signed, then encrypted, and then replaced with the resulting `xend:EncryptedData`. The message contains a `wsse:Security` header that contains an `xenc:EncryptedKey` and a `ds:Signature`. The `xenc:EncryptedKey` contains the key used to encrypt the SOAP message body. The key is encrypted in the public key of the recipient.
`auth-recipient="before-content"` OR `auth-recipient="after-content"`	The content of the SOAP message Body is encrypted and replaced with the resulting `xend:EncryptedData`. The message contains `a wsse:Security` header that contains an `xenc:EncryptedKey`. The `xenc:EncryptedKey` contains the key used to encrypt the SOAP message body. The key is encrypted in the public key of the recipient.
No policy specified.	No security operations are performed by the modules.

To Configure the Message Protection Policies for a Provider

Typically, you would not reconfigure a provider. However, if needed for your situation, you can modify a provider's message protection policies by changing provider type, implementation class, and provider-specific configuration properties. To understand the results of different combinations, see Table 13–1.

Use the set(1) subcommand to set the response policy, then replace the word request in the following commands with the word response.

Add a request policy to the client and set the authentication source by using the set(1) subcommand.

For example:

asadmin> set server-config.security-service.message-security-config.SOAP.
provider-config.ClientProvider.request-policy.auth_source=[sender | content]

Add a request policy to the server and set the authentication source by using the set subcommand.

For example:

asadmin> set server-config.security-service.message-security-config.SOAP.
provider-config.ServerProvider.request-policy.auth_source=[sender | content]

Add a request policy to the client and set the authentication recipient by using the set subcommand:

For example:

asadmin> set server-config.security-service.message-security-config.SOAP.
provider-config.ClientProvider.request-policy.auth_recipient=[before-content | after-content]

Add a request policy to the server and set the authentication recipient by using the set subcommand:

For example:

asadmin> set server-config.security-service.message-security-config.SOAP.
provider-config.ServerProvider.request-policy.auth_recipient=[before-content | after-content]

Setting the Request and Response Policy for the Application Client Configuration

The request and response policies define the authentication policy requirements associated with request and response processing performed by the authentication provider. Policies are expressed in message sender order such that a requirement that encryption occur after content would mean that the message receiver would expect to decrypt the message before validating the signature.

To achieve message security, the request and response policies must be enabled on both the server and client. When configuring the policies on the client and server, make sure that the client policy matches the server policy for request/response protection at application-level message binding.

To set the request policy for the application client configuration, modify the GlassFish Server–specific configuration for the application client container as described in Enabling Message Security for Application Clients.

Example 13–1 Message Security Policy Setting for Application Clients

In the application client configuration file, the request-policy and response-policy elements are used to set the request policy, as shown in the following code snippet. (Additional code in the snippet is provided as illustration and might differ slightly in your installation. Do not change the additional code.)

<client-container>
  <target-server name="your-host" address="your-host"
      port="your-port"/>
  <log-service file="" level="WARNING"/>
  <message-security-config auth-layer="SOAP"
      default-client-provider="ClientProvider">
    <provider-config
        class-name="com.sun.enterprise.security.jauth.ClientAuthModule"
        provider-id="ClientProvider" provider-type="client">
      <request-policy auth-source="sender | content"
        auth-recipient="after-content | before-content"/>
      <response-policy auth-source="sender | content"
        auth-recipient="after-content | before-content"/>
       <property name="security.config"
           value="as-install/lib/appclient/wss-client-config.xml"/>
    </provider-config>
  </message-security-config>
</client-container>

Valid values for auth-source include sender and content. Valid values for auth-recipient include before-content and after-content. A table describing the results of various combinations of these values can be found in Configuring Message Protection Policies.

To not specify a request or response policy, leave the element blank, for example:

<response-policy/>

Administering Non-default Message Security Providers

The following topics are addressed here:

To Create a Message Security Provider

Use the create–message–security–provider subcommand in remote mode to create a new message provider for the security service. If the message layer does not exist, the message layer is created, and the provider is created under it.

Ensure that the server is running.

Remote subcommands require a running server.

Create the message security provider by using the create-message-security-provider(1) subcommand.

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

(Optional) If needed, restart the server.

Some properties require server restart. See Configuration Changes That Require Server Restart. If your server needs to be restarted, see To Restart a Domain.

Example 13–2 Creating a Message Security Provider

This example creates the new message security provider mySecurityProvider.

asadmin> create-message-security-provider 
--classname com.sun.enterprise.security.jauth.ClientAuthModule
--providertype client mySecurityProvider
Command create-message-security-provider executed successfully.

To List Message Security Providers

Use the list–message–security–providers subcommand in remote mode to list the message providers for the security layer.

Ensure that the server is running.

Remote subcommands require a running server.

List the message security providers by using the list-message-security-providers(1) subcommand.

Example 13–3 Listing Message Security Providers

This example lists the message security providers for a message layer.

asadmin> list-message-security-providers --layer SOAP
XWS_ClientProvider 
ClientProvider
XWS_ServerProvider
ServerProvider
Command list-message-security-providers executed successfully.

To Update a Message Security Provider

Ensure that the server is running.

Remote subcommands require a running server.

List the message security providers by using the list-message-security-providers(1) subcommand.

Modify the values for the specified message security provider by using the set(1) subcommand.

The message security provider is identified by its dotted name.

To Delete a Message Security Provider

Use the delete-message-security-provider subcommand in remote mode to remove a message security provider.

Ensure that the server is running.

Remote subcommands require a running server.

List the message security providers by using the list-message-security-providers(1) subcommand.

Delete the message security provider by using the delete-message-security-provider(1) subcommand.

Example 13–4 Deleting a Message Security Provider

This example deletes the myServerityProvider message security provider.

asadmin> delete-message-security-provider --layer SOAP myServerityProvider
Command delete-message-security-provider executed successfully.

Enabling Message Security for Application Clients

The message protection policies of client providers must be configured such that they are equivalent to the message protection policies of the server-side providers they will be interacting with. This is already the situation for the providers configured (but not enabled) when GlassFish Server is installed.

To enable message security for client applications, modify the GlassFish Server specific configuration for the application client container. The process is analogous to the process in Configuring Message Protection Policies.

Additional Information About Message Security

For additional information about message security, see the following documentation:

Part II Security Administration

Chapter 11 Administering System Security

About System Security in GlassFish Server

Authentication

Authentication Types

Passwords

Master Password and Keystores

Administration Password

Encoded Passwords

Web Browsers and Password Storage

Password Aliases

Single Sign-on

Authorization

Roles

Figure 11–1 Role Mapping

Java Authorization Contract for Containers

Auditing

Firewalls

Certificates and SSL

Certificates

Certificate Chains

Certificate Files

Secure Sockets Layer

Ciphers

Name-based Virtual Hosts

Tools for Managing System Security

Administering Passwords

To Change the Master Password

Before You Begin

Example 11–1 Changing the Master Password

See Also

To Change the Administration Password

Before You Begin

Example 11–2 Changing the Admin Password

See Also

To Set a Password From a File

Troubleshooting

Administering Password Aliases

To Create a Password Alias

Example 11–3 Creating a Password Alias

See Also

To List Password Aliases

Example 11–4 Listing Password Aliases

See Also

To Delete a Password Alias

Example 11–5 Deleting a Password Alias

See Also

To Update a Password Alias

Example 11–6 Updating a Password Alias

See Also

Administering Audit Modules

To Create an Audit Module

Example 11–7 Creating an Audit Module

See Also

To List Audit Modules

Example 11–8 Listing Audit Modules

See Also

To Delete an Audit Module

Example 11–9 Deleting an Audit Module

Administering JSSE Certificates

To Generate a Certificate by Using keytool

Before You Begin

Example 11–10 Creating a Self-Signed Certificate in a JKS Keystore by Using an RSA Key Algorithm

Example 11–11 Creating a Self-Signed Certificate in a JKS Keystore by Using a Default Key Algorithm

Example 11–12 Displaying Available Certificates From a JKS Keystore

Example 11–13 Displaying Certificate information From a JKS Keystore

See Also

To Sign a Certificate by Using keytool

Example 11–14 Importing an RFC/Text-Formatted Certificate Into a JKS Keystore

Example 11–15 Exporting a Certificate From a JKS Keystore in PKCS7 Format

Example 11–16 Exporting a Certificate From a JKS Keystore in RFC/Text Format

See Also

To Delete a Certificate by Using keytool

Example 11–17 Deleting a Certificate From a JKS Keystore

See Also

Chapter 12 Administering User Security

Administering Authentication Realms

Overview of Authentication Realms

To Create an Authentication Realm

Example 12–1 Creating a Realm

To Generate a Certificate by Using `keytool`

To Sign a Certificate by Using `keytool`

To Delete a Certificate by Using `keytool`