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.
- property 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 orNone
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. IfMULTIPASS_ALL_MATCHING_IDENTITIES
is set, it will pass a list of identities. IfMULTIPASS_REQUIRE_IDENTITY
is set,IdentityRetrievalFailed
will be raised if no identities were found, otherwiseNone
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.
- property 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.
- property 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:
identifier – The identifier from
IdentityInfo
multipass_data – The multipass_data dict from
IdentityInfo
- Returns:
An
IdentityInfo
instance orNone
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
orIdentityProvider
.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.
- search_identities_ex(providers=None, exact=False, limit=None, criteria=None)¶
Search user identities matching search criteria.
This is very similar to
search_identities()
, but instead of just yielding identities, it allows specifying a limit and only returns up to that number of identities per provider. It also returns the total number of found identities so the application can decide to inform the user that their search criteria may be too broad.- Returns:
A tuple containing
(identities, total_count)
.
- set_next_url()¶
Saves the URL to redirect to after logging in.
- property single_auth_provider¶
The auth provider in case there is only one.
This returns
None
if there are multiple auth providers.
- validate_next_url(url)¶
Make sure the next URL is an allowed redirect target.
The default logic is to accept relative URL and URLs with the same host as the one serving the current request.
If you override this and want to allow more hosts, make sure to use a whitelist of trusted hosts to avoid creating an open redirector.
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 anAuthInfo
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 byredirect()
- property 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 anAuthInfo
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 anAuthInfo
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.authlib.AuthlibAuthProvider(*args, **kwargs)¶
Provide authentication using Authlib (OAuth/OIDC).
The type name to instantiate this provider is
authlib
.The following settings are supported:
callback_uri
: the relative uri used after a successful oauth login.defaults to
/multipass/authlib/<name>
, but you can change it e.g. if your oauth/oidc infrastructure requires a specific callback uri and you do not want to rely on the default one.
include_token
: when set toTrue
, the AuthInfo passed to theidentity provider includes the
token
containing the raw token data received from oauth. this is useful when connecting this auth provider to a custom identity provider that needs to do more than just calling the userinfo endpoint. when set to ‘only’, the AuthInfo will only contain the token, and no other data will be retrieved from the id token or userinfo endpoint.
use_id_token
: specify whether to use the OIDC id token instead ofcalling the userinfo endpoint. if unspecified or None, it will default to true when the
openid
scope is enabled (which indicates that OIDC is being used)
authlib_args
: a dict of params forwarded to authlib. see the argumentsof
register()
in the authlib docs for details.
- 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 anAuthInfo
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 byredirect()
- 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.saml.SAMLAuthProvider(*args, **kwargs)¶
Provides authentication using SAML.
The type name to instantiate this provider is saml.
- 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 anAuthInfo
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 byredirect()
- 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.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 anAuthInfo
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 anAuthInfo
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 byredirect()
- 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 dialogalias 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 anAuthInfo
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 orNone
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 orNone
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:
identifier – The identifier from
IdentityInfo
multipass_data – The multipass_data dict from
IdentityInfo
- 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.
- search_identities_ex(criteria, exact=False, limit=None)¶
Search 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.
limit – The max number of identities to return.
- Returns:
A tuple containing
(identities, total_count)
.
- 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
- supports_search = False¶
If the provider supports searching identities
- supports_search_ex = False¶
If the provider supports the extended identity search feature
- 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 orNone
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 orNone
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¶
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:
identifier – The identifier from
IdentityInfo
multipass_data – The multipass_data dict from
IdentityInfo
- 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.
- property 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
- supports_search = True¶
If the provider supports searching users
- class flask_multipass.providers.authlib.AuthlibIdentityProvider(*args, **kwargs)¶
Provides identity information using Authlib.
This provides access to all data returned by userinfo endpoint or id token. The type name to instantiate this provider is
authlib
.- 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 orNone
if no identity was found
- supports_get = False¶
If the provider supports getting identity information based from an identifier
- supports_refresh = False¶
If the provider supports refreshing identity information
- class flask_multipass.providers.saml.SAMLIdentityProvider(*args, **kwargs)¶
Provides identity information using SAML.
The type name to instantiate this provider is saml.
- 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 orNone
if no identity was found
- supports_get = False¶
If the provider supports getting identity information based from an identifier
- 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 orNone
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 orNone
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:
identifier – The identifier from
IdentityInfo
multipass_data – The multipass_data dict from
IdentityInfo
- 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
- supports_search = True¶
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 orNone
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 orNone
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, secure_login=None, **data)¶
Stores data from an authentication provider.
- Parameters:
provider – The authentication provider instance providing the data.
secure_login – A bool indicating whether the login was secure, with the interpretation of “secure” being up to the application and auth provider, but generally this is meant to be set if multiple factors have been used. Must be left as
None
in case no information about how secure the login was i available.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, secure_login=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.
secure_login – A bool indicating whether the login was secure, with the interpretation of “secure” being up to the application and auth provider, but generally this is meant to be set if multiple factors have been used. Must be left as
None
in case the object has not been created during a login process or if no information about how secure the login was is available.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 iterator 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(name, bases, dct)¶
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 isNone
, 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 ofNone
.
- 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
orIdentityProvider
.- Returns:
- 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.