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.

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 User.query.join(
                    UserLDAP
                ).filter(
                    UserLDAP.dn==user_dn
                ).with_entities(User).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.

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.

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.

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

class flaskbb.auth.services.authentication.DefaultFlaskBBAuthProvider[source]

This is the default username/email and password authentication checker, locates the user based on the identifer passed – either username or email – and compares the supplied password to the hash connected to the matching user (if any).

Offers protection against timing attacks that would rely on the difference in response time from not matching a password hash.

class flaskbb.auth.services.authentication.MarkFailedLogin[source]

Failure handler that marks the login attempt on the user and sets the last failed date when it happened.

class flaskbb.auth.services.authentication.BlockUnactivatedUser[source]

Post auth handler that will block a user that has managed to pass the authentication check but has not actually activated their account yet.

class flaskbb.auth.services.authentication.ClearFailedLogins[source]

Post auth handler that clears all failed login attempts from a user’s account.

class flaskbb.auth.services.authentication.PluginAuthenticationManager(plugin_manager, session)[source]

Authentication manager relying on plugin hooks to manage the authentication process. This is the default authentication manager for FlaskBB.

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.

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
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

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

handle_reauth_failure(user)[source]

This method is abstract.

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

Reauthentication Provided Implementations

class flaskbb.auth.services.reauthentication.DefaultFlaskBBReauthProvider[source]

This is the default reauth provider in FlaskBB, it compares the provided password against the current user’s hashed password.

class flaskbb.auth.services.reauthentication.ClearFailedLoginsOnReauth[source]

Handler that clears failed login attempts after a successful reauthentication.

class flaskbb.auth.services.reauthentication.MarkFailedReauth[source]

Failure handler that marks the failed reauth attempt as a failed login and when it occurred.

class flaskbb.auth.services.reauthentication.PluginReauthenticationManager(plugin_manager, session)[source]

Default reauthentication manager for FlaskBB, it relies on plugin hooks to manage the reauthentication flow.

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