Data models

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.

classmethod get_model_annotations(attribute)[source]
match_filter(filter)[source]
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.

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.

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.

identifier_attribute: ClassVar[str] = 'display_name'
members: User, {'backref': 'groups'}]] = []

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]

Whether 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: Group, {'backref': 'members'}]] = []

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]

Check whether a password has been set for the user.

identifier_attribute: ClassVar[str] = 'user_name'
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

Whether 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
identifier_attribute: ClassVar[str] = 'authorization_code_id'
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.

identifier_attribute: ClassVar[str] = 'client_id'
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.

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.

class canaille.oidc.basemodels.Consent[source]

Bases: Model

Long-term user consent to an application.

client: Client
consent_id: str
identifier_attribute: ClassVar[str] = 'consent_id'
issue_date: datetime
restore()[source]
revokation_date: datetime
revoke()[source]
scope: List[str]
subject: User
class canaille.oidc.basemodels.Token[source]

Bases: Model

OpenID Connect token definition.

access_token: str
audience: List[Client]
client: Client
identifier_attribute: ClassVar[str] = 'token_id'
issue_date: datetime
lifetime: int
refresh_token: str
revokation_date: datetime
scope: List[str]
subject: User
token_id: str
type: str