Authentication

FlaskBB exposes several interfaces and hooks to customize authentication and implementations of these. For details on the hooks see Hooks

Authentication Interfaces

class flaskbb.core.auth.authentication.AuthenticationManager[source]

Used to handle the authentication process. A default is implemented, however this interface is provided in case alternative flows are needed.

If a user successfully passes through the entire authentication process, then it should be returned to the caller.

abstractmethod authenticate(identifier, secret)[source]

This method is abstract.

Parameters:

  • identifier (str) – An identifer for the user, typically this is either a username or an email.

  • secret (str) – A secret to verify the user is who they say they are

Returns:

A fully authenticated but not yet logged in user

Return type:

User

class flaskbb.core.auth.authentication.AuthenticationProvider[source]

Used to provide an authentication service for FlaskBB.

For example, an implementer may choose to use LDAP as an authentication source:

class LDAPAuthenticationProvider(AuthenticationProvider):
    def __init__(self, ldap_client):
        self.ldap_client = ldap_client

    def authenticate(self, identifier, secret):
        user_dn = "uid={},ou=flaskbb,ou=org".format(identifier)
        try:
            self.ldap_client.bind_user(user_dn, secret)
            return db.session.execute(
                db.select(User)
                .join(UserLDAP)
                .filter(UserLDAP.dn == user_dn)
            ).scalar_one()
        except Exception:
            return None

During an authentication process, a provider may raise a StopAuthentication exception to completely, but safely halt the process. This is most useful when multiple providers are being used.

abstractmethod authenticate(identifier, secret)[source]

This method is abstract.

Parameters:

  • identifier (str) – An identifer for the user, typically this is either a username or an email.

  • secret (str) – A secret to verify the user is who they say they are

Returns:

An authenticated user.

Return type:

User

class flaskbb.core.auth.authentication.PostAuthenticationHandler[source]

Used to post process authentication success. Post authentication handlers recieve the user instance that was returned by the successful authentication rather than the identifer.

Postprocessors may decide to preform actions such as flashing a message to the user, clearing failed login attempts, etc.

Alternatively, a postprocessor can decide to fail the authentication process anyways by raising StopAuthentication, for example a user may successfully authenticate but has not yet activated their account.

Cancelling a successful authentication will cause registered AuthenticationFailureHandler instances to be run.

Success handlers should not return a value as it will not be considered.

abstractmethod handle_post_auth(user)[source]

This method is abstact.

Parameters:

user (User) – An authenticated but not yet logged in user

class flaskbb.core.auth.authentication.AuthenticationFailureHandler[source]

Used to post process authentication failures, such as no provider returning a user or a provider raising StopAuthentication.

Postprocessing may take many forms, such as incrementing the login attempts locking an account if too many attempts are made, forcing a reauth if the user is currently authenticated in a different session, etc.

Failure handlers should not return a value as it will not be considered.

abstractmethod handle_authentication_failure(identifier)[source]

This method is abstract.

Parameters:

identifier (str) – An identifer for the user, typically this is either a username or an email.

Authentication Provided Implementations

Reauthentication Interfaces

class flaskbb.core.auth.authentication.ReauthenticateManager[source]

Used to handle the reauthentication process in FlaskBB. A default implementation is provided, however this is interface exists in case alternative flows are desired.

Unlike the AuthenticationManager, there is no need to return the user to the caller.

abstractmethod reauthenticate(user, secret)[source]

This method is abstract.

Parameters:

  • user (User) – The current user instance

  • secret (str) – The secret provided by the user

class flaskbb.core.auth.authentication.ReauthenticateProvider[source]

Used to reauthenticate a user that is already logged into the system, for example when suspicious activity is detected in their session.

ReauthenticateProviders are similiar to AuthenticationProvider except they receive a user instance rather than an identifer for a user.

A successful reauthentication should return True while failures should return None in order to give other providers an attempt run.

If a ReauthenticateProvider determines that reauthentication should immediately end, it may raise :class:~flaskbb.core.auth.authentication.StopAuthentication` to safely end the process.

An example:

class LDAPReauthenticateProvider(ReauthenticateProvider):
    def __init__(self, ldap_client):
        self.ldap_client = ldap_client

    def reauthenticate(self, user, secret):
        user_dn = "uid={},ou=flaskbb,ou=org".format(user.username)
        try:
            self.ldap_client.bind_user(user_dn, secret)
            return True
        except Exception:
            return None
abstractmethod reauthenticate(user, secret)[source]

This method is abstract.

Parameters:

  • user (User) – The current user instance

  • secret (str) – The secret provided by the user

Returns:

True for a successful reauth, otherwise None

class flaskbb.core.auth.authentication.PostReauthenticateHandler[source]

Used to post process successful reauthentication attempts.

PostAuthenticationHandlers are similar to PostAuthenticationHandler, including their ability to cancel a successful attempt by raising StopAuthentication

abstractmethod handle_post_reauth(user)[source]

This method is abstract.

Parameters:

user (User) – The current user instance that passed the reauth attempt

class flaskbb.core.auth.authentication.ReauthenticateFailureHandler[source]

Used to manager reauthentication failures in FlaskBB.

ReauthenticateFailureHandlers are similiar to AuthenticationFailureHandler except they receive the user instance rather than an indentifier for a user

abstractmethod handle_reauth_failure(user)[source]

This method is abstract.

Parameters:

user (User) – The current user instance that failed the reauth attempt

Reauthentication Provided Implementations

Exceptions

exception flaskbb.core.auth.authentication.StopAuthentication(reason)[source]

Used by Authentication providers to halt any further attempts to authenticate a user.

Parameters:

str (reason) – The reason why authentication was halted

exception flaskbb.core.auth.authentication.ForceLogout(reason)[source]

Used to forcefully log a user out.

Parameters:

str (reason) – The reason why the user was force logged out