About
LoginModules are components of Authentication providers.
They are responsible for authenticating users within the security realm and for populating a subject with the necessary principals (users/groups).
They are called in the order in which the Authentication providers are configured.
LoginModules can be written to handle a variety of authentication mechanisms, including username/password combinations, smart cards, biometric devices, and so on.
Articles Related
Subject
A subject is a container for authentication information.
The Java Authentication and Authorization Service (JAAS) requires subjects to used them as containers for authentication information, including principals.
Each principal stored in the same subject represents a separate aspect of the same user’s identity, much like cards in a person’s wallet. (For example, an ATM card identifies someone to their bank, while a membership card identifies them to a professional organization to which they belong.)
If there are multiple Authentication providers configured in a security realm, each of the Authentication providers’ LoginModules will store principals within the same subject.
Therefore, if a principal that represents a WebLogic Server user named “Joe” is added to the subject by one Authentication provider’s LoginModule, any other Authentication provider in the security realm should be referring to the same person when they encounter “Joe”.
In other words, the other Authentication providers’ LoginModules should not attempt to add another principal to the subject that represents a WebLogic Server user (for example, named “Joseph”) to refer to the same person.
However, it is acceptable for a another Authentication provider’s LoginModule to add a principal of a type other than WLSUser with the name “Joseph”.
Flow
Control Flag
The way each LoginModule’s control flag is set specifies how a failure during the authentication process should be handled and is is especially important for multipart authentication.
Below: LoginModule = Authentication
| JAAS Control Flag | Authentication provider Always Called ? | Authentication must succeed | Next Step if authentication succeeds | Next Step if authentication fails |
|---|---|---|---|---|
| SUFFICIENT | No | No | Control is returned to the application | if other Authentication providers are configured, authentication proceeds down the LoginModule list |
| OPTIONAL | No | No * | Authentication proceeds down the list of LoginModules | |
| REQUIRED | Yes | Yes | Authentication proceeds down the list of LoginModules | |
| REQUISITE | No | Yes | Authentication proceeds down the list of LoginModules. | Control is returned to the application |
- *If all Authentication providers configured in a security realm have the JAAS Control Flag set to OPTIONAL, the user must pass the authentication test of one of the configured providers.
When additional Authentication providers are added to an existing security realm, by default the Control Flag is set to OPTIONAL.
The non-dynamic attribute ControlFlag when changed may require redeploying or rebooting configured entities.
Example
The figure below illustrates a sample flow involving three different LoginModules. It illustrates what happens to the subject for different authentication outcomes.
- If the control flag for Custom Authentication Provider #1 had been set to Required, the authentication failure in its User Authentication step would have caused the entire authentication process to have failed.
- If the user had not been authenticated by the WebLogic Authentication provider (or custom Authentication provider #2), the entire authentication process would have failed.
If the authentication process had failed in any of these ways, all three LoginModules would have been rolled back and the subject would not contain any principals.