API

Core

class flask_multipass.core.Multipass(app=None)

Base class of the Flask-Multipass extension.

Parameters:app – The flask application. If omitted, use init_app() to initialize the extension for you application.
auth_providers

Returns a read-only dict of the active auth providers

get_group(provider, name)

Returns a specific group

Parameters:
  • provider – The name of the provider containing the group.
  • name – The name of the group.
Returns:

An instance of a Group subclass.

get_identity(provider, identifier)

Retrieves user identity information from a provider.

This method is similar to refresh_identity() but does not require multiauth_data.

Parameters:identifier – The unique user identifier used by the provider.
Returns:An IdentityInfo instance or None if the identity does not exist.
handle_auth_error(exc, redirect_to_login=False)

Handles an authentication failure

Parameters:
  • exc – The exception indicating the error.
  • redirect_to_login – Returns a redirect response to the login page.
handle_auth_success(auth_info)

Called after a successful authentication

This method calls login_finished() with the found identity. If MULTIPASS_ALL_MATCHING_IDENTITIES is set, it will pass a list of identities. If MULTIPASS_REQUIRE_IDENTITY is set, IdentityRetrievalFailed will be raised if no identities were found, otherwise None or and empty list will be passed.

Parameters:auth_info – An AuthInfo instance containing data that can be used to retrieve the user’s unique identity.
Returns:A Flask response
handle_login_form(provider, data)

Handles the submitted and validated login form

This returns a response in case of a successful login. In case of an error, it is handled internally and the application should show the login form again.

Parameters:
  • provider – The provider used for logging in.
  • data – The form’s data dictionary.
Returns:

A flask response or None in case of an error.

identity_handler(callback)

Registers the callback function that receives identity information after a successful login.

If the callback returns a value, it is expected to be a valid return value for a Flask view function such as a redirect. In this case the target page should do whatever it needs to do (like showing an account creation form) and then use redirect_success() to redirect to the destination page.

See login_finished() for a description of the parameters.

identity_providers

Returns a read-only dict of the active identity providers

init_app(app)

Initialize the extension for a Flask application.

This is only necessary if the application was not provided in the constructor, e.g. because there is more than one application or you are using an application factory.

Parameters:app – The flask application
is_identity_in_group(provider, identity_identifier, group_name)

Checks if a user identity is in a group

Parameters:
  • provider – The name of the provider containing the group.
  • identity_identifier – The identifier of the user.
  • group_name – The name of the group.
login_check(callback)

Registers the callback function used to determine if the user is already logged in.

This is optional, but recommended, as it will avoid showing the login form to a user who is already logged in. When accessing the login page while being logged in, the user will be redirected to the same URL he’d be redirected to after a successful login.

login_finished(identity_info)

Called after the login process finished.

This method invokes the function registered via identity_handler with the same arguments.

Parameters:identity_info – An IdentityInfo instance or a list of them
logout(return_url, clear_session=False)

Performs a provider-specific logout.

This should be called by the application before. It returns a Flask response (usually a redirect) which must be returned from the view function calling this method so a provider can for example redirect to an external logout page.

Parameters:
  • return_url – The URL to redirect to after logging out. This is only used if the provider supports it.
  • clear_session – If true, the Flask session is cleared.
Returns:

A Flask respnse

process_login(provider=None)

Handles the login process

This should be registered in the Flask routing system and accept GET and POST requests on two URLs, one of them containing the <provider> placeholder. When executed with no provider, the login selector page will be shown unless there is only one provider available - in this case the page will immediately redirect to that provider.

Parameters:provider – The provider named used to log in.
provider_map

Returns a read-only mapping between auth and identity providers.

redirect_success()

Redirects to whatever page should be displayed after login

refresh_identity(identifier, multipass_data)

Retrieves user identity information for an existing identity

Parameters:
Returns:

An IdentityInfo instance or None if the identity does not exist anymore.

register_provider(cls, type_)

Registers a new provider type.

This can be used to register a new provider type in the application without having to go through the entry point system.

Parameters:
  • cls – The provider. Must be a subclass of either AuthProvider or IdentityProvider.
  • type – The type name of the provider used to reference it in the configuration.
render_template(template_key, **kwargs)

Renders a template configured in the app config

Parameters:
  • template_key – The template key to insert in the config option name MULTIPASS_*_TEMPLATE
  • kwargs – The variables passed to the template/
search_groups(name, providers=None, exact=False)

Searches groups by name

Parameters:
  • name – The name to search for.
  • providers – A list of providers to search in. If not specified, all providers are searched.
  • exact – If the name needs to match exactly, i.e. no substring matches are performed.
Returns:

An iterable of matching groups.

search_identities(providers=None, exact=False, **criteria)

Searches user identities matching certain criteria

Parameters:
  • providers – A list of providers to search in. If not specified, all providers are searched.
  • exact – If criteria need to match exactly, i.e. no substring matches are performed.
  • criteria – The criteria to search for. A criterion can have a list, tuple or set as value if there are many values for the same criterion.
Returns:

An iterable of matching user identities.

set_next_url()

Saves the URL to redirect to after logging in.

single_auth_provider

The auth provider in case there is only one.

This returns None if there are multiple auth providers.

Authentication Providers

class flask_multipass.auth.AuthProvider(multipass, name, settings)

Provides the base for an authentication provider.

Parameters:
  • multipass – The Flask-Multipass instance
  • name – The name of this auth provider instance
  • settings – The settings dictionary for this auth provider instance
initiate_external_login()

Initiates the login process for external authentication.

Called when the provider is selected and has no login form. This method usually redirects to an external login page.

Executing this method eventually needs to result in a call to Multipass.handle_auth_success() with an AuthInfo instance containing data that can be used by the identity provider to retrieve information for that user.

The most common way to achieve this is registering a new endpoint (decorated with login_view()) and passing the URL of that endpoint to the external provider so it redirects to it once the user authenticated with that provider.

Returns:A Flask Response, usually created by redirect()
is_external

True if the provider is external.

External providers do not have a login form and instead redirect to a third-party service to perform authentication.

login_form = None

If this auth provider requires the user to enter data using a form in your application, specify a Form here (usually containing a username/email and a password field).

multi_instance = True

If there may be multiple instances of this auth provider

process_local_login(data)

Handles the login process based on form data.

Only called if the login form validates successfully. This method needs to verify the form data actually contains valid credentials.

After successful authentication this method needs to call Multipass.handle_auth_success() with an AuthInfo instance containing data that can be used by the identity provider to retrieve information for that user.

Parameters:data – The form data (as returned by the data attribute of the login_form instance)
Returns:The return value of Multipass.handle_auth_success()
process_logout(return_url)

Handles logging out from the provider.

This is only necessary if logging out from the application needs to perform some provider-specific action such as sending a logout notification to the provider or redirecting to a SSO logout page.

If a value is returned, it’s eventually returned to Flask as a view function return value, so anything that’s valid there can be used. Most likely you want to use redirect() to redirect to an external logout page though.

When redirecting to an external site, you should pass along the return_url if the external provider allows you to specify a URL to redirect to after logging out.

Parameters:return_url – The URL to redirect to after logging our.
Returns:None or a Flask response.
class flask_multipass.providers.ldap.LDAPAuthProvider(*args, **kwargs)

Provides authentication using LDAP

The type name to instantiate this provider is ldap.

login_form

alias of LoginForm

process_local_login(data)

Handles the login process based on form data.

Only called if the login form validates successfully. This method needs to verify the form data actually contains valid credentials.

After successful authentication this method needs to call Multipass.handle_auth_success() with an AuthInfo instance containing data that can be used by the identity provider to retrieve information for that user.

Parameters:data – The form data (as returned by the data attribute of the login_form instance)
Returns:The return value of Multipass.handle_auth_success()
class flask_multipass.providers.oauth.OAuthAuthProvider(*args, **kwargs)

Provides authentication using OAuth

The type name to instantiate this provider is oauth.

initiate_external_login()

Initiates the login process for external authentication.

Called when the provider is selected and has no login form. This method usually redirects to an external login page.

Executing this method eventually needs to result in a call to Multipass.handle_auth_success() with an AuthInfo instance containing data that can be used by the identity provider to retrieve information for that user.

The most common way to achieve this is registering a new endpoint (decorated with login_view()) and passing the URL of that endpoint to the external provider so it redirects to it once the user authenticated with that provider.

Returns:A Flask Response, usually created by redirect()
class flask_multipass.providers.static.StaticAuthProvider(*args, **kwargs)

Provides authentication against a static list

This provider should NEVER be use in any production system. It serves mainly as a simple dummy/example for development.

The type name to instantiate this provider is static.

login_form

alias of StaticLoginForm

process_local_login(data)

Handles the login process based on form data.

Only called if the login form validates successfully. This method needs to verify the form data actually contains valid credentials.

After successful authentication this method needs to call Multipass.handle_auth_success() with an AuthInfo instance containing data that can be used by the identity provider to retrieve information for that user.

Parameters:data – The form data (as returned by the data attribute of the login_form instance)
Returns:The return value of Multipass.handle_auth_success()
class flask_multipass.providers.shibboleth.ShibbolethAuthProvider(*args, **kwargs)

Provides authentication using Shibboleth.

This provider requires the application to run inside the Apache webserver with mod_shib.

The type name to instantiate this provider is shibboleth.

initiate_external_login()

Initiates the login process for external authentication.

Called when the provider is selected and has no login form. This method usually redirects to an external login page.

Executing this method eventually needs to result in a call to Multipass.handle_auth_success() with an AuthInfo instance containing data that can be used by the identity provider to retrieve information for that user.

The most common way to achieve this is registering a new endpoint (decorated with login_view()) and passing the URL of that endpoint to the external provider so it redirects to it once the user authenticated with that provider.

Returns:A Flask Response, usually created by redirect()
process_logout(return_url)

Handles logging out from the provider.

This is only necessary if logging out from the application needs to perform some provider-specific action such as sending a logout notification to the provider or redirecting to a SSO logout page.

If a value is returned, it’s eventually returned to Flask as a view function return value, so anything that’s valid there can be used. Most likely you want to use redirect() to redirect to an external logout page though.

When redirecting to an external site, you should pass along the return_url if the external provider allows you to specify a URL to redirect to after logging out.

Parameters:return_url – The URL to redirect to after logging our.
Returns:None or a Flask response.
class flask_multipass.providers.sqlalchemy.SQLAlchemyAuthProviderBase(multipass, name, settings)

Provides authentication against passwords stored in SQLAlchemy

This provider expects your application to have an “identity” model which maps identifiers from IdentityInfo objects to users. For further details on how to use this provider, please see the example application.

To use it, you have to subclass it in your application.

check_password(identity, password)

Checks the entered password

Parameters:
  • identity – An instance of identity_model.
  • password – The password entered by the user.
identifier_column = None

The column of the identity model that contains the identifier, i.e. the username. This needs to be a SQLAlchemy column object, e.g. Identity.identifier

identity_model = None

The Flask-SQLAlchemy model representing a user identity

login_form

The Form that is used for the login dialog

alias of LoginForm

process_local_login(data)

Handles the login process based on form data.

Only called if the login form validates successfully. This method needs to verify the form data actually contains valid credentials.

After successful authentication this method needs to call Multipass.handle_auth_success() with an AuthInfo instance containing data that can be used by the identity provider to retrieve information for that user.

Parameters:data – The form data (as returned by the data attribute of the login_form instance)
Returns:The return value of Multipass.handle_auth_success()
provider_column = None

The column of the identity model that contains the provider name. This needs to be a SQLAlchemy column object, e.g. Identity.provider

Identity Providers

class flask_multipass.identity.IdentityProvider(multipass, name, settings)

Provides the base for an identity provider.

Parameters:
  • multipass – The Flask-Multipass instance
  • name – The name of this identity provider instance
  • settings – The settings dictionary for this identity provider instance
get_group(name)

Returns a specific group

Parameters:name – The name of the group
Returns:An instance of group_class
get_identity(identifier)

Retrieves identity information.

This method is similar to refresh_identity() but does not require multiauth_data

Parameters:identifier – The unique user identifier used by the provider.
Returns:An IdentityInfo instance or None if the identity does not exist.
get_identity_from_auth(auth_info)

Retrieves identity information after authentication

Parameters:auth_info – An AuthInfo instance from an auth provider
Returns:An IdentityInfo instance containing identity information or None if no identity was found
get_identity_groups(identifier)

Retrieves the list of groups a user identity belongs to

Parameters:identifier – The unique user identifier used by the provider.
Returns:A set of groups
group_class = None

The class that represents groups from this provider. Must be a subclass of Group

map_search_criteria(criteria)

Maps the search criteria from application keys to provider keys

Parameters:criteria – A dict containing search criteria
Returns:A dict containing search criteria with mapped keys
multi_instance = True

If there may be multiple instances of this identity provider

refresh_identity(identifier, multipass_data)

Retrieves identity information for an existing user identity

This method returns identity information for an identity that has been retrieved before based on the provider-specific refresh data.

Parameters:
search_groups(name, exact=False)

Searches groups by name

Parameters:
  • name – The name to search for
  • exact – If the name needs to match exactly, i.e. no substring matches are performed
Returns:

An iterable of matching group_class objects

search_identities(criteria, exact=False)

Searches user identities matching certain criteria

Parameters:
  • criteria – A dict containing the criteria to search for.
  • exact – If criteria need to match exactly, i.e. no substring matches are performed.
Returns:

An iterable of matching identities.

supports_get = True

If the provider supports getting identity information based from an identifier

supports_get_identity_groups = False

If the provider supports getting the list of groups an identity belongs to

supports_groups = False

If the provider also provides groups and membership information

supports_refresh = False

If the provider supports refreshing identity information

If the provider supports searching identities

class flask_multipass.providers.ldap.LDAPIdentityProvider(*args, **kwargs)

Provides identity information using LDAP.

get_group(name)

Returns a specific group

Parameters:name – The name of the group
Returns:An instance of group_class
get_identity(identifier)

Retrieves identity information.

This method is similar to refresh_identity() but does not require multiauth_data

Parameters:identifier – The unique user identifier used by the provider.
Returns:An IdentityInfo instance or None if the identity does not exist.
get_identity_from_auth(auth_info)

Retrieves identity information after authentication

Parameters:auth_info – An AuthInfo instance from an auth provider
Returns:An IdentityInfo instance containing identity information or None if no identity was found
get_identity_groups(identifier)

Retrieves the list of groups a user identity belongs to

Parameters:identifier – The unique user identifier used by the provider.
Returns:A set of groups
group_class

The class that represents groups from this provider

alias of LDAPGroup

refresh_identity(identifier, multipass_data)

Retrieves identity information for an existing user identity

This method returns identity information for an identity that has been retrieved before based on the provider-specific refresh data.

Parameters:
search_groups(name, exact=False)

Searches groups by name

Parameters:
  • name – The name to search for
  • exact – If the name needs to match exactly, i.e. no substring matches are performed
Returns:

An iterable of matching group_class objects

search_identities(criteria, exact=False)

Searches user identities matching certain criteria

Parameters:
  • criteria – A dict containing the criteria to search for.
  • exact – If criteria need to match exactly, i.e. no substring matches are performed.
Returns:

An iterable of matching identities.

supports_get_identity_groups

bool(x) -> bool

Returns True when the argument x is true, False otherwise. The builtins True and False are the only two instances of the class bool. The class bool is a subclass of the class int, and cannot be subclassed.

supports_groups = True

If the provider also provides groups and membership information

supports_refresh = True

If the provider supports refreshing user information

If the provider supports searching users

class flask_multipass.providers.oauth.OAuthIdentityProvider(*args, **kwargs)

Provides identity information using OAuth.

The remote service needs to provide identity information as JSON. The type name to instantiate this provider is oauth.

get_identity_from_auth(auth_info)

Retrieves identity information after authentication

Parameters:auth_info – An AuthInfo instance from an auth provider
Returns:An IdentityInfo instance containing identity information or None if no identity was found
refresh_identity(identifier, multipass_data)

Retrieves identity information for an existing user identity

This method returns identity information for an identity that has been retrieved before based on the provider-specific refresh data.

Parameters:
supports_get = False

If the provider supports getting identity information based from an identifier

supports_refresh = True

If the provider supports refreshing identity information

class flask_multipass.providers.static.StaticIdentityProvider(*args, **kwargs)

Provides identity information from a static list.

This provider should NEVER be use in any production system. It serves mainly as a simple dummy/example for development.

The type name to instantiate this provider is static.

get_group(name)

Returns a specific group

Parameters:name – The name of the group
Returns:An instance of group_class
get_identity(identifier)

Retrieves identity information.

This method is similar to refresh_identity() but does not require multiauth_data

Parameters:identifier – The unique user identifier used by the provider.
Returns:An IdentityInfo instance or None if the identity does not exist.
get_identity_from_auth(auth_info)

Retrieves identity information after authentication

Parameters:auth_info – An AuthInfo instance from an auth provider
Returns:An IdentityInfo instance containing identity information or None if no identity was found
get_identity_groups(identifier)

Retrieves the list of groups a user identity belongs to

Parameters:identifier – The unique user identifier used by the provider.
Returns:A set of groups
group_class

The class that represents groups from this provider

alias of StaticGroup

refresh_identity(identifier, multipass_data)

Retrieves identity information for an existing user identity

This method returns identity information for an identity that has been retrieved before based on the provider-specific refresh data.

Parameters:
search_groups(name, exact=False)

Searches groups by name

Parameters:
  • name – The name to search for
  • exact – If the name needs to match exactly, i.e. no substring matches are performed
Returns:

An iterable of matching group_class objects

search_identities(criteria, exact=False)

Searches user identities matching certain criteria

Parameters:
  • criteria – A dict containing the criteria to search for.
  • exact – If criteria need to match exactly, i.e. no substring matches are performed.
Returns:

An iterable of matching identities.

supports_get_identity_groups = True

If the provider supports getting the list of groups an identity belongs to

supports_groups = True

If the provider also provides groups and membership information

supports_refresh = True

If the provider supports refreshing user information

If the provider supports searching identities

class flask_multipass.providers.shibboleth.ShibbolethIdentityProvider(*args, **kwargs)

Provides identity information using Shibboleth

This provider requires the application to run inside the Apache webserver with mod_shib.

The type name to instantiate this provider is shibboleth.

get_identity_from_auth(auth_info)

Retrieves identity information after authentication

Parameters:auth_info – An AuthInfo instance from an auth provider
Returns:An IdentityInfo instance containing identity information or None if no identity was found
supports_get = False

If the provider supports getting identity information based from an identifier

class flask_multipass.providers.sqlalchemy.SQLAlchemyIdentityProviderBase(multipass, name, settings)

Provides identity information for users stored in SQLAlchemy

This provider expects your application to have an “identity” model which maps identifiers from IdentityInfo objects to users. For further details on how to use this provider, please see the example application.

The provider returns all columns from the user model; use the configurable mapping to restrict the data returned.

To use it, you have to subclass it in your application.

get_identity_from_auth(auth_info)

Retrieves identity information after authentication

Parameters:auth_info – An AuthInfo instance from an auth provider
Returns:An IdentityInfo instance containing identity information or None if no identity was found
identity_user_relationship = None

The relationship of the identity model that points to the associated user object. This can be either a SQLAlchemy relationship object such as Identity.user or a string containing the attribute name of the relationship.

supports_get = False

Getting an identity based on the identifier does not make lots of sense for identities coming from the local database.

user_model = None

The Flask-SQLAlchemy model representing a user.

Data Structures

class flask_multipass.data.AuthInfo(provider, **data)

Stores data from an authentication provider.

Parameters:
  • provider – The authentication provider instance providing the data.
  • data – Any data the authentication provider wants to pass on to identity providers. This data must allow any connected identity provider to uniquely identify a user.
map(mapping)

Creates a new instance with transformed data keys

Parameters:mapping – The dict mapping the current data keys to the the keys that are expected by the identity provider. Any key that is not in mapping is kept as-is.
class flask_multipass.data.IdentityInfo(provider, identifier, multipass_data=None, **data)

Stores user identity information for the application.

Parameters:
  • provider – The identity provider instance providing the data.
  • identifier – A unique identifier string that can later be used to retrieve identity information for the same user.
  • multipass_data – A dict containing additional data the identity provider needs e.g. to refresh the identity information for the same user, without him authenticating again by keeping a long-lived token.
  • data – Any data the identity provider wants to pass on the application.

Groups

class flask_multipass.group.Group(provider, name)

Base class for groups

Parameters:
  • provider – The identity provider managing the group.
  • name – The unique name of the group.
get_members()

Returns the members of the group.

This can also be performed by iterating over the group. If the group does not support listing members, NotImplementedError is raised.

Returns:An iterable of IdentityInfo objects.
has_member(identifier)

Checks if a given identity is a member of the group.

This check can also be performed using the in operator.

Parameters:identifier – The identifier from an IdentityInfo provided by the associated identity provider.
supports_member_list = False

If it is possible to get the list of members of a group.

Utils

class flask_multipass.util.SupportsMeta

Metaclass that requires/prohibits methods to be overridden depending on class attributes.

The class using this metaclass must have a __support_attrs__ attribute containing a dict mapping attribute names to method names (or lists of method names) which must be overridden if the attribute is True and may not mbe overridden if it isn’t.

Instead of a string key the dict may also contain a tuple returned from callable().

static callable(func, message)

Returns an object suitable for more complex

Parameters:
  • func – A callable that is invoked with the dict of the newly created object
  • message – The message to show in case of a failure.
flask_multipass.util.convert_app_data(app_data, mapping, key_filter=None)

Converts data coming from the application to be used by the provider.

Parameters:
  • app_data – dict – Data coming from the application.
  • mapping – dict – Mapping between keys used to define the data in the application and those used by the provider.
  • key_filter – list – Keys to be exclusively considered. If None, all items will be returned.
Returns:

dict – containing the values of app_data mapped to the keys of the provider as defined in the mapping and filtered out by key_filter.

flask_multipass.util.convert_provider_data(provider_data, mapping, key_filter=None)

Converts data coming from the provider to be used by the application

The result will have all the keys listed in keys with values coming either from data (using the key mapping defined in mapping) or None in case the key is not present. If key_filter is None, all keys from provider_data will be used unless they are mapped to a different key in mapping.

Parameters:
  • provider_data – dict – Data coming from the provider.
  • mapping – dict – Mapping between keys used to define the data in the provider and those used by the application. All application keys will be present in the return value, defaulting to None.
  • key_filter – list – Keys to be exclusively considered. If None, all items will be returned. Keys not present in the mapped data, will have a value of None.
Returns:

dict – containing the values of app_data mapped to the keys of the application as defined in the mapping and filtered out by key_filter.

flask_multipass.util.get_canonical_provider_map(provider_map)

Converts the configured provider map to a canonical form

flask_multipass.util.get_provider_base(cls)

Returns the base class of a provider class.

Parameters:cls – A subclass of either AuthProvider or IdentityProvider.
Returns:AuthProvider or IdentityProvider
flask_multipass.util.login_view(func)

Decorates a Flask view function as an authentication view.

This catches multipass-related exceptions and flashes a message and redirects back to the login page.

flask_multipass.util.resolve_provider_type(base, type_, registry=None)

Resolves a provider type to its class

Parameters:
  • base – The base class of the provider
  • type – The type of the provider. Can be a subclass of base or the identifier of a registered type.
  • registry – A dict containing registered providers. This complements the entrypoint-based lookup. Any provider type defined in this dict takes priority over an entrypoint-based one with the same name.
Returns:

The type’s class, which is a subclass of base.

Exceptions

exception flask_multipass.exceptions.AuthenticationFailed(message=None, details=None, provider=None)

Indicates an authentication failure that was caused by the user, e.g. by entering the wrong credentials or not authorizing the application

exception flask_multipass.exceptions.GroupRetrievalFailed(message=None, details=None, provider=None)

Indicates a failure while retrieving group information

exception flask_multipass.exceptions.IdentityRetrievalFailed(message=None, details=None, provider=None)

Indicates a failure while retrieving identity information

exception flask_multipass.exceptions.InvalidCredentials(details=None, provider=None)

Indicates a failure to authenticate using the given credentials.

exception flask_multipass.exceptions.MultipassException(message=None, details=None, provider=None)

Base class for Multipass exceptions

exception flask_multipass.exceptions.NoSuchUser(details=None, provider=None)

Indicates a user does not exist when attempting to authenticate.