Reference¶

This reference details the data models used by Canaille. This is mostly useful for developers.

class canaille.backends.models.BackendModel[source]¶

Bases: object

The backend model abstract class.

It details all the methods and attributes that are expected to be implemented for every model and for every backend.

delete()[source]¶: Removes the current instance from the database.

classmethod fuzzy(query, attributes=None, **kwargs)[source]¶: Works like query() but attribute values loosely be matched.

classmethod get(identifier=None, **kwargs)[source]¶: Works like query() but return only one element or None if no item is matching.

classmethod get_model_annotations(attribute)[source]¶

property identifier¶

Returns a unique value that will be used to identify the model instance.

This value will be used in URLs in canaille, so it should be unique and short.

match_filter(filter)[source]¶

classmethod query(**kwargs)[source]¶

Performs a query on the database and return a collection of instances. Parameters can be any valid attribute with the expected value:

>>> User.query(first_name="George")

If several arguments are passed, the methods only returns the model instances that return matches all the argument values:

>>> User.query(first_name="George", last_name="Abitbol")

If the argument value is a collection, the methods will return the models that matches any of the values:

>>> User.query(first_name=["George", "Jane"])

reload()[source]¶

Cancels the unsaved modifications.

>>> user = User.get(user_name="george")
>>> user.display_name
George
>>> user.display_name = "Jane"
>>> user.display_name
Jane
>>> user.reload()
>>> user.display_name
George

save()[source]¶: Validates the current modifications in the database.

update(**kwargs)[source]¶

Assign a whole dict to the current instance. This is useful to update models based on forms.

>>> user = User.get(user_name="george")
>>> user.first_name
George
>>> user.update({
...     first_name="Jane",
...     last_name="Calamity",
... })
>>> user.first_name
Jane

class canaille.backends.models.Model[source]¶

Bases: object

The model abstract class.

It details all the common attributes shared by every models.

attributes = {'created': typing.Optional[datetime.datetime], 'id': typing.Optional[str], 'last_modified': typing.Optional[datetime.datetime]}¶

created: datetime | None = None¶: The datetime that the resource was added to the service provider.

id: str | None = None¶

A unique identifier for a SCIM resource as defined by the service provider. Id will be None until the save() method is called.

Each representation of the resource MUST include a non-empty “id” value. This identifier MUST be unique across the SCIM service provider’s entire set of resources. It MUST be a stable, non- reassignable identifier that does not change when the same resource is returned in subsequent requests. The value of the “id” attribute is always issued by the service provider and MUST NOT be specified by the client. The string “bulkId” is a reserved keyword and MUST NOT be used within any unique identifier value. The attribute characteristics are “caseExact” as “true”, a mutability of “readOnly”, and a “returned” characteristic of “always”. See Section 9 for additional considerations regarding privacy.

last_modified: datetime | None = None¶

The most recent datetime that the details of this resource were updated at the service provider.

If this resource has never been modified since its initial creation, the value MUST be the same as the value of created.

class canaille.core.models.Group[source]¶

Bases: Model

User model, based on the SCIM Group schema.

description: str | None = None¶

display_name: str¶

A human-readable name for the Group.

REQUIRED.

members: List[User] = []¶

A list of members of the Group.

While values MAY be added or removed, sub-attributes of members are “immutable”. The “value” sub-attribute contains the value of an “id” attribute of a SCIM resource, and the “$ref” sub-attribute must be the URI of a SCIM resource such as a “User”, or a “Group”. The intention of the “Group” type is to allow the service provider to support nested groups. Service providers MAY require clients to provide a non-empty value by setting the “required” attribute characteristic of a sub-attribute of the “members” attribute in the “Group” resource schema.

class canaille.core.models.User[source]¶

Bases: Model

User model, based on the SCIM User schema, Entreprise User Schema Extension and SCIM Password Management Extension draft. Attribute description is based on SCIM and put there for information purpose. The description may not fit the current implementation in Canaille.

can(*permissions: Permission)[source]¶: Wether or not the user has the Permission according to the configuration.

can_read(field: str)[source]¶

department: str | None = None¶: Identifies the name of a department.

display_name: str | None = None¶

The name of the user, suitable for display to end-users.

Each user returned MAY include a non-empty displayName value. The name SHOULD be the full name of the User being described, if known (e.g., “Babs Jensen” or “Ms. Barbara J Jensen, III”) but MAY be a username or handle, if that is all that is available (e.g., “bjensen”). The value provided SHOULD be the primary textual label by which this User is normally displayed by the service provider when presenting it to end-users.

emails: List[str] = []¶

Email addresses for the User.

The value SHOULD be specified according to [RFC5321]. Service providers SHOULD canonicalize the value according to [RFC5321], e.g., “bjensen@example.com” instead of “bjensen@EXAMPLE.COM”. The “display” sub-attribute MAY be used to return the canonicalized representation of the email value. The “type” sub-attribute is used to provide a classification meaningful to the (human) user. The user interface should encourage the use of basic values of “work”, “home”, and “other” and MAY allow additional type values to be used at the discretion of SCIM clients.

employee_number: str | None = None¶: A string identifier, typically numeric or alphanumeric, assigned to a person, typically based on order of hire or association with an organization.

family_name: str | None = None¶: The family name of the User, or last name in most Western languages (e.g., “Jensen” given the full name “Ms. Barbara Jane Jensen, III”).

formatted_address: str | None = None¶

The full mailing address, formatted for display or use with a mailing label.

This attribute MAY contain newlines.

formatted_name: str | None = None¶: The full name, including all middle names, titles, and suffixes as appropriate, formatted for display (e.g., “Ms. Barbara Jane Jensen, III”).

given_name: str | None = None¶: The given name of the User, or first name in most Western languages (e.g., “Barbara” given the full name “Ms. Barbara Jane Jensen, III”).

groups: List[Group] = []¶

A list of groups to which the user belongs, either through direct membership, through nested groups, or dynamically calculated.

The values are meant to enable expression of common group-based or role-based access control models, although no explicit authorization model is defined. It is intended that the semantics of group membership and any behavior or authorization granted as a result of membership are defined by the service provider. The canonical types “direct” and “indirect” are defined to describe how the group membership was derived. Direct group membership indicates that the user is directly associated with the group and SHOULD indicate that clients may modify membership through the “Group” resource. Indirect membership indicates that user membership is transitive or dynamic and implies that clients cannot modify indirect group membership through the “Group” resource but MAY modify direct group membership through the “Group” resource, which may influence indirect memberships. If the SCIM service provider exposes a “Group” resource, the “value” sub-attribute MUST be the “id”, and the “$ref” sub-attribute must be the URI of the corresponding “Group” resources to which the user belongs. Since this attribute has a mutability of “readOnly”, group membership changes MUST be applied via the “Group” Resource (Section 4.2). This attribute has a mutability of “readOnly”.

has_password() → bool[source]¶: Checks wether a password has been set for the user.

load_permissions()[source]¶

locality: str | None = None¶: The city or locality component.

lock_date: datetime | None = None¶: A DateTime indicating when the resource was locked.

property locked: bool¶: Wether the user account has been locked or has expired.

organization: str | None = None¶: Identifies the name of an organization.

password: str | None = None¶

This attribute is intended to be used as a means to set, replace, or compare (i.e., filter for equality) a password. The cleartext value or the hashed value of a password SHALL NOT be returnable by a service provider. If a service provider holds the value locally, the value SHOULD be hashed. When a password is set or changed by the client, the cleartext password SHOULD be processed by the service provider as follows:

Prepare the cleartext value for international language comparison. See Section 7.8 of [RFC7644].
Validate the value against server password policy. Note: The definition and enforcement of password policy are beyond the scope of this document.
Ensure that the value is encrypted (e.g., hashed). See Section 9.2 for acceptable hashing and encryption handling when storing or persisting for provisioning workflow reasons.

A service provider that immediately passes the cleartext value on to another system or programming interface MUST pass the value directly over a secured connection (e.g., Transport Layer Security (TLS)). If the value needs to be temporarily persisted for a period of time (e.g., because of a workflow) before provisioning, then the value MUST be protected by some method, such as encryption.

Testing for an equality match MAY be supported if there is an existing stored hashed value. When testing for equality, the service provider:

Prepares the filter value for international language comparison. See Section 7.8 of [RFC7644].
Generates the salted hash of the filter value and tests for a match with the locally held value.

The mutability of the password attribute is “writeOnly”, indicating that the value MUST NOT be returned by a service provider in any form (the attribute characteristic “returned” is “never”).

phone_numbers: List[str] = []¶

Phone numbers for the user.

The value SHOULD be specified according to the format defined in [RFC3966], e.g., ‘tel:+1-201-555-0123’. Service providers SHOULD canonicalize the value according to [RFC3966] format, when appropriate. The “display” sub-attribute MAY be used to return the canonicalized representation of the phone number value. The sub- attribute “type” often has typical values of “work”, “home”, “mobile”, “fax”, “pager”, and “other” and MAY allow more types to be defined by the SCIM clients.

photo: str | None = None¶

A URI that is a uniform resource locator (as defined in Section 1.1.3 of [RFC3986]) that points to a resource location representing the user’s image.

The resource MUST be a file (e.g., a GIF, JPEG, or PNG image file) rather than a web page containing an image. Service providers MAY return the same image in different sizes, although it is recognized that no standard for describing images of various sizes currently exists. Note that this attribute SHOULD NOT be used to send down arbitrary photos taken by this user; instead, profile photos of the user that are suitable for display when describing the user should be sent. Instead of the standard canonical values for type, this attribute defines the following canonical values to represent popular photo sizes: “photo” and “thumbnail”.

postal_code: str | None = None¶: The zip code or postal code component.

property preferred_email¶

preferred_language: str | None = None¶

Indicates the user’s preferred written or spoken languages and is generally used for selecting a localized user interface.

The value indicates the set of natural languages that are preferred. The format of the value is the same as the HTTP Accept-Language header field (not including “Accept-Language:”) and is specified in Section 5.3.5 of [RFC7231]. The intent of this value is to enable cloud applications to perform matching of language tags [RFC4647] to the user’s language preferences, regardless of what may be indicated by a user agent (which might be shared), or in an interaction that does not involve a user (such as in a delegated OAuth 2.0 [RFC6749] style interaction) where normal HTTP Accept-Language header negotiation cannot take place.

profile_url: str | None = None¶

A URI that is a uniform resource locator (as defined in Section 1.1.3 of [RFC3986]) and that points to a location representing the user’s online profile (e.g., a web page).

URIs are canonicalized per Section 6.2 of [RFC3986].

property readable_fields¶

The fields the user can read according to the configuration configuration.

This does not include the writable fields.

region: str | None = None¶: The state or region component.

reload()[source]¶

street: str | None = None¶

The full street address component, which may include house number, street name, P.O.

box, and multi-line extended street address information. This attribute MAY contain newlines.

title: str | None = None¶: The user’s title, such as “Vice President”.

user_name: str¶

A service provider’s unique identifier for the user, typically used by the user to directly authenticate to the service provider.

Often displayed to the user as their unique identifier within the system (as opposed to “id” or “externalId”, which are generally opaque and not user-friendly identifiers). Each User MUST include a non-empty userName value. This identifier MUST be unique across the service provider’s entire set of Users. This attribute is REQUIRED and is case insensitive.

property writable_fields¶: The fields the user can write according to the configuration.

class canaille.oidc.basemodels.AuthorizationCode[source]¶

Bases: Model

OpenID Connect temporary authorization code definition.

authorization_code_id: str¶

challenge: str | None¶

challenge_method: str | None¶

client: Client¶

code: str¶

issue_date: datetime¶

lifetime: int¶

nonce: str | None¶

redirect_uri: str | None¶

response_type: str | None¶

revokation_date: datetime¶

scope: List[str]¶

subject: User¶

class canaille.oidc.basemodels.Client[source]¶

Bases: Model

OpenID Connect client definition, based on the OAuth 2.0 Dynamic Client Registration protocols and the OpenID Connect RP-Initiated Logout specifications.

audience: List[Client] = []¶

client_id: str | None¶

REQUIRED.

OAuth 2.0 client identifier string. It SHOULD NOT be currently valid for any other registered client, though an authorization server MAY issue the same client identifier to multiple instances of a registered client at its discretion.

client_id_issued_at: datetime | None = None¶

OPTIONAL.

Time at which the client identifier was issued. The time is represented as the number of seconds from 1970-01-01T00:00:00Z as measured in UTC until the date/time of issuance.

client_name: str | None = None¶

Human-readable string name of the client to be presented to the end-user during authorization.

If omitted, the authorization server MAY display the raw “client_id” value to the end-user instead. It is RECOMMENDED that clients always send this field. The value of this field MAY be internationalized, as described in Section 2.2.

client_secret: str | None = None¶

OPTIONAL.

OAuth 2.0 client secret string. If issued, this MUST be unique for each “client_id” and SHOULD be unique for multiple instances of a client using the same “client_id”. This value is used by confidential clients to authenticate to the token endpoint, as described in OAuth 2.0 [RFC6749], Section 2.3.1.

client_secret_expires_at: datetime | None = None¶

REQUIRED if “client_secret” is issued.

Time at which the client secret will expire or 0 if it will not expire. The time is represented as the number of seconds from 1970-01-01T00:00:00Z as measured in UTC until the date/time of expiration.

client_uri: str | None = None¶

URL string of a web page providing information about the client.

If present, the server SHOULD display this URL to the end-user in a clickable fashion. It is RECOMMENDED that clients always send this field. The value of this field MUST point to a valid web page. The value of this field MAY be internationalized, as described in Section 2.2.

contacts: List[str] = None¶

Array of strings representing ways to contact people responsible for this client, typically email addresses.

The authorization server MAY make these contact addresses available to end-users for support requests for the client. See Section 6 for information on Privacy Considerations.

description: str | None = None¶

grant_types: List[str] = ['authorization_code', 'refresh_token']¶

Array of OAuth 2.0 grant type strings that the client can use at the token endpoint. These grant types are defined as follows:

“authorization_code”: The authorization code grant type defined in OAuth 2.0, Section 4.1.
“implicit”: The implicit grant type defined in OAuth 2.0, Section 4.2.
“password”: The resource owner password credentials grant type defined in OAuth 2.0, Section 4.3.
“client_credentials”: The client credentials grant type defined in OAuth 2.0, Section 4.4.
“refresh_token”: The refresh token grant type defined in OAuth 2.0, Section 6.
“urn:ietf:params:oauth:grant-type:jwt-bearer”: The JWT Bearer Token Grant Type defined in OAuth JWT Bearer Token Profiles [RFC7523].
“urn:ietf:params:oauth:grant-type:saml2-bearer”: The SAML 2.0 Bearer Assertion Grant defined in OAuth SAML 2 Bearer Token Profiles [RFC7522].

If the token endpoint is used in the grant type, the value of this parameter MUST be the same as the value of the “grant_type” parameter passed to the token endpoint defined in the grant type definition. Authorization servers MAY allow for other values as defined in the grant type extension process described in OAuth 2.0, Section 4.5. If omitted, the default behavior is that the client will use only the “authorization_code” Grant Type.

jwk: str | None = None¶

Client’s JSON Web Key Set [RFC7517] document value, which contains the client’s public keys.

The value of this field MUST be a JSON object containing a valid JWK Set. These keys can be used by higher-level protocols that use signing or encryption. This parameter is intended to be used by clients that cannot use the “jwks_uri” parameter, such as native clients that cannot host public URLs. The “jwks_uri” and “jwks” parameters MUST NOT both be present in the same request or response.

jwks_uri: str | None = None¶

URL string referencing the client’s JSON Web Key (JWK) Set [RFC7517] document, which contains the client’s public keys.

The value of this field MUST point to a valid JWK Set document. These keys can be used by higher-level protocols that use signing or encryption. For instance, these keys might be used by some applications for validating signed requests made to the token endpoint when using JWTs for client authentication [RFC7523]. Use of this parameter is preferred over the “jwks” parameter, as it allows for easier key rotation. The “jwks_uri” and “jwks” parameters MUST NOT both be present in the same request or response.

logo_uri: str | None = None¶

URL string that references a logo for the client.

If present, the server SHOULD display this image to the end-user during approval. The value of this field MUST point to a valid image file. The value of this field MAY be internationalized, as described in Section 2.2.

policy_uri: str | None = None¶

URL string that points to a human-readable privacy policy document that describes how the deployment organization collects, uses, retains, and discloses personal data.

The authorization server SHOULD display this URL to the end-user if it is provided. The value of this field MUST point to a valid web page. The value of this field MAY be internationalized, as described in Section 2.2.

post_logout_redirect_uris: List[str] = []¶

OPTIONAL.

Array of URLs supplied by the RP to which it MAY request that the End-User’s User Agent be redirected using the post_logout_redirect_uri parameter after a logout has been performed. These URLs SHOULD use the https scheme and MAY contain port, path, and query parameter components; however, they MAY use the http scheme, provided that the Client Type is confidential, as defined in Section 2.1 of OAuth 2.0 [RFC6749], and provided the OP allows the use of http RP URIs.

preconsent: bool | None = False¶

redirect_uris: List[str] = []¶

Array of redirection URI strings for use in redirect-based flows such as the authorization code and implicit flows.

As required by Section 2 of OAuth 2.0 [RFC6749], clients using flows with redirection MUST register their redirection URI values. Authorization servers that support dynamic registration for redirect-based flows MUST implement support for this metadata value.

response_types: List[str] = []¶

Array of the OAuth 2.0 response type strings that the client can use at the authorization endpoint. These response types are defined as follows:

“code”: The authorization code response type defined in OAuth 2.0, Section 4.1.
“token”: The implicit response type defined in OAuth 2.0, Section 4.2.

If the authorization endpoint is used by the grant type, the value of this parameter MUST be the same as the value of the “response_type” parameter passed to the authorization endpoint defined in the grant type definition. Authorization servers MAY allow for other values as defined in the grant type extension process is described in OAuth 2.0, Section 4.5. If omitted, the default is that the client will use only the “code” response type.

scope: List[str] = []¶

String containing a space-separated list of scope values (as described in Section 3.3 of OAuth 2.0 [RFC6749]) that the client can use when requesting access tokens.

The semantics of values in this list are service specific. If omitted, an authorization server MAY register a client with a default set of scopes.

software_id: str | None = None¶

A unique identifier string (e.g., a Universally Unique Identifier (UUID)) assigned by the client developer or software publisher used by registration endpoints to identify the client software to be dynamically registered.

Unlike “client_id”, which is issued by the authorization server and SHOULD vary between instances, the “software_id” SHOULD remain the same for all instances of the client software. The “software_id” SHOULD remain the same across multiple updates or versions of the same piece of software. The value of this field is not intended to be human readable and is usually opaque to the client and authorization server.

software_version: str | None = None¶

A version identifier string for the client software identified by “software_id”.

The value of the “software_version” SHOULD change on any update to the client software identified by the same “software_id”. The value of this field is intended to be compared using string equality matching and no other comparison semantics are defined by this specification. The value of this field is outside the scope of this specification, but it is not intended to be human readable and is usually opaque to the client and authorization server. The definition of what constitutes an update to client software that would trigger a change to this value is specific to the software itself and is outside the scope of this specification.

token_endpoint_auth_method: str | None = None¶

String indicator of the requested authentication method for the token endpoint. Values defined by this specification are:

“none”: The client is a public client as defined in OAuth 2.0, Section 2.1, and does not have a client secret.
“client_secret_post”: The client uses the HTTP POST parameters as defined in OAuth 2.0, Section 2.3.1.
“client_secret_basic”: The client uses HTTP Basic as defined in OAuth 2.0, Section 2.3.1.

Additional values can be defined via the IANA “OAuth Token Endpoint Authentication Methods” registry established in Section 4.2. Absolute URIs can also be used as values for this parameter without being registered. If unspecified or omitted, the default is “client_secret_basic”, denoting the HTTP Basic authentication scheme as specified in Section 2.3.1 of OAuth 2.0.

tos_uri: str | None = None¶

URL string that points to a human-readable terms of service document for the client that describes a contractual relationship between the end-user and the client that the end-user accepts when authorizing the client.

class canaille.oidc.basemodels.Consent[source]¶

Bases: Model

Long-term user consent to an application.