Authentication

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

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

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 that the user belongs to, and the tokens that are 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
Authentication service uses JAAS login modules to handle the authentication.

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 that is 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 that is used for SSO capability, and stores them in the subject as relevant credentials. You can also customize the information that is saved in the subject by plugging in custom login modules during this process.

When theT 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.
Note: To support user IDs and passwords that contain non US-ASCII characters, form login method is required for web applications. For more information, see autoRequestEncoding and autoResponseEncoding.
The following sections describe these concepts in detail:

User registries

When validating the authentication data of a user, the login modules call the user registry that is configured to validate the user information. Liberty supports both a simple configuration-based user registry and a more robust LDAP-based registry. For more information, see Configuring a user registry in Liberty.

Using the LDAP registry, you 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, you can obtain a consolidated result of the federated repositories on any operation that you want to perform. For example, if you want to perform a search operation for all user names that starts with test, you 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. You can configure the cache timeout period, and the cache size, and you can also disable or enable caching. For more information, see Configuring 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 that is 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. You can specify this JAAS configuration and add your 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 that is 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 you want to customize by using the custom login modules. Depending on the requirement, you can customize specific login configurations. For example, if you want all the web resource logins to be customized, you must add custom login modules only to the system.WEB_INBOUND configuration. See Configuring 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 by 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 you must customize the login process by using custom login modules, you can provide them and configure them in the order you 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, you 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 by 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 Programming 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 Developing 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 by 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 by 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 that contains 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 your 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 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 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 Configuring 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 that 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 Configuring 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 Configuring an OpenID Connect Client in Liberty. For configuring an OpenID Connect Provider on a Liberty server, see Configuring 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 Configuring SPNEGO authentication in Liberty.

Kerberos constrained delegation for SPNEGO

The Kerberos constrained delegation feature provides two APIs that are 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 by 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, you 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 server, the SSO token that is 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 that is 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 is 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:

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
  1. Use the hash table login. See Developing JAAS custom login modules for a system login configuration.
  2. Use IdentityAssertionLoginModule. You 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. You 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 that 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.IdentityAssertionLoginModule.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 that contains 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 Customizing an application login to perform an identity assertion by using JAAS.

RunAs() authentication

When you 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, you can choose to delegate to a different identity by using the RunAs specification, so that any subsequent calls that the servlet makes run under this other identity. To summarize, you have two options to propagate the security identity:
  • Propagate the caller identity, which is the default behavior.
  • Delegate to the RunAs identity that you can specify by 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, you must update the deployment descriptor of your application to include the run-as element or @RunAs annotation. Set this element to the security role that you want to delegate to.

See Configuring 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. For more information, see Configuring a JAAS custom login module for the Liberty application client container.

Certificate login

With the certificate login feature, you can authenticate web requests such as servlets by 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 Securing 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, you must add the hash table to the shared state. If the identity is not switched, but the value of the requiresLogin code is true, you can create the hash table of attributes. You do not have to create a hash table in this situation, because Liberty handles the login for you. However, you might consider creating a hash table to gather attributes in special cases. For example, if you are using your own special user registry, then creating a UserRegistry implementation, by 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. You 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 that contain 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 that contains 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
    Reference to the property
    AttributeNameConstants.WSCREDENTIAL_UNIQUEID
    Returns
    java.util.String
    Explanation
    The value of the property must be a unique representation of the user. For the Liberty default implementation, this property represents the information that is stored in the application authorization configuration. The information is in the application deployment descriptor after it is deployed and the user-to-role mapping is performed. See the expected format examples if the user to role mapping is performed by looking up a user registry implementation of Liberty.
    Expected format examples
    Table 1. Format examples for uniqueId. This table gives expected format examples.
    User Registry Format (UniqueUserId) value
    LDAP ldapRegistryRealm/cn=kevin,o=mycompany,c=use
    Basic basicRegistryRealm/kelvin
    The com.ibm.wsspi.security.cred.uniqueId property is required.
  • com.ibm.wsspi.security.cred.securityName
    Reference to the property
    AttributeNameConstants. WSCREDENTIAL_ SECURITYNAME
    Returns
    java.util.String
    Explanation
    This property searches for securityName of the authentication user. This name is commonly called the display name or short name. Liberty uses the securityName attribute for the getRemoteUser, getUserPrincipal, and getCallerPrincipal application programming interfaces (APIs). To ensure compatibility with the default implementation for the securityName value, call the public String getUserSecurityName(String uniqueUserId) UserRegistry method.
    Expected format examples
    Table 2. Format examples for securityName. This table gives expected format examples.
    User Registry Format (securityName) value
    LDAP kevin
    Basic kevin
    The com.ibm.wsspi.security.cred.securityname property is required.
  • com.ibm.wsspi.security.cred.group
    Reference to the property
    AttributeNameConstants. WSCREDENTIAL_GROUP
    Returns
    java.util.ArrayList
    Explanation
    This key searches for the array list of groups to which the user belongs. The groups are specified in the realm_name/user_name format. The format of these groups is important because the groups are used by the Liberty authorization engine for group-to-role mappings in the deployment descriptor. The format that is provided must match the format expected by Liberty default implementation. When you use a third-party authorization provider, you must use the format that is expected by the third-party provider. To ensure compatibility with the default implementation for the unique group IDs value, call the public List getUniqueGroupIds(String uniqueUserId) UserRegistry method.
    Expected format examples
    Table 3. Format examples for group. This table gives some format examples when configuring inbound identity mapping.
    User Registry Format (group) value
    LDAP ldapRegistryRealm/cn=group1,o=Groups,c=US
    Basic basicRegistryRealm/group1
    The com.ibm.wsspi.security.cred.group property is required. A user is not required to be associated groups.
  • com.ibm.wsspi.security.cred.realm
    Reference to the property
    AttributeNameConstants. WSCREDENTIAL_REALM
    Returns
    java.util.String
    Explanation
    This key property can specify the user registry realm name that is stored in the LTPA cookie.
    This key property is not required.
  • com.ibm.wsspi.security.cred.cacheKey
    Reference to the property
    AttributeNameConstants. WSCREDENTIAL_CACHE_KEY
    Returns
    java.lang.Object
    Explanation
    This key property can specify an object that represents the unique properties of the login, including the user-specific information and the user dynamic attributes that might affect uniqueness. For example, when the user logs in from location A, which might affect their access control, the cache key must include location A so that the received Subject is the correct Subject for the current location.
    This com.ibm.wsspi.security.cred.cacheKey property is not required. When this property is not specified, the cache lookup is the value that is specified for WSCREDENTIAL_UNIQUEID. When this information is found in the java.util.Hashtable object, Liberty creates a Subject similar to the Subject that goes through the normal login process, at least for LTPA. The new Subject contains a WSCredential object and a WSPrincipal object that is fully populated with the information found in the Hashtable object.