Authentication

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

The latest information about authentication in Liberty is available on the Open Liberty website.

A protected web resource must have authorization configured. 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 more information about the user, such as the groups 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.

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

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

The autoRequestEncoding and autoResponseEncoding extensions enable the application server to set the encoding values and content type. Values for both are either true or false. Default value for both is false, which means the request and response character encoding is set to the Servlet Specification default, ISO-8859-1. For more information, 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. Liberty supports both a simple configuration-based user registry and a more robust LDAP-based registry. See Configure a user registry in Liberty.

Use the LDAP registry, we can also federate multiple repositories and run the LDAP operations on two or more registries. Liberty user can configure the LDAP registry federation feature either directly in the server.xml file 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 we want 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, Liberty 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, causes 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 in Liberty.

JAAS configuration

JAAS configuration defines a set of login modules to create the subject. Liberty 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. It is also used by applications running in an application client container, but unlike the ClientContainerJAAS configuration, it does not recognize the CallbackHandler handler specified in the client application module's deployment descriptor.

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 the server.xml file to ensure that the propagated subjects contain your custom information.
ClientContainer: Used by applications running in an application client container. This JAAS login configuration recognizes the CallbackHandler handler specified in the client application module's deployment descriptor, if one is specified.

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 we want 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, we must add custom login modules only to the system.WEB_INBOUND configuration.

See Configure a JAAS custom login module for Liberty.

JAAS login modules

JAAS configuration uses a set of login modules to create the subject. Liberty 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 Liberty:

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 Liberty 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

Liberty 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 must 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 Liberty:

com.ibm.websphere.security.auth.callback.WSCallbackHandlerImpl
com.ibm.wsspi.security.auth.callback.WSCallbackHandlerFactory

The Java API documentation for each Liberty API is detailed in the Program interfaces (Javadoc) section of the online IBM documentation, 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. Liberty 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 that are 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 Liberty, 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 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 make sure that the token is not expired and 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 your security policies.

If key sharing is required between different Liberty 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 Liberty server start time. For more information about the LTPA support, see Configure LTPA in Liberty.

OpenID

OpenID is an open authentication standard that enables users to authenticate themselves to multiple entities without the need to manage multiple accounts or sets of credentials. Liberty supports the OpenID Authentication 2.0 standard by functioning as a Relying Party. In this standard, a Relying Party requires authentication confirmation from an OpenID Provider. Instead of providing credentials to the Relying Party, users are redirected to the OpenID Provider to submit their credentials. The OpenID Provider confirms the authentication result with the Relying Party and returns a unique identifier the user owns, possibly in addition to a subset of personal information that is approved by the user such as the user's name or email address. The Relying Party can then use this information to complete authentication without ever needing to handle the user's credentials. Moreover, users can use a single account with an OpenID Provider to authenticate themselves with any entity that acts as a Relying Party, precluding the need to manage or create unique accounts for each entity.

For more information about OpenID, see OpenID. For configuring OpenID on a Liberty server, see Configure an OpenID Relying Party in Liberty.

OpenID Connect

OpenID Connect is a simple identity protocol and open standard that is built on the OAuth 2.0 protocol. OpenID Connect enables client applications to rely on authentication performed by an OpenID Connect Provider to verify the identity of a user.

Client applications can also obtain basic profile information about an end user in an interoperable and REST-like manner from OpenID Connect Providers. OpenID Connect support is based on the OpenID Connect Standard v1.0.

For more information about OpenID Connect, see OpenID Connect. For configuring an OpenID Connect Client, or Relying Party, on a Liberty server, see Configure an OpenID Connect Client in Liberty. For configuring an OpenID Connect Provider on a Liberty server, see Configure an OpenID Connect Provider in Liberty.

SPNEGO

Simple and Protected GSS-API Negotiation Mechanism (SPNEGO) enables users to log in to the Microsoft Domain controller once and access protected applications on Liberty servers without getting prompted again.

When SPNEGO web authentication is enabled, and a browser client or a non-browser client accesses a protected resource on the Liberty server, SPNEGO authenticates access to the secured resource in the HTTP request. A browser client creates a SPNEGO token. A non-browser client creates a Kerberos service ticket (Kerberos token). The client sends the token to the Liberty server as part of the HTTP request. The WebSphere Application Server validates and retrieves the user identity from the SPNEGO or Kerberos token. The identity is used to establish a secure context between the user and the application server.

For more information about SPNEGO, see Single sign-on for HTTP requests using SPNEGO web authentication. For further information on configuring SPNEGO on the Liberty server, see Configure SPNEGO authentication in Liberty.

Kerberos constrained delegation for SPNEGO

The Kerberos constrained delegation feature provides two APIs used to create out-bound SPNEGO tokens for back end services that support SPNEGO authentication, such as .NET servers and other Liberty servers. The Kerberos v5 extension called S4U (Services for Users) compromises two parts:

S4U2self: Allows a Liberty server to obtain a service ticket to itself on behalf of a user. This can be used with any form of authentication that is supported by Liberty. S4U2self is the Kerberos Protocol Transition extension.
S4U2proxy: Allows a Liberty server to obtain service tickets to trusted services on behalf of a user. These service tickets are obtained using the user's service ticket to the Liberty service. The services are constrained by the Kerberos Key Distribution Center (KDC) administrator. S4U2proxy is the Kerberos Constrained Delegation extension.

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 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 used by all the servers participating in the SSO domain must be the same.

When a user is authenticated in one Liberty 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 that is 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 used for authorizing the user when the resource is accessed.

See Customizing SSO configuration using LTPA cookies in Liberty.

SAML Web Browser SSO

SAML Web Browser SSO enables web applications to delegate user authentication to a SAML identity provider instead of a configured user registry.

For further information on configuring SAML Web Browser SSO on the Liberty server, see SAML 2.0 Web Browser Single-Sign-On.

Pluggable authentication

Use the following ways to customize the authentication process:

Provide a custom login module. Most of the authentication process is built around JAAS login modules, so we can plug in custom login modules before, after, or between the login modules provided by Liberty.
See Configure a JAAS custom login module for Liberty.
Implement Trust Association Interceptor (TAI) to handle all web resource-based authentication.
See Develop a custom TAI for Liberty.

For more information 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, Liberty also supports identity assertion. This is a relaxed form of authentication that does not require identity proof, but rather accepts the identity that is based on a trust relationship with the entity that vouches for the asserted identity. Use the following ways to assert identities in Liberty

Use the hash table login.
See Develop JAAS custom login modules for a system login configuration.
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 used to assert an identity. The following two custom login modules are required:
See Customizing 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 that you 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:

Propagate the caller identity, which is the default behavior.
Delegate to the RunAs identity we can specify using the RunAs specification.

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, we must update the deployment descriptor of the application to include the run-as element or @RunAs annotation. Set this element to the security role we want to delegate to.

See Configure RunAs authentication in Liberty.

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 the WSLogin JAAS login context entry , the proxy login module delegates all the work to the system.DEFAULT JAAS login context entry.

See Configure a JAAS custom login module for the Liberty application client container.

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 truststore of the server. This mechanism eliminates the need for users to supply a password to establish trust.

See Secure communications with Liberty.

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, we must 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. We do not have to create a hash table in this situation, because Liberty 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:

com.ibm.wsspi.security.cred.uniqueId
com.ibm.wsspi.security.cred.securityName
com.ibm.wsspi.security.cred.group
com.ibm.wsspi.security.cred.realm
com.ibm.wsspi.security.cred.cacheKey

User Registry	Format (UniqueUserId) value
LDAP	ldapRegistryRealm/cn=kevin,o=mycompany,c=use
Basic	basicRegistryRealm/kelvin

User Registry	Format (securityName) value
LDAP	kevin
Basic	kevin

User Registry	Format (group) value
LDAP	ldapRegistryRealm/cn=group1,o=Groups,c=US
Basic	basicRegistryRealm/group1