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.
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 used for SSO capability, and stores them in the subject as relevant credentials. You can also customize the information saved in the subject by plugging in custom login modules during this process.
When validating the authentication data of a user, the login modules call the user registry that is configured to validate the user information. The Liberty profile supports both a simple configuration-based user registry and a more robust LDAP-based repository. For more information, see Configuring a user registry for the Liberty profile.
Using
the LDAP registry, you 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 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.
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. 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 on the Liberty profile.
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 the Liberty profile.
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 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 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 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.
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 by using that specific callback handler.
See Developing JAAS custom login modules for a system login configuration.
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 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 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 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 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 Configuring LTPA on the Liberty profile.
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, 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 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 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 will be used for authorizing the user when the resource is accessed.
See Customizing SSO configuration using LTPA cookies for the Liberty profile.
For more details about the JAAS login module and TAI, see Advanced authentication in WebSphere® Application Server.
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.
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.com.ibm.wsspi.security.common.auth.module.IdentityAssertionLoginModule
This
module relies on the trust state information in the shared state of
the login context. 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.
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 the Liberty profile.
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.
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 trust store of the server. This mechanism eliminates the need for users to supply a password to establish trust.
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 the Liberty profile 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, 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:
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:
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 |