Liberty profile: Authentication

WAS v8.5 > WebSphere applications > Liberty profile > Liberty profile: Security
Liberty profile: Authentication

Overview

The authentication process...

Collect user credential information
Check the cache to see whether the subject exists for that user
If not, the login module calls the registry and validates credential information
If validation is successful, authentication process collections information

Groups the user belongs to
SSO token for the user

A JAAS subject is created.

The information in the JAAS subject is used during the authorization process for protected resources.

If authentication is successful, the SSO token created during the process is sent back to the browser in cookie ltpaToken2.

User registries

To validate user authentication data, the login modules check the user registry. The Liberty profile supports both...

Configuration-based user registry
LDAP-based repository

Authentication cache

Creating a subject can be 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.
Changes to the configuration affecting the creation of the subject, including...

Adding a login module
Change 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...

Set cache timeout period
Set cache size
Disable and enable caching

JAAS configuration

JAAS configuration defines a set of login modules to create the subject...

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.

The system.WEB_INBOUND and system.DEFAULT configurations have these default login modules in this order:

hashtable
userNameAndPassword
certificate
token

The login modules are called in the order they are configured. 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, specify all the login module information in the configuration along with the custom login module in the required order.
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 with custom login modules. Depending on the requirement, we can customize specific login configurations. For example, if you want all the web resource logins to be customized, then add custom login modules only to the system.WEB_INBOUND configuration.

JAAS login modules

Login modules create the subjects. Authentication data is passed to the login modules using the callback handler. 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 is presented as the authentication data, only the token login module handles the authentication.
Default login modules...

userNameAndPassword Handles authentication when user name and password are used as the authentication data.
certificate Handles authentication when an X509 certificate is used as the authentication data of mutual SSL.
token Handles 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 hashtable. 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.

When a login module determines that it can handle the authentication, it first makes sure the authentication data 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 credentials...

WSCredential
WSPrincipal
SingleSignonToken

The WSCredential credential contains the groups information, with additional information required by the security runtime environment.

Callback handler

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:

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

Credentials/Tokens

Credentials are created as part of the subject creation process. The Liberty profile creates the credentials...

WSCredential
SingleSignonToken
WSPrincipal

The SingleSignonToken credential contains the token 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 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 encrypts, digitally signs, and securely transmits authentication-related data, and later uses cryptographic keys to decrypt and verify the signature. Application servers can securely communicate using the LTPA protocol.
LTPA also provides the SSO feature: In a DNS domain a user authenticate once, then is authenticated automatically on other systems in the same DNS domain. The realm names on each system in the DNS domain are case-sensitive and must match identically.
Keys must be shared between different servers for the resources in one server to access resources in other servers. LTPA requires the user registry is shared by all systems in the SSO DNS domain. LTPA tokens contain user information and an expiration time, and are signed by the keys When SSO is enabled the LTPA token passes to other servers through cookies for web resources
Because LTPA tokens are 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.
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 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 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 only used 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.

Single sign-on (SSO)

SSO enables users to log in one place (one server for example) and access applications on other servers without getting prompted again. To make SSO work...

LTPA keys must be exchanged across different Liberty profile servers
User registries must be the same across different Liberty profile servers
The token must not have expired

To exchange the LTPA keys, we can...

Copy ltpa.keys file from one server to another
Restart the server to use the new LTPA keys

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 sent to the HTTP client, either browser or device.
Subsequent requests from the client to access another set of applications on a different server but in the same SSO DNS, the cookie is sent along with the request. The receiving server authenticates 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 accessing the resource.

Pluggable authentication

To customize the authentication process:

Provide a custom login module.
Implement Trust Association Interceptor to handle web resource-based authentication.

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.
To assert identities in the Liberty profile...

Use the hashtable login.

Use the IdentityAssertionLoginModule.
We can allow an application or system provider to assert an identity with trust validation. To use the IdentityAssertionLoginModule, use the JAAS login framework, where trust validation is accomplished in one custom login module and credential creation is accomplished in the 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
Set to true if trusted and false if not trusted.
com.ibm.wsspi.security.common.auth.module.IdenityAssertionLoginModule.principal
Contains the principal of the identity.
com.ibm.wsspi.security.common.auth.module.IdentityAssertionLoginModule.certificates
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

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

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
Set to true when trusted and false when not trusted.
com.ibm.wsspi.security.common.auth.module.IdentityAssertionLoginModule.principal Contains principal of the identity to log in if a principal is used.
com.ibm.wsspi.security.common.auth.module.IdentityAssertionLoginModule.certificates Contains an array of a certificate chain containing the identity to log in if a certificate is used.

A WSLoginFailedException 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 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 the servlet makes run under this other identity.
Options to propagate security identity:

Propagate the caller identity, which is the default behavior.
Delegate to the runAs identity that 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, 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.

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

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.

Hashtable login module

Look up the required attributes from the user registry, put the attributes in a hashtable, and then add the hashtable to the shared state. If the identity is switched in this login module, add the hashtable to the shared state. If the identity is not switched, but the value of the requiresLogin code is true, we can create the hashtable of attributes. We do not have to create a hashtable in this situation, because the Liberty profile handles the login for you. However, you might consider creating a hashtable to gather attributes in special cases. For example, if you are using our own special user registry, then creating a UserRegistry implementation, using a hashtable, 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 hashtable 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 containing the user information. If the Hashtable object is put into the shared state of the login context using a custom login module 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 Search for the Hashtable object containing the required properties in the shared state of the login context.
Expected result java.util.Hashtable object.

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

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 profile default implementation, this property represents the information 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 looking up to a user registry implementation of the Liberty profile.
Expected format examples

User Registry Format (UniqueUserId)
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 Search for the securityName of the authentication user. Commonly called the display or short name. The Liberty profile uses the securityName attribute for the getRemoteUser, getUserPrincipal, and getCallerPrincipal APIs. To ensure compatibility with the default implementation, call getUserSecurityName(String uniqueUserId) UserRegistry.
Expected format examples

User Registry Format (securityName)
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 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 profile authorization engine for group-to-role mappings in the deployment descriptor. The format provided must match the format expected by the Liberty profile default implementation. When you use a third-party authorization provider, use the format 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

User Registry Format (group)
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.cacheKey

Reference to the property AttributeNameConstants. WSCREDENTIAL_CACHE_KEY
Returns java.lang.Object
Explanation 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 the received Subject is the correct Subject for the current location.
Not required. When not specified, the cache lookup is the value specified for WSCREDENTIAL_UNIQUEID. When this information is found in the java.util.Hashtable object, the Liberty profile 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 fully populated with the information found in the Hashtable object.

Parent topic: Liberty profile: Security

Related:

Authenticate users in the Liberty profile
Configuring TAI for the Liberty profile
Customizing SSO configuration using LTPA cookies for the Liberty profile
Configure a JAAS custom login module for the Liberty profile
Configure a basic user registry for the Liberty profile
Configure an LDAP user registry with the Liberty profile
Configuring the authentication cache on the Liberty profile
Configuring LTPA on the Liberty profile
Configuring RunAs authentication in the Liberty profile
Configuring the web application and server for client certificate authentication
Configure a user registry for the Liberty profile

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.

userNameAndPassword	Handles authentication when user name and password are used as the authentication data.
certificate	Handles authentication when an X509 certificate is used as the authentication data of mutual SSL.
token	Handles 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 hashtable. 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.

Property	com.ibm.wsspi.security.cred.propertiesObject
Reference to the property	AttributeNameConstants.WSCREDENTIAL_PROPERTIES_KEY
Explanation	Search for the Hashtable object containing the required properties in the shared state of the login context.
Expected result	java.util.Hashtable object.

Reference to the property	AttributeNameConstants. WSCREDENTIAL_CACHE_KEY
Returns	java.lang.Object
Explanation	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 the received Subject is the correct Subject for the current location. Not required. When not specified, the cache lookup is the value specified for WSCREDENTIAL_UNIQUEID. When this information is found in the java.util.Hashtable object, the Liberty profile 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 fully populated with the information found in the Hashtable object.