Oak Documentation

Brief recap of the JAAS authentication

The following section is copied and adapted from the javadoc of javax.security.auth.spi.LoginModule. The authentication process within the LoginModule proceeds in two distinct phases, login and commit phase:

Phase 1: Login

1. In the first phase, the LoginModule's login method gets invoked by the LoginContext's login method.
2. The login method for the LoginModule then performs the actual authentication (prompt for and verify a password for example) and saves its authentication status as private state information.
3. Once finished, the LoginModule's login method either returns true (if it succeeded) or false (if it should be ignored), or throws a LoginException to specify a failure. In the failure case, the LoginModule must not retry the authentication or introduce delays. The responsibility of such tasks belongs to the application. If the application attempts to retry the authentication, the LoginModule's login method will be called again.

Phase 2: Commit

1. In the second phase, if the LoginContext's overall authentication succeeded (the relevant REQUIRED, REQUISITE, SUFFICIENT and OPTIONAL LoginModules succeeded), then the commit method for the LoginModule gets invoked.
2. The commit method for a LoginModule checks its privately saved state to see if its own authentication succeeded.
3. If the overall LoginContext authentication succeeded and the LoginModule's own authentication succeeded, then the commit method associates the relevant Principals (authenticated identities) and Credentials (authentication data such as cryptographic keys) with the Subject located within the LoginModule.
4. If the LoginContext's overall authentication failed (the relevant REQUIRED, REQUISITE, SUFFICIENT and OPTIONAL LoginModules did not succeed), then the abort method for each LoginModule gets invoked. In this case, the LoginModule removes/destroys any authentication state originally saved.

Login module execution order

Very simply put, all the login modules that participate in JAAS authentication are configured in a list and can have flags indicating how to treat their behaviors on the login() calls.

JAAS defines the following module flags:
(The following section is copied and adapted from the javadoc of javax.security.auth.login.Configuration)

• Required: The LoginModule is required to succeed. If it succeeds or fails, authentication still continues to proceed down the LoginModule list.
• Requisite: The LoginModule is required to succeed. If it succeeds, authentication continues down the LoginModule list. If it fails, control immediately returns to the application (authentication does not proceed down the LoginModule list).
• Sufficient: The LoginModule is not required to succeed. If it does succeed, control immediately returns to the application (authentication does not proceed down the LoginModule list). If it fails, authentication continues down the LoginModule list.
• Optional: The LoginModule is not required to succeed. If it succeeds or fails, authentication still continues to proceed down the LoginModule list.

The overall authentication succeeds only if all Required and Requisite LoginModules succeed. If a Sufficient LoginModule is configured and succeeds, then only the Required and Requisite LoginModules prior to that Sufficient LoginModule need to have succeeded for the overall authentication to succeed. If no Required or Requisite LoginModules are configured for an application, then at least one Sufficient or Optional LoginModule must succeed.

Abstract Login Module

This package also contains a abstract LoginModule implementation (AbstractLoginModule) providing common functionality. In particular it contains Oak specific methods that allow subclasses to retrieve the SecurityProvider, a Root and accesss to various security related interfaces (e.g. PrincipalManager).

Subclasses are required to implement the following methods:

• getSupportedCredentials(): return a set of supported credential classes. See also section Supported Credentials
• login(): The login method defined by LoginModule
• commit(): The commit method defined by LoginModule

public class TestLoginModule extends AbstractLoginModule {

    private Credentials credentials;
    private String userId;
    private Set<? extends Principal> principals;

    @Nonnull
    @Override
    protected Set<Class> getSupportedCredentials() {
        return Set.of(TestCredentials.class);
    }

    @Override
    public boolean login() throws LoginException {
        credentials = getCredentials();
        if (validCredentials(credentials)) {
            this.credentials = credentials;
            this.userId = getUserId(credentials);
            this.principals = getPrincipals(userId);
            return true;
        }
        return false;
    }

    @Override
    public boolean commit() throws LoginException {
        if (credentials != null) {
            if (!subject.isReadOnly()) {
                subject.getPublicCredentials().add(credentials);
                if (principals != null) {
                    subject.getPrincipals().addAll(principals);
                }
                AuthInfo authInfo = new AuthInfoImpl(userId, Collections.EMPTY_MAP, principals);
                setAuthInfo(authInfo, subject);
            }
            return true;
        }
        return false;
    }
}

Examples

import javax.security.auth.login.AppConfigurationEntry
import javax.security.auth.login.Configuration;

AppConfigurationEntry[] entries = new AppConfigurationEntry[]{new DefaultEntry(options)};
Configuration c = new Configuration() {
     @Override
     public AppConfigurationEntry[] getAppConfigurationEntry(String applicationName) {
         Map<String, ?> options = [....];
         
         // choose control flag for custom login module (example here: REQUIRED)
         AppConfigurationEntry.LoginModuleControlFlag flag = LoginModuleControlFlag.SUFFICIENT;
         
         // create an entry for your custom login module
         AppConfigurationEntry customEntry = new AppConfigurationEntry("your.org.LoginModuleClassName", flag, options)
         
         // additionally use the oak default login module
         AppConfigurationEntry defaultEntry = new AppConfigurationEntry(("org.apache.jackrabbit.oak.security.authentication.user.LoginModuleImpl", LoginModuleControlFlag.REQUIRED, options)
         
         // define array of all entries in the correct order according to your needs
         return new AppConfigurationEntry[]{customEntry, defaultEntry};
     }
};
Configuration.setConfiguration(c);