Oak Documentation

The LoginModule Sequence

• The GuestLoginModule is in charge of handling unauthenticated guest login without passing [GuestCredentials]. In other words: if no credentials can be obtained during the login phase, an new instance of [GuestCredentials] is pushed to the shared state and this module succeeds. Due to the optional flag success is not required and the authentication proceeds down the list of modules. This module helps to cover non-standard guest login with null credentials as it is performed by Apache Sling (compatibility with Jackrabbit 1.0)

• The TokenLoginModule is in charge of handling repository authentication request with TokenCredentials:

  • Login Success: If token-login succeeds the sufficient flag makes sure authentication does not proceed down the LoginModule list. This means that it will not hit the ExternalIdentityProvider and will not re-sync an external user as long as the login token is valid.
  • Login Failure: If it fails (e.g. other type of Credentials) the authentication will proceed down the LoginModule list.
  • Commit: If the login failed the login module will test if the Credentials passed to the login ask for generation of a new login token. If this login succeeded it will populate the Subject with Principals, Credentials and AuthInfo.

  NOTE: In this setup the TokenLoginModule is expected to only handle subsequent authentication request after having issued a login token. The latter is achieved by providing Credentials attributes that force the TokenLoginModule to generate a new login token in the commit phase. The application should then use that login toke for subsequent requests.

  See Token Authentication and Token Management for details and for a description of the default implementation.

• The ExternalLoginModule is in charge of handling authentication request for users managed by an ExternalIdentityProvider.

  • Login Success: If user authentication against the IDP succeeds the module synchronizes the external user into the repository according to the logic defined in the configure SyncHandler. If the user has been synced before it might be updated. If and how often a user gets re-synced is an implementation detail of the SyncHandler.

  • Login Failure: If the authentication fails (e.g. wrong IDP or invalid Credentials), the login will proceed to the LoginModuleImpl.

  • Commit: If the login succeeded the login module will populate the Subject with Principals, Credentials and AuthInfo.

    NOTE: if no login token is generated upon first login, any subsequent login for external users will end up being handled by this module (including connection to the IDP) or fail.

• The LoginModuleImpl is in charge of handling authentication request for users managed and created through the repository's user management API; i.e. users that are not defined by an ExternalIdentityProvider. This includes built-in system users like the administrator, the guest-user (aka anonymous) or SystemUsers. It also handles impersonation logins.

  • Login Success: If regular user authentication (or impersonation) succeeds the sufficient flag makes sure authentication does not proceed down the LoginModule list i.e. omits unnecessarily trying to authenticate a local user against the external IDP.

  • Login Failure: If the authentication fails (e.g. no local user that could have uid/pw matching the passed Credentials), it will continue down the LoginModule list.

  • Commit: If the login succeeded the login module will populate the Subject with Principals, Credentials and AuthInfo.

    NOTE: if no login token is generated upon first login, any subsequent login for local users will end up being handled by this module or fail.

The LoginModule Sequence

• The TokenLoginModule is in charge of handling repository authentication request with TokenCredentials:

  • Login Success: If token-login succeeds the sufficient flag makes sure authentication does not proceed down the LoginModule list. This means that it will not hit the ExternalIdentityProvider and will not re-sync an external user as long as the login token is valid.
  • Login Failure: If it fails (e.g. other type of Credentials) the authentication will proceed down the LoginModule list.
  • Commit: If the login failed the login module will test if the Credentials passed to the login ask for generation of a new login token. If this login succeeded it will populate the Subject with Principals, Credentials and AuthInfo.

  NOTE: In this setup the TokenLoginModule is expected to only handle subsequent authentication request after having issued a login token. The latter is achieved by providing Credentials attributes that force the TokenLoginModule to generate a new login token in the commit phase. The application should then use that login toke for subsequent requests.

  See Token Authentication and Token Management for details and for a description of the default implementation.

• The LoginModuleImpl is in charge of handling authentication request for users managed and created through the repository's user management API; i.e. users that are not defined by an ExternalIdentityProvider. This includes built-in system users like the administrator, the guest-user (aka anonymous) or SystemUsers. It also handles impersonation logins.

  • Login Success: If regular user authentication (or impersonation) succeeds the sufficient flag makes sure authentication does not proceed down the LoginModule list i.e. omits unnecessarily trying to authenticate a local user against the external IDP.

  • Login Failure: If the authentication fails (e.g. no local user that could have uid/pw matching the passed Credentials), it will continue down the LoginModule list.

  • Commit: If the login succeeded the login module will populate the Subject with Principals, Credentials and AuthInfo.

    NOTE: if no login token is generated upon first login, any subsequent login for local users will end up being handled by this module or fail.

• The ExternalLoginModule is in charge of handling authentication request for users managed by an ExternalIdentityProvider.

  • Login Success: If user authentication against the IDP succeeds the module synchronizes the external user into the repository according to the logic defined in the configure SyncHandler. If the user has been synced before it might be updated. If and how often a user gets re-synced is an implementation detail of the SyncHandler.

  • Login Failure: If the authentication fails (e.g. wrong IDP or invalid Credentials), the whole login will fail because the ExternalLoginModule is configured to be required and the last module in the chain.

  • Commit: If the login succeeded the login module will populate the Subject with Principals, Credentials and AuthInfo.

    NOTE: if no login token is generated upon first login, any subsequent login for external users will end up being handled by this module (including connection to the IDP) or fail.

Login with Different Credentials

The LoginModule Sequence

• The custom pre-auth module is in charge of handling custom pre-auth Credentials shared between the code performing the authentication outside of the scope of the repository and this module. It's only task is to create the PreAuthenticatedLogin marker and push it to the shared stated to inform subsequent modules, which will always be consulted due to the optional flag. - Login Success: not desired as we want subsequent modules to verify if there is a matching identity for the PreAuthenticatedLogin and later on populate the subject. - Login Failure: the default passing over the responsibility the other modules in the chain. - Commit: Nothing to do.

• The LoginModuleImpl will try to resolve the repository user associated with the PreAuthenticatedLogin or perform regular login with the login Credentials if no PreAuthenticatedLogin is present. - Login Success: If there exists a valid user for the given PreAuthenticatedLogin or Credentials login will always succeed in case of a pre-auth login. Otherwise credentials are regularly evaluated (e.g. password validation). The authentication will continue down the chain due to the optional flag. - Login Failure: If no matching user exists or if the user is not valid (e.g. disabled). In case of regular authentication it will fail if the Credentials cannot be validated. Then authentication it will again continue down the LoginModule list. - Commit: If the login succeeded the login module will populate the Subject with Principals, Credentials and AuthInfo.

• The ExternalLoginModule will try to resolve the PreAuthenticatedLogin or alternatively the Credentials to a SyncedIdentity. - If no SyncedIdentity exists the user is retrieved from external IDP and eventually synced into the repository. In case no PreAuthenticatedLogin is present retrieving identity additionally includes credentials validation. - If there exists a SyncedIdentity the module will validate it. In case of PreAuthenticatedLogin it checks if the identity needs to be synced again. - Login Success: If there exists a valid external identity on the IDP and it has be synced with the repository. - Login Failure: If no matching/valid identity exists on the IDP or if there exists a SyncedIdentity that doesn't belong to the IDP or we have a PreAuthenticatedLogin marker and the SyncedIdentity doesn't need a re-sync. - Commit: If the login succeeded the login module will populate the Subject with Principals, Credentials and AuthInfo.

Login with Different Credentials

FAQ