geofront.team — Team authentication

Geofront doesn’t force you to manage team members by yourself. Instead it hides how to manage team members, and offers Team, the layering interface to implement custom team data provider e.g. GitHubOrganization.

It is theologically possible to implement a straightforward RDBMS-backed team provider, but we rather recommend to adapt your existing team data instead e.g. GitHub organization, Google Apps organization, Bitbucket team.

class geofront.team.AuthenticationContinuation(next_url: str, state) → None

The continuation value for the process between Team.request_authentication() and Team.authenticate().

It is created by Team.request_authentication() method, and holds following two attributes:

next_url

(str) The url to direct the authenticator to.

state

The arbitrary value to be passed to Team.authenticate() method’s state parameter.

It can be used for passing arbitrary nonce, or request token, etc.

It has to be possible to pickle.

New in version 0.3.0.

exception geofront.team.AuthenticationError

Authentication exception which rise when the authentication process has trouble including network problems.

geofront.team.GroupSet

The type to represent a set of groups. Group sets consist of group identifiers. Group identifiers are usually a string, but can be anything hashable.

Alias of AbstractSet[Hashable].

New in version 0.4.0.

alias of AbstractSet

class geofront.team.Team

Backend interface for team membership authentication.

Authorization process consists of three steps (and therefore every backend subclass has to implement these three methods):

  1. request_authentication() makes the url to interact with the owner of the identity to authenticate. I.e. the url to login web page of the backend service.
  2. authenticate() finalize authentication of the identity, and then returns Identity.
  3. authorize() tests the given Identity belongs to the team. It might be a redundant step for several backends, but is a necessary step for some backends that distinguish identity authentication between team membership authorization. For example, Any Gmail users can authenticate they own their Gmail account, but only particular users can authenticate their account belongs to the configured Google Apps organization.
authenticate(state, requested_redirect_url: str, wsgi_environ: typing.Mapping[str, object]) → geofront.identity.Identity

Second step of authentication process, to create a verification token for the identity. The token is used by authorize() method, and the key store as well (if available).

Parameters:
Returns:

an identity which contains a verification token

Return type:

Identity

Raises:

geofront.team.AuthenticationError – when something goes wrong e.g. network errors, the user failed to verify their ownership

Changed in version 0.3.0: The auth_nonce parameter was replaced by more general state parameter. The new parameter has no longer type constraints so that it can be any value even if it’s not a str.

authorize(identity: geofront.identity.Identity) → bool

The last step of authentication process. Test whether the given identity belongs to the team.

Note that it can be called every time the owner communicates with Geofront server, out of authentication process.

Parameters:identity (Identity) – the identity to authorize
Returns:True only if the identity is a member of the team
Return type:bool
list_groups(identity: geofront.identity.Identity) → typing.AbstractSet[collections.abc.Hashable]

List the all groups that the given identity belongs to. Any hashable value can be an element to represent a group e.g.:

{1, 4, 9}

Or:

{'owners', 'programmers'}

Whatever value the set consists of these would be referred by Remote objects.

Some team implementations might not have a concept like groups. It’s okay to return always an empty set then.

Parameters:identity (Identity) – the identity to list his/her groups
Returns:the set of groups associated with the identity
Return type:GroupSet

New in version 0.2.0.

request_authentication(redirect_url: str) → geofront.team.AuthenticationContinuation

First step of authentication process, to prepare the “sign in” interaction with the owner. It typically returns a url to the login web page.

Parameters:redirect_url (str) – a url that owner’s browser has to redirect to after the “sign in” interaction finishes
Returns:a url to the web page to interact with the owner in their browser
Return type:AuthenticationContinuation

Changed in version 0.3.0: The auth_nonce parameter was removed. Instead, it became to return AuthenticationContinuation value so that share state more general than simple auth_nonce between request_authentication() and authenticate(). If arbitrary nonce is needed, request_authentication() method has to generate one by itself.