Administering System Security

Within its deployment descriptors, an application can specify the type of authentication that it uses. The Jakarta Security API provides an alternative mechanism for configuring the type of authentication an application uses.

Payara Server supports specifying the following types of authentication in deployment descriptors:

The Jakarta Security API defines the HttpAuthenticationMechanism interface, the IdentityStore and IdentityStoreHandler interfaces.

The HttpAuthenticationMechanism interface defines an SPI for writing authentication mechanisms that can be provided with an application and deployed using CDI. Developers can write their own implementations of HttpAuthenticationMechanism to support specific authentication token types or protocols. There are also several built-in authentication mechanisms that perform BASIC, FORM, and Custom FORM authentication.

The HttpAuthenticationMechanism interface defines three methods - validateRequest(), secureResponse(), and cleanSubject(). These methods align closely with the methods defined by the Jakarta Authentication’s ServerAuth interface.

The IdentityStore interface provides an abstraction of an identity store that holds user account information including name, password, group membership, and other additional attributes. Implementations of the IdentityStore interface are used to validate caller credentials, typically username and password, and retrieve and group information. There are built-in implementations of this interface that can validate credentials against external LDAP or Database identity stores.

IdentityStore is intended primarily for use by HttpAuthenticationMechanism implementations, but could be used by other authentication mechanisms, such as a Jakarta Authentication ServerAuthModule implementation, or a runtime built-in authentication mechanisms. Though HttpAuthenticationMechanism implementations can authenticate users in any manner they choose, the IdentityStore interface provides a convenient mechanism.

A significant advantage of using HttpAuthenticationMechanism and IdentityStore over the declarative mechanisms defined by the Jakarta Servlet specification is that it allows an application to control the identity stores that it authenticates against, in a standard, portable way. You can use the built-in implementations of the plug-in SPIs, or define custom implementations.

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

The master password is not tied to a user account, and it is not used for authentication. Instead, Payara Server strictly uses the master password to ONLY encrypt the keystore and truststore used to store keys and certificates for the DAS and instances usage.

When you create a new Payara Server domain, a new self-signed certificate is generated and stored in the domain keystore and truststore. The DAS needs the master password to open both stores at startup. Similarly, the associated server instances need the master password to open their copy of these stores at startup.

If you use a utility such as keytool to modify the keystore or truststore, you must provide the master password in that case as well.

If you change the master password, you can choose to enter the master password manually when required, or save it in a file.

Payara Server keeps the keystore and truststore for the DAS and instances in sync, which guarantees that all copies of the stores are encrypted with the same master password at any given time.

However, Payara Server does not synchronize the master password itself, and it is possible that the DAS and instances might attempt to use different master passwords.

Consider the following potential scenario:

If you do not use a master password file, you assume the responsibility for using the change-master-password subcommand on the DAS and instances to keep the master passwords in sync.

If you do use a master password file, you assume the responsibility for using the change-master-password subcommand on the DAS and instances to keep the master password file in sync.

Payara Server uses the known text string changeit as the default master password. This master password is not stored in a file. The default password is a convenience feature and provides no additional security because it is assumed to be widely known.

All Payara Server subcommands work as expected with the default master password and there are no synchronization issues.

The change-master-password --savemasterpassword option indicates whether the master password should be written to the file system in the master-password file for the DAS or a node. The default setting is false.

You might want to save the master password to the file so that the start-domain subcommand can start the server without having to prompt the user.

The create-domain --usemasterpassword option specifies whether the keystore and truststore are encrypted with a master password that is built into the system, or by a user-defined master password.

An administration password, also known as the admin password, is used to invoke the Administration Console and the Asadmin CLI utility. As with the default admin username, the default admin password is usually set during installation, but it can be changed.

For instructions, see To Change an Administration Password.

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.

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, 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 website can retrieve the stored credentials for other applications, by exploiting browser vulnerabilities or through application-level cross-domain attacks.

It is heavily recommended to disable password storage when prompted for the password of the Administration Console’s web interface.

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.

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 standard 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, like this:

Jakarta Authorization is the specification that defines an interface for pluggable policy providers. This enables you to set up third-party plug-in modules to perform authorization based on custom policies.

Each Payara Server domain has its own global Java policy file, located in domain-dir/config. The file is named server.policy.

A sample server.policy file is as follows. Comments in the file describe why various permissions are granted. These permissions are described in more detail in the next section.

The Payara Server internal server code is granted all permissions. These grants are covered by the AllPermission grant blocks to various parts of the server infrastructure code. Do not modify these entries.

Application permissions are granted in the default grant block. These permissions apply to all code not part of the internal server code listed previously.

The section beginning with the comment "Basic set of required permissions…​" provides the basic set of permissions granted to all remaining code.

Specifically, the following permission allows all applications to read and write all properties and read and write all files on the file system:

While this grant provides optimum flexibility, it is inherently unsecure. For enhanced security, change this permission based on your real deployment needs.

For example, consider removing this permission and assign default read and write permissions only to the application’s install directory (context-root). This example uses com.sun.aas.instanceRoot, which specifies the top level directory for a server instance:

For any application that needs to read and write additional directories, you would then have to explicitly allow such permissions by adding specific grants. In general, you should add extra permissions only to the applications or modules that require them, not to all applications deployed to a domain.

Certificates, also known as digital certificates, are electronic files that uniquely identify users and resources on the Internet and public networks. Certificates also enable secure, confidential communication between two entities. Usually, there are two different kinds of certificates:

Certificates are based on public key cryptography, which uses pairs of digital keys to encrypt, or encode, information so the information can be read only by its intended recipient. The recipient then decrypts 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, which is embedded on a digital certificate. The private key on the other hand 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 digital 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 (CN) of the X.509 certificate as the principal name.

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

Most modern 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 called 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 entity of the previous certificate in the chain.

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

Secure Sockets Layer (SSL) is a 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:

After the handshake, the client has verified the identity of the website, 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.

To use SSL, Payara 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" in the Payara Server General Administration section.

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.

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 (corresponding to the CN entry) listed in the certificate, if any (applicable primarily to official, CA-signed certificates). If the domain names do not match, most browsers will display a warning and fail the validation. In general, only address-based virtual hosts are commonly used with SSL in a production environment.

Payara Server provides the AppservCertificateLoginModule class to allow developers to implement a custom implementation of a login module that interacts with client certificates. This class provides some convenience methods for accessing the certificates, the application name and so forth, and for adding the group principals to the subject.

The convenience methods include the following:

The following example shows a custom implementation of a certificate login module using the AppservCertificateLoginModule class.

Take note of the following points from the example:

Use the create-password-alias subcommand in remote mode to create an alias for a password in the domain. 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 subcommand to remove and replace the password in the configuration file. For example:

To create a new password alias follow these steps:

Here’s another example that creates the new jms-password alias for the admin user:

Then, you are prompted to type the password for the alias:

Here’s another example that creates a new password alias using the provided name. The user is then prompted to enter the associated password twice.

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

This example lists all existing password aliases:

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

This example deletes the password alias jmspassword-alias:

To modify an existing password alias, select it on the Password Aliases page. On the Edit Password Alias page you are able to change the entered password.

To delete a password alias, go to the Password Aliases page, tick the checkbox of the password alias you wish to delete and then press the Delete button: