+

Search Tips   |   Advanced Search

Authentication

  1. Overview
  2. User registries
  3. Authentication cache
  4. JAAS configuration
  5. JAAS login modules
  6. Callback handler
  7. Credentials and tokens
  8. LTPA
  9. Single sign-on (SSO)
  10. Pluggable authentication
  11. Identity assertion
  12. RunAs() authentication
  13. Proxy login module
  14. Certificate login
  15. Hash table login module
  16. Subtopics


Overview

Authentication in the Liberty security is to confirm the identity of a user.

To access a protected web resource, the user must provide credential data, such as user ID and password. The authentication process involves collecting this user credential information (based on how the web application was configured to collect this data) and validating it against the configured registry. When the credential information is verified, a JAAS subject is created for that user. The subject contains additional information about the user, such as the groups that the user belongs to, and the tokens created for the user. The information in this subject is then used during the authorization process to determine whether the user can access the resource.

The following diagram illustrates a typical authentication process flow for a web resource.

Figure 1. Overview of authentication process

The authentication process involves gathering credential data from the user, checking the cache to see whether the subject exists for that user and in its absence calling the JAAS service to perform the authentication to create a subject. The JAAS service calls a set of login modules to handle the authentication. One or more of the login modules creates the subject depending on the credential data. The login module then calls the registry configured to validate the credential information. If the validation is successful, the authentication process collects and creates relevant information for that user, including the groups that the user belongs to and the single sign-on (SSO) token used for SSO capability, and stores them in the subject as relevant credentials. We can also customize the information saved in the subject by plugging in custom login modules during this process.

When the authentication is successful, the SSO token that is created during the process is sent back to the browser in a cookie. The default name of the configurable cookie is ltpaToken2. On subsequent calls, the token information is used to authenticate the user. If this authentication fails, the authentication service tries to use other authentication data, such as the user ID and password, if they still exist in the request.

To support user IDs and passwords containing non US-ASCII characters, form login method is required for web applications.

See autoRequestEncoding and autoResponseEncoding.


User registries

When validating the authentication data of a user, the login modules call the user registry configured to validate the user information. The Liberty profile supports both a simple configuration-based user registry and a more robust LDAP-based repository.

See Configure a user registry .

Using the LDAP registry, we can also federate multiple repositories and execute the LDAP operations on two or more registries. The Liberty profile user can configure the LDAP registry federation feature either directly in server.xml or can configure in the LDAP Registry Federation section in the developer tool. After the configuration of the federated repositories, we can obtain a consolidated result of the federated repositories on any operation to perform. For example, to perform a search operation for all user names that starts with test, we can perform a search across the set of LDAP registries and get the consolidated search result which can then be sent back to the calling program.


Authentication cache

Because creating a subject is relatively expensive, the Liberty profile provides an authentication cache to store a subject after the authentication of a user is successful. The default expiration time for the cache is 10 minutes. If the user does not log back in within 10 minutes, the subject is removed and the process of authentication repeats to create a subject for that user. Changes to the configuration that affect the creation of the subject, such as adding a login module or changing the LTPA keys, will cause the authentication cache to be cleared. If the subject is cached and the information in the registry changes, the cache is updated with the information in the registry. We can configure the cache timeout period, and the cache size, and we can also disable or enable caching.

See Configure the authentication cache .


JAAS configuration

JAAS configuration defines a set of login modules to create the subject. The Liberty profile supports the following JAAS configurations:

system.WEB_INBOUND

Used when accessing web resources such as servlets and JSPs.

WSLogin

Used by applications when using the programmatic login.

system.DEFAULT

Used for login when no JAAS configuration is specified.

system.DESERIALIZE_CONTEXT

Used when a security context is being deserialized. This JAAS configuration handles authentication to re-create the subjects that were active on the thread at the time the security context was serialized. We can specify this JAAS configuration and add our own custom JAAS login modules by editing the JAAS configuration entry in server.xml to ensure that the propagated subjects contain the custom information.

The system.WEB_INBOUND and system.DEFAULT configurations have these default login modules in this order: hashtable, userNameAndPassword, certificate, and token. The WSLogin configuration has the proxy login module as the default login module, and the proxy delegates all the operations to the real login module in system.DEFAULT.

No explicit configuration is required unless to customize using the custom login modules. Depending on the requirement, we can customize specific login configurations. For example, if we want all the web resource logins to be customized, add custom login modules only to the system.WEB_INBOUND configuration. See Configure a JAAS custom login module .


JAAS login modules

JAAS configuration uses a set of login modules to create the subject. The Liberty profile provides a set of login modules in each of the login configurations. Depending on the authentication data, a particular login module creates the subject. The authentication data is passed to the login modules using the callback handler, as specified in the JAAS specification. For example, if the user ID and password callback handler is being used for authentication, the userNameAndPassword login module handles the authentication. If a SingleSignonToken credential is presented as the authentication data, only the token login module handles the authentication.

The following default login modules are supported in the Liberty profile:

userNameAndPassword

Handles the authentication when user name and password are used as the authentication data.

certificate

Handles the authentication when an X509 certificate is used as the authentication data of mutual SSL.

token

Handles the authentication when an SSO token is presented as the authentication data. During the authentication process, an SSO token is created and sent back to the HTTP client (browser) in a cookie. On subsequent requests, this cookie is sent back by the browser and the server extracts the token from the cookie to authenticate the user when the single sign-on is enabled.

hashtable

Used when the authenticated data is sent through a predefined hash table. For more information about the hash table login, see Hash table login module. This login module is also used by the security run time when authentication is performed using identity only; for example, in the case of runAs.

proxy

The default login module for WSLogin. See Proxy login module.

The login modules are called in the order that they are configured. The default order is hashtable, userNameAndPassword, certificate, token. If we must customize the login process using custom login modules, we can provide them and configure them in the order we need. Typically, place a custom login module first in the list of login modules so that it is called first. When a custom login module is used, we must specify all the login module information in the configuration along with the custom login module in the required order.

When a login module determines that it can handle the authentication, it first makes sure that the authentication data that is passed in is valid. For example, for user name and password authentication, the configured user registry is called to verify the authentication information. For token authentication, the token must be decrypted and valid for the verification to succeed.

When the authentication data is validated, the login modules create credentials with additional data for the user including the groups and the SSO token. A custom login module can add additional data to the subject by creating its own credentials. For the Liberty profile authorization to work, the subject must contain the WSCredential, WSPrincipal, and SingleSignonToken credentials. The WSCredential credential contains the groups information, with additional information that is required by the security runtime environment.


Callback handler

The Liberty profile supports various callback handlers for providing data to the login modules during the JAAS authentication process. A custom login module can use the callback handler information to authenticate itself. For example, if the callback handler needs to access some information in an HttpServletRequest object, it can do so using that specific callback handler.

The following callback handlers and factories for programmatic JAAS login are supported in the Liberty profile:

The Java API documentation for each Liberty profile API is detailed in the Programming Interfaces (APIs) section of the information center, and is also available as a separate .zip file in one of the javadoc subdirectories of the ${wlp.install.dir}/dev directory.

See Develop JAAS custom login modules for a system login configuration.


Credentials and tokens

As mentioned in the loginModule section, credentials are created as part of the subject creation process. The Liberty profile creates the WSCredential, SingleSignonToken, and WSPrincipal credentials. The SingleSignonToken credential contains the token that is sent back to the browser in a cookie for SSO to work. This token contains the user information and an expiration time. It is signed and encrypted using the Lightweight Third Party Authentication (LTPA) keys generated during the first server startup. The default expiration time is 2 hours and is an absolute time, not based on user activities. After the 2 hours, the token expires and the user must log in again to access the resource.


LTPA

LTPA is intended for distributed and multiple application server environments. In the Liberty profile, LTPA supports SSO and security in a distributed environment through cryptography. This support enables LTPA to encrypt, digitally sign, and securely transmit authentication-related data, and later decrypt and verify the signature.

Application servers can securely communicate using the LTPA protocol. The protocol also provides the SSO feature, whereby a user is required to authenticate only when connecting to a domain name system (DNS). Then the user can access resources in other Liberty profile servers in the same domain without getting prompted. The realm names on each system in the DNS domain are case-sensitive and must match identically.

The LTPA protocol uses cryptographic keys to encrypt and decrypt user data that passes between the servers. These keys must be shared between different servers for the resources in one server to access resources in other servers, assuming that all the servers involved use the same user registry. LTPA requires that the configured user registry must be a centrally shared repository so that users and groups are the same, regardless of the server.

When using LTPA, a token is created containing the user information and an expiration time, and is signed by the keys. The LTPA token is time sensitive. All participating servers must have their time and date synchronized. If not, LTPA tokens are prematurely expired and cause authentication or validation failures. Coordinated Universal Time (UTC) is used by default, and all other servers must have the same UTC time. See the operating system documentation for information about how to ensure the same UTC time among servers.

The LTPA token passes to other servers through cookies for web resources when SSO is enabled.

If the receiving servers use the same keys as the originating server, the token can be decrypted to obtain the user information, which then is validated to verify the token is not expired and that the user information in the token is valid in its registry. On successful validation, the resources in the receiving servers are accessible after the authorization check.

Each server must have valid credentials. When the credentials expire, the server is required to communicate to the user registry to authenticate. Extending the time that the LTPA token remains cached presents a slightly increased security risk to be considered when defining the security policies.

If key sharing is required between different Liberty profile servers, copy the keys from one server to another. For security purposes, the keys are encrypted with a randomly-generated key, and a user-defined password is used to protect the keys. This same password is needed when importing the keys into another server. The password is used only to protect the keys, and is not used to generate the keys.

When security is enabled, LTPA is configured by default during the Liberty profile server start time. For more information about the LTPA support, see Configure LTPA .


Single sign-on (SSO)

SSO enables users to log in in one place (one server for example) and access applications on other servers without getting prompted again. To make SSO work, the LTPA keys must be exchanged across different Liberty profile servers, the user registries must be the same, and the token must not have expired. To exchange the LTPA keys, we can copy the ltpa.keys file from one server to another and restart the server to use the new LTPA keys. The registries that are used by all the servers participating in the SSO domain must be the same.

When a user is authenticated in one Liberty profile server, the SSO token created for the user during the authentication process is put in the cookie that is sent to the HTTP client, for example a browser. If there is another request from that client to access another set of applications on a different server, but in the same DNS that was configured as part of the SSO configuration in the first server, the cookie is sent along with the request. The receiving server tries to authenticate the user using the token in the cookie. If both conditions are met, the receiving server validates the token and creates a subject based on the user in this server, without prompting the user to log in again. If the token cannot be validated (for example, it cannot decrypt or verify the token because of LTPA key mismatch), the user is prompted to enter the credential information again.

Any application configured to use the Form-login attribute must have SSO to be configured for that server. When the user is authenticated for a form-login, the token is sent back to the browser that will be used for authorizing the user when the resource is accessed.

See Customize SSO configuration using LTPA cookies .


Pluggable authentication

Use the following ways to customize the authentication process:

For more details about the JAAS login module and TAI, see Advanced authentication in WebSphere Application Server.


Identity assertion

Besides authentication that requires a requesting entity to prove its identity, the Liberty profile also supports identity assertion. This is a relaxed form of authentication that does not require identity proof, but rather accepts the identity based on a trust relationship with the entity that vouches for the asserted identity.

Use the following ways to assert identities in the Liberty profile

  1. Use the hash table login. See Develop JAAS custom login modules for a system login configuration.

  2. Use IdentityAssertionLoginModule. We can allow an application or system provider to assert an identity with trust validation. To use IdentityAssertionLoginModule, use the JAAS login framework, where trust validation is accomplished in one custom login module and credential creation is accomplished in IdentityAssertionLoginModule. We can use the two login modules to create a JAAS login configuration that can be used to assert an identity.

    The following two custom login modules are required:

    User implemented login module (trust validation)

    The user implemented login module performs whatever the user requires in trust verification. When trust is verified, the trust verification status and the login identity must be put into a map in the share state of the login module, so the credential creation login module can use the information. Store this map in the following property:

      com.ibm.wsspi.security.common.auth.module.IdentityAssertionLoginModule.state

    This property consists of the following properties:

      • com.ibm.wsspi.security.common.auth.module.IdentityAssertionLoginModule.trusted

      This property is set to true if trusted and false if not trusted.

      • com.ibm.wsspi.security.common.auth.module.IdenityAssertionLoginModule.principal

      This property contains the principal of the identity.

      • com.ibm.wsspi.security.common.auth.module.IdentityAssertionLoginModule.certificates

      This property contains the certificate of the identity.

    Identity assertion login module (credential creation)

    The following module creates the credential:

      com.ibm.wsspi.security.common.auth.module.IdentityAssertionLoginModule

    This module relies on the trust state information in the shared state of the login context.

    The identity assertion login module looks for the trust information in the shared state property:

      com.ibm.wsspi.security.common.auth.module.IdentityAssertionLoginModule.state

    This property contains the trust status and the identity to log in, and must include the following property:

      • com.ibm.wsspi.security.common.auth.module.IdentityAssertionLoginModule.trusted

      This property is set to true when trusted and false when not trusted.

      • com.ibm.wsspi.security.common.auth.module.IdentityAssertionLoginModule.principal

      This property contains the principal of the identity to log in if a principal is used.

      • com.ibm.wsspi.security.common.auth.module.IdentityAssertionLoginModule.certificates

      This property contains an array of a certificate chain containing the identity to log in if a certificate is used.

    A WSLoginFailedException message is returned if the state, trust, or identity information is missing. The login module then logs in with the identity, and the subject contains the new identity.

    See Customize an application login to perform an identity assertion using JAAS.


RunAs() authentication

When we have successfully authenticated after calling a servlet, the servlet can make subsequent calls, for example to other servlets. These subsequent calls are normally made under the same security identity originally used to log in to the servlet. This identity is known as the caller identity. Alternatively, we can choose to delegate to a different identity using the RunAs specification, so that any subsequent calls that the servlet makes run under this other identity. To summarize, we have two options to propagate the security identity:

After the server authenticates the original user, the server then authenticates the RunAs user. If this authentication fails, the server falls back to propagate the caller identity.

To use the RunAs specification, update the deployment descriptor of the application to include the run-as element or @RunAs annotation. Set this element to the security role to delegate to.

See Configure RunAs authentication .


Proxy login module

The proxy login module class loads the application server login module and delegates all the operations to the real login module implementation. The real login module implementation is specified as the delegate option in the option configuration. The proxy login module is required because the application class loaders do not have visibility of shared library class loaders of the application server product. With an application programmatic login that uses the Login() method of the LoginContext class with JAAS login context entry WSLogin, the proxy login module delegates all the work to the JAAS login context entry system.DEFAULT.


Certificate login

With the certificate login feature, we can authenticate web requests such as servlets using client side X509 certificates instead of supplying a user ID and password.

Certificate authentication works by associating a user in the user registry with the distinguished name in the client certificate of a web request. Trust is established by having the client certificate trusted by the server, for example the signer of the client certificate must be in the trust store of the server. This mechanism eliminates the need for users to supply a password to establish trust.

See Secure communications with the Liberty profile.


Hash table login module

Look up the required attributes from the user registry, put the attributes in a hash table, and then add the hash table to the shared state. If the identity is switched in this login module, add the hash table to the shared state. If the identity is not switched, but the value of the requiresLogin code is true, we can create the hash table of attributes. You do not have to create a hash table in this situation, because the Liberty profile handles the login for you. However, we might consider creating a hash table to gather attributes in special cases. For example, if we are using our own special user registry, then creating a UserRegistry implementation, using a hash table, and letting the server gather the user attributes for you, might be a simple solution.

The following rules define in more details about how a hash table login is completed. We must use a java.util.Hashtable object in either the Subject (public or private credential set) or the shared-state HashMap. The com.ibm.wsspi.security.token.AttributeNameConstants class defines the keys containing the user information. If the Hashtable object is put into the shared state of the login context using a custom login module that is listed before the hashtable login module, the value of the java.util.Hashtable object is searched using the following key within the shared-state hashMap:

Property

com.ibm.wsspi.security.cred.propertiesObject

Reference to the property

AttributeNameConstants.WSCREDENTIAL_PROPERTIES_KEY

Explanation

This key searches for the Hashtable object containing the required properties in the shared state of the login context.

Expected result

A java.util.Hashtable object.

If a java.util.Hashtable object is found inside the Subject or within the shared state area, verify that the following properties are present in the hash table:


Subtopics


Parent topic: Security

Tasks:

  • Authenticate users

    Reference:

  • Security considerations