Configuration¶

Load the configuration¶

Canaille can be configured either by a environment variables, environment file, or by a configuration file.

Configuration file¶

CANAILLE_CONFIG¶: The configuration can be written in toml configuration file which path is passed in the CANAILLE_CONFIG environment variable.

config.toml¶

SECRET_KEY = "very-secret"

[CANAILLE]
NAME = "My organization"

[CANAILLE_SQL]
DATABASE_URI = "postgresql://user:password@localhost/database"
...

You can have a look at the example file for inspiration.

Environment variables¶

In addition, parameters that have not been set in the configuration file can be read from environment variables. The way environment variables are parsed can be read from the pydantic-settings documentation.

Tip

For environment vars, the separator between sections and variables is a double underscore: __. For instance, the NAME var in the CANAILLE section shown above is CANAILLE__NAME.

Environment file¶

Any environment variable can also be written in an environment file, which path should be passed in the CANAILLE_ENV environment variable. For instance, set CANAILLE_ENV=.env to load a .env file.

.env¶

SECRET_KEY="very-secret"
CANAILLE__NAME="My organization"
CANAILLE_SQL__DATABASE_URI="postgresql://user:password@localhost/database"

Configuration methods priority¶

If a same configuration option is defined by different ways, here is how Canaille will choose which one to use:

environment vars have priority over the environment file and the configuration file;
environment file will have priority over the configuration file;
if no configuration method is used, Canaille will look for a canaille.toml configuration file in the current working directory.

Parameters¶

canaille.app.configuration.RootSettings[source]¶

The top-level namespace contains the configuration settings unrelated to Canaille.

The configuration parameters from the following libraries can be used:

config.toml¶

SECRET_KEY = "very-secret"
SERVER_NAME = "auth.mydomain.example"
PREFERRED_URL_SCHEME = "https"
DEBUG = false

[CANAILLE]
NAME = "My organization"
...

BROKER: str | None = None¶

Points to the broker class.

If none, this will be guessed from the value of BROKER_URL:

dramatiq_eager_broker:EagerBroker is used if the broker URL is unset.
This broker executes that’s synchronously, meaning there is no need to run a task worker.
dramatiq.brokers.rabbitmq:RabbitmqBroker is used if the URL is an AMQP URL.
dramatiq.brokers.redis:RedisBroker is used if the URL is a redis URL.

BROKER_URL: str | None = None¶

The URL of the running task worker.

It is passed as url keyword argument to broker class. For example:

redis://localhost:6379
amqp://localhost
redis://username:password@redis.example:6379/0
amqp://guest:guest@localhost:5672/?heartbeat=30&connection_timeout=10

If none, all the tasks are executed synchronously without requiring to run a task worker. This has poor performance but can be useful in tests environments.

CACHE_TYPE: str = 'SimpleCache'¶

The cache type.

The default SimpleCache is a lightweight in-memory cache. See the Flask-Caching documentation for further details.

DEBUG: bool = False¶

The Flask DEBUG configuration setting.

This enables debug options.

Danger

This is useful for development but should be absolutely avoided in production environments.

PERMANENT_SESSION_LIFETIME: timedelta = datetime.timedelta(days=30)¶

The Flask PERMANENT_SESSION_LIFETIME configuration setting.

This sets the lifetime of a permanent session. Users sessions are permanent when they check the “Remember me” checkbox during login.

The value is expressed in ISO8601 duration format. For example:

P365D for 365 days
P30D for 30 days
P1W for 1 week
PT12H for 12 hours
P1DT12H for 1 day and 12 hours

PREFERRED_URL_SCHEME: str = 'https'¶

The Flask PREFERRED_URL_SCHEME configuration setting.

This sets the url scheme by which canaille will be served.

SECRET_KEY: str | None = None¶

The Flask SECRET_KEY configuration setting.

You MUST set a value before deploying in production.

SERVER_NAME: str | None = None¶

The Flask SERVER_NAME configuration setting.

This sets domain name on which canaille will be served.

SESSION_TYPE: Literal['redis', 'memcached', 'filesystem', 'sqlalchemy', 'mongodb', 'cachelib', 'dynamodb'] | None = None¶

The Flask-Session backend type.

If None (default), Flask’s default session implementation is used (client-side signed cookies). When set, sessions are stored server-side using the specified backend.

Available backends:

redis: Store sessions in Redis (connects to localhost:6379 by default)
memcached: Store sessions in Memcached (connects to localhost:11211 by default)
filesystem: Store sessions in local files (uses /tmp/flask-session by default)
sqlalchemy: Store sessions in a SQL database
mongodb: Store sessions in MongoDB
cachelib: Store sessions using a cachelib backend
dynamodb: Store sessions in DynamoDB

See the Flask-Session documentation for backend-specific details.

TRUSTED_HOSTS: list[str] | None = None¶

The Flask TRUSTED_HOSTS configuration setting.

This sets trusted values for hosts and validates hosts during requests.

canaille.core.configuration.CoreSettings[source]¶

The settings from the CANAILLE namespace.

Those are all the configuration parameters that controls the behavior of Canaille.

ACL: dict[str, ACLSettings] | None [Optional]¶

Mapping of permission groups. See ACLSettings for more details.

The ACL name can be freely chosen. For example:

[CANAILLE.ACL.DEFAULT]
PERMISSIONS = ["edit_self", "use_oidc"]
READ = ["user_name", "groups"]
WRITE = ["given_name", "family_name"]

[CANAILLE.ACL.ADMIN]
WRITE = ["user_name", "groups"]

The default ACL gives all permissions to users with the admin user name, and members of a group called admin.

ADMIN_EMAIL: str | None = None¶

Administration email contact.

In certain special cases (example : questioning about password corruption), it is necessary to provide an administration contact email.

AUTHENTICATION_FACTORS: list[str] = ['password']¶

The authentication factors.

Users will need to authenticate with factors in the order of this list. For instance, this will show a password form and then ask for a one-time passcode:

Valid factors are password, otp, email, sms and fido2.

AUTHENTICATION_FACTORS = ["password", "otp"]

CAPTCHA_ENABLED: bool = True¶: Enable CAPTCHA on authentication and registration forms.

CAPTCHA_FAILURE_THRESHOLD: int = 3¶

Number of failed login attempts before showing CAPTCHA.

If 0, CAPTCHA is always shown.
If > 0, CAPTCHA appears after N failed attempts and persists until successful login.
On registration forms, CAPTCHA is always shown when enabled.

CAPTCHA_LENGTH: int = 5¶: CAPTCHA length (number of characters).

DATABASE: str [Optional]¶

The database backend to use.

Default is “sql” if available, else “memory”.

EMAIL_CONFIRMATION: bool | None = None¶

If True, users will need to click on a confirmation link sent by email when they want to add a new email.

By default, this is true if SMTP is configured, else this is false. If explicitly set to true and SMTP is disabled, the email field will be read-only.

ENABLE_INTRUDER_LOCKOUT: bool = False¶: If True, then users will have to wait for an increasingly long time between each failed login attempt.

ENABLE_PASSWORD_COMPROMISSION_CHECK: bool = False¶: If True, Canaille will check if passwords appears in compromission databases such as HIBP when users choose a new one.

ENABLE_PASSWORD_RECOVERY: bool = True¶: If False, then users cannot ask for a password recovery link by email.

ENABLE_REGISTRATION: bool = False¶

If True, then users can freely create an account at this instance.

If email verification is available, users must confirm their email before the account is created.

FAVICON: str | None = '/static/img/canaille-c.webp'¶

You favicon.

If unset and LOGO is set, then the logo will be used.

FIDO_ATTESTATION: Literal['none', 'indirect', 'direct'] = 'none'¶

Attestation conveyance preference for FIDO2/WebAuthn.

Attestation allows the server to verify the authenticator’s identity (manufacturer, model) during registration. This is useful in high-security environments where only specific certified authenticators should be allowed.

none: No attestation requested. The server cannot identify the authenticator type. Most privacy-preserving option, recommended for most use cases.
indirect: Anonymized attestation. The authenticator may provide manufacturer information without revealing the exact model.
direct: Full attestation. The authenticator provides a signed certificate identifying its manufacturer and model. This can be validated against the FIDO Alliance Metadata Service (MDS) to ensure only trusted authenticators are accepted.

Note that even with “direct”, authenticators may refuse to provide attestation for privacy reasons. Additionally, validating attestation certificates requires additional server-side implementation.

FIDO_MAX_CREDENTIALS: int = 5¶: Maximum number of passkeys per user.

FIDO_TIMEOUT: timedelta = datetime.timedelta(seconds=60)¶: Timeout for FIDO2/WebAuthn operations.

FIDO_USER_VERIFICATION: Literal['required', 'preferred', 'discouraged'] = 'preferred'¶

User verification requirement for FIDO2/WebAuthn.

required: User verification (PIN/biometric) is required.
preferred: User verification is preferred but not required.
discouraged: User verification should not be used.

FORCE_HTTPS: bool = False¶: Whether to force the rediction of http requests to https.

HIDE_INVALID_LOGINS: bool = True¶

If True, when users try to sign in with an invalid login, a message is shown indicating that the password is wrong, but does not give a clue whether the login exists or not.

If False, when a user tries to sign in with an invalid login, a message is shown indicating that the login does not exist.

HTMX: bool = True¶: Accelerates webpages loading with asynchronous requests.

INVITATION_EXPIRATION: int = 172800¶

The validity duration of registration invitations, in seconds.

Defaults to 2 days.

JAVASCRIPT: bool = True¶: Enables Javascript to smooth the user experience.

LANGUAGE: str | None = None¶

If a language code is set, it will be used for every user.

If unset, the language is guessed according to the users browser.

LOGGING: str | dict | None = None¶

Configures the logging output using the python logging configuration format:

If None, everything is logged in the standard error output. The log level is DEBUG if the DEBUG setting is True, else this is INFO.
If this is a dict, it is passed to logging.config.dictConfig():
If this is a str, it is expected to be a file path that will be passed to logging.config.fileConfig().

For example:

[CANAILLE.LOGGING]
version = 1
formatters.default.format = "[%(asctime)s] - %(ip)s - %(levelname)s in %(module)s: %(message)s"
root = {level = "INFO", handlers = ["canaille"]}

[CANAILLE.LOGGING.handlers.canaille]
class = "logging.handlers.WatchedFileHandler"
filename = "/var/log/canaille.log"
formatter = "default"

LOGIN_ATTRIBUTES: list[str] | dict[str, str] = ['user_name', 'emails']¶

The attributes users can use to identify themselves, generally a combination of user_name, emails and phone_numbers.

When this is a list, it expects the attribute names to match.
When this is a dict, keys are expected to be the attribute names to match, and values are a Jinja string with a login variable available. This can be used to tune the user input, and for example remove a domain name.

LOGIN_ATTRIBUTES = ["user_name", "emails"]
LOGIN_ATTRIBUTES = {user_name = "{{ login | replace('@example.org', '') }}", emails = "{{ login }}"}

LOGO: str | None = '/static/img/canaille-head.webp'¶: The logo of your organization, this is useful to make your organization recognizable on login screens.

MAX_PASSWORD_LENGTH: int = 1000¶: User password maximum length.

Note

There is a technical limit of 4096 characters with the SQL backend. If the value is 0, None, or greater than 4096, then 4096 will be retained.

MIN_PASSWORD_LENGTH: int = 8¶

User password minimum length.

If 0 or None, password won’t have a minimum length.

NAME: str = 'Canaille'¶

Your organization name.

Used for display purpose.

OTP_LIFETIME: timedelta = datetime.timedelta(seconds=600)¶

One-time password validity duration.

Duration for which email and SMS one-time passwords remain valid. The value is expressed in ISO8601 duration format.

Examples:

PT10M for 10 minutes
PT5M for 5 minutes
PT30S for 30 seconds

OTP_METHOD: OTPMethod = OTPMethod.TOTP¶: The OTP method to use if otp is set in AUTHENTICATION_FACTORS. If set to TOTP, the application will use time-based one-time passcodes, If set to HOTP, the application will use HMAC-based one-time passcodes.

PASSWORD_COMPROMISSION_CHECK_API_URL: str = 'https://api.pwnedpasswords.com/range/'¶: Have i been pwned api url for compromission checks.

PASSWORD_LIFETIME: str | None = None¶

Password validity duration.

If set, user passwords expire after this delay. Users are forced to change their password when the lifetime of the password is over. The duration value is expressed in ISO8601 format. For example, delay of 60 days is written “P60D”.

SENTRY_DSN: str | None = None¶

A Sentry DSN to collect the exceptions.

This is useful for tracking errors in test and production environments.

SMPP: SMPPSettings | None = None¶

The settings related to SMPP configuration.

If unset, sms-related features like sms one-time passcodes won’t be enabled.

SMTP: SMTPSettings | None [Optional]¶

The settings related to SMTP and mail configuration.

If unset, mail-related features like password recovery won’t be enabled.

THEME: Annotated[Path, PathType(path_type=dir)] | None = None¶

A path to a theme.

See the theming documentation for more details.

TIMEZONE: str | None = None¶

The timezone in which datetimes will be displayed to the users (e.g. CEST).

If unset, the server timezone will be used.

TOTP_LIFETIME: timedelta = datetime.timedelta(seconds=30)¶

The validity period for TOTP codes.

Should be provided in ISO8601 duration format (e.g., “PT30S” for 30 seconds, “PT1M” for 1 minute).

canaille.core.configuration.SMTPSettings[source]¶

The SMTP configuration. Belong in the CANAILLE.SMTP namespace.

If unset, mail related features will be disabled, such as mail verification or password recovery emails.

By default, Canaille will try to send mails from localhost without authentication.

FROM_ADDR: str | None = None¶

The sender for Canaille mails.

Some mail provider might require a valid sender address.

HOST: str | None = 'localhost'¶: The SMTP host.

LOGIN: str | None = None¶: The SMTP login.

PASSWORD: str | None = None¶: The SMTP password.

PORT: int | None = 25¶: The SMTP port.

SSL: bool | None = False¶: Whether to use SSL to connect to the SMTP server.

TLS: bool | None = False¶: Whether to use TLS to connect to the SMTP server.

canaille.core.configuration.SMPPSettings[source]¶

The SMPP configuration. Belong in the CANAILLE.SMPP namespace.

If not set, sms related features such as sms one-time passcodes will be disabled.

HOST: str | None = 'localhost'¶: The SMPP host.

LOGIN: str | None = None¶: The SMPP login.

PASSWORD: str | None = None¶: The SMPP password.

PORT: int | None = 2775¶: The SMPP port. Use 8775 for SMPP over TLS (recommended).

canaille.core.configuration.ACLSettings[source]¶

Access Control List settings. Belong in the CANAILLE.ACL namespace.

You can define access controls that define what users can do on canaille. An access control consists in a FILTER to match users, a list of PERMISSIONS matched users will be able to perform, and fields users will be able to READ and WRITE. Users matching several filters will cumulate permissions.

FILTER: dict[str, str] | list[dict[str, str]] | None = None¶

FILTER can be:

None, in which case all the users will match this access control
a mapping where keys are user attributes name and the values those user attribute values. All the values must be matched for the user to be part of the access control.
a list of those mappings. If a user values match at least one mapping, then the user will be part of the access control

Here are some examples:

FILTER = {user_name = 'admin'}
FILTER = [
    {groups = 'admin},
    {groups = 'moderators'},
]

PERMISSIONS: list[Permission] = [Permission.EDIT_SELF, Permission.USE_OIDC, Permission.MANAGE_OWN_GROUPS]¶

A list of Permission users in the access control will be able to manage.

By default, users can edit their own profile, use OpenID Connect, and manage their own groups.

For example:

PERMISSIONS = [
    "manage_users",
    "manage_all_groups",
    "manage_oidc",
    "delete_account",
    "impersonate_users",
]

READ: list[str] = ['user_name', 'groups', 'lock_date']¶: A list of User attributes that users in the ACL will be able to read.

WRITE: list[str] = ['photo', 'given_name', 'family_name', 'display_name', 'password', 'phone_numbers', 'emails', 'profile_url', 'formatted_address', 'street', 'postal_code', 'locality', 'region', 'preferred_language', 'employee_number', 'department', 'title', 'organization']¶: A list of User attributes that users in the ACL will be able to edit.

class canaille.core.configuration.Permission(*values)[source]¶

The permissions that can be assigned to users.

The permissions are intended to be used in ACLSettings.

DELETE_ACCOUNT = 'delete_account'¶

Allows users to delete their account.

If used with MANAGE_USERS, users can delete any account.

EDIT_SELF = 'edit_self'¶: Allows users to edit their own profile.

IMPERSONATE_USERS = 'impersonate_users'¶: Allows users to take the identity of another user.

MANAGE_ALL_GROUPS = 'manage_all_groups'¶: Allows edition and creation of all groups (administrator permission).

MANAGE_OIDC = 'manage_oidc'¶: Allows OpenID Connect client managements.

MANAGE_OWN_GROUPS = 'manage_own_groups'¶: Allows users to create their own groups and manage groups they own.

MANAGE_USERS = 'manage_users'¶: Allows other users management.

USE_OIDC = 'use_oidc'¶: Allows OpenID Connect authentication.

canaille.oidc.configuration.OIDCSettings[source]¶

OpenID Connect settings.

Belong in the CANAILLE_OIDC namespace.

ACTIVE_JWKS: list[dict[str, str] | str] | None = None¶

The active JSON Web Keys Set.

Those keys are used to sign and verify JWTs. The keys can be in the form of JWK dict or raw keys.

DYNAMIC_CLIENT_REGISTRATION_OPEN: bool = False¶

Whether a token is needed for the RFC7591 dynamical client registration.

If True, no token is needed to register a client. If False, dynamical client registration requires a valid JWT token generated by the canaille jwt registration command.

ENABLE_OIDC: bool = True¶: Whether the Single Sign-On feature and the OpenID Connect API is enabled.

INACTIVE_JWKS: list[dict[str, str] | str] | None = None¶

The inactive JSON Web Keys Set.

Those keys are only used to verify JWTs. The keys can be in the form of JWK dict or raw keys.

REQUIRE_NONCE: bool = True¶

Force the nonce exchange during the authentication flows.

This adds security but may not be supported by all clients.

TRUSTED_DOMAINS: Annotated[list[str], NoDecode, BeforeValidator(func=parse_comma_separated, json_schema_input_type=PydanticUndefined)] = ['.localhost', '127.0.0.1']¶

Trusted domains for automatic client trust.

Clients with a client_uri matching these domains will be automatically considered as trusted and will not display the consent page to users. This is particularly useful for development environments.

Supports these patterns:

Exact match: example.com matches example.com
Wildcard match: .example.com matches example.com and all its subdomains

Examples:

[".localhost", "127.0.0.1"] (default for development)
[".dev.company.com", "staging.company.com"]
[".local", "localhost"]

Constraints:

__module__ = pydantic_settings.sources.types
__firstlineno__ = 22
__doc__ = Annotation to prevent decoding of a field value.
__static_attributes__ = ()
__dict__ = {‘__module__’: ‘pydantic_settings.sources.types’, ‘__firstlineno__’: 22, ‘__doc__’: ‘Annotation to prevent decoding of a field value.’, ‘__static_attributes__’: (), ‘__dict__’: <attribute ‘__dict__’ of ‘NoDecode’ objects>, ‘__weakref__’: <attribute ‘__weakref__’ of ‘NoDecode’ objects>}
__weakref__ = <attribute ‘__weakref__’ of ‘NoDecode’ objects>
func = <function parse_comma_separated at 0x72dc973f7d80>
json_schema_input_type = PydanticUndefined

USERINFO_MAPPING: UserInfoMappingSettings | None = UserInfoMappingSettings(SUB='{{ user.user_name }}', NAME='{% if user.formatted_name %}{{ user.formatted_name }}{% endif %}', PHONE_NUMBER='{% if user.phone_numbers %}{{ user.phone_numbers[0] }}{% endif %}', EMAIL='{% if user.preferred_email %}{{ user.preferred_email }}{% endif %}', GIVEN_NAME='{% if user.given_name %}{{ user.given_name }}{% endif %}', FAMILY_NAME='{% if user.family_name %}{{ user.family_name }}{% endif %}', PREFERRED_USERNAME='{% if user.display_name %}{{ user.display_name }}{% endif %}', LOCALE='{% if user.preferred_language %}{{ user.preferred_language }}{% endif %}', ADDRESS='{% if user.formatted_address %}{{ user.formatted_address }}{% endif %}', PICTURE='{% if user.photo %}{{ user | photo_url(external=True) }}{% endif %}', WEBSITE='{% if user.profile_url %}{{ user.profile_url }}{% endif %}', UPDATED_AT='{% if user.last_modified %}{{ user.last_modified.timestamp() }}{% endif %}')¶

“Attribute mapping used to build an OIDC UserInfo object.

UserInfo is used to fill the id_token and the userinfo endpoint.

canaille.oidc.configuration.UserInfoMappingSettings[source]¶

Mapping between the user model and the JWT fields.

Fields are evaluated with jinja. A user var is available.

ADDRESS: str | None = '{% if user.formatted_address %}{{ user.formatted_address }}{% endif %}'¶

EMAIL: str | None = '{% if user.preferred_email %}{{ user.preferred_email }}{% endif %}'¶

FAMILY_NAME: str | None = '{% if user.family_name %}{{ user.family_name }}{% endif %}'¶

GIVEN_NAME: str | None = '{% if user.given_name %}{{ user.given_name }}{% endif %}'¶

LOCALE: str | None = '{% if user.preferred_language %}{{ user.preferred_language }}{% endif %}'¶

NAME: str | None = '{% if user.formatted_name %}{{ user.formatted_name }}{% endif %}'¶

PHONE_NUMBER: str | None = '{% if user.phone_numbers %}{{ user.phone_numbers[0] }}{% endif %}'¶

PICTURE: str | None = '{% if user.photo %}{{ user | photo_url(external=True) }}{% endif %}'¶

PREFERRED_USERNAME: str | None = '{% if user.display_name %}{{ user.display_name }}{% endif %}'¶

SUB: str | None = '{{ user.user_name }}'¶

UPDATED_AT: str | None = '{% if user.last_modified %}{{ user.last_modified.timestamp() }}{% endif %}'¶

WEBSITE: str | None = '{% if user.profile_url %}{{ user.profile_url }}{% endif %}'¶

canaille.scim.configuration.SCIMSettings[source]¶

SCIM settings.

ENABLE_CLIENT: bool = False¶

Whether the state of User and Group are broadcasted to clients using the SCIM protocol.

When enabled, any creation, edition or deletion of a client or a group will be replicated on clients that implement the SCIM protocol.

ENABLE_SERVER: bool = True¶

Whether the SCIM server API is enabled.

When enabled, services plugged to Canaille can update users and groups using the API.

canaille.backends.sql.configuration.SQLSettings[source]¶

Settings related to the SQL backend.

Belong in the CANAILLE_SQL namespace.

AUTO_MIGRATE: bool = True¶

Whether to automatically apply database migrations.

If True, database migrations will be automatically applied when Canaille web application is launched. If False, migrations must be applied manually with canaille db upgrade.

Note

When running the CLI, migrations will never be applied.

DATABASE_URI: str = 'sqlite:///canaille.sqlite'¶

The SQL server URI. For example:

DATABASE_URI = "postgresql://user:password@localhost/database_name"

PASSWORD_HASH_PARAMS: dict [Optional]¶

Additional parameters for password hashing.

These parameters are passed directly to passlib’s CryptContext. Useful for customizing hash parameters like rounds/iterations.

Example to tune PBKDF2:

[CANAILLE_SQL]
PASSWORD_HASH_PARAMS = { "pbkdf2_sha512__rounds" = 100000 }

PASSWORD_SCHEMES: str = 'pbkdf2_sha512'¶

Password hashing scheme.

Defines password hashing scheme in SQL database. See the passlib.hash documentation for a complete list of available schemes.

Examples: "mssql2000", "ldap_salted_sha1", "pbkdf2_sha512", "argon2", "scrypt"

POOL_MAX_OVERFLOW: int = 10¶

The number of connections to allow in overflow beyond POOL_SIZE.

When all persistent connections are in use, additional connections will be created up to this limit. Set to -1 to indicate no overflow limit. See the max_overflow parameter of sqlalchemy.create_engine().

POOL_PRE_PING: bool = False¶

Whether to test connections for liveness upon each checkout.

When enabled, a SELECT 1 is emitted before each connection use to detect stale connections (e.g. after a database restart). The overhead is negligible compared to the cost of failed requests. See the pool_pre_ping parameter of sqlalchemy.create_engine().

POOL_RECYCLE: int = -1¶

Number of seconds after which a connection is automatically recycled.

Useful to prevent the database server from closing idle connections. For example, MySQL/MariaDB closes idle connections after wait_timeout (default 8 hours). Set this to a value below the server’s timeout (e.g. 3600 for one hour). -1 disables recycling. See the pool_recycle parameter of sqlalchemy.create_engine().

POOL_SIZE: int = 5¶

The number of connections to keep persistently in the pool.

Set to 0 to indicate no size limit (not recommended in production). See the pool_size parameter of sqlalchemy.create_engine().

canaille.backends.ldap.configuration.LDAPSettings[source]¶

Settings related to the LDAP backend.

Belong in the CANAILLE_LDAP namespace.

BIND_DN: str = 'cn=admin,dc=example,dc=org'¶: The LDAP bind DN.

BIND_PW: str = 'admin'¶: The LDAP bind password.

GROUP_BASE: str [Required]¶

The LDAP node under which groups will be looked for and saved.

For instance “ou=groups,dc=example,dc=org”.

GROUP_CLASS: str = 'groupOfNames'¶: The object class to use for creating new groups.

GROUP_NAME_ATTRIBUTE: str = 'cn'¶: The attribute to use to identify a group.

GROUP_RDN: str = 'cn'¶: The attribute to identify an object in the Group DN.

POOL_MAX_LIFETIME: int = 600¶

Maximum lifetime of a connection in seconds.

Connections older than this are automatically closed and replaced. Set to 0 to disable lifetime-based recycling. See the max_lifetime parameter of ldappool.ConnectionManager.

POOL_RETRY_DELAY: float = 0.1¶

Delay in seconds between connection retry attempts.

See the retry_delay parameter of ldappool.ConnectionManager.

POOL_RETRY_MAX: int = 3¶

Number of retry attempts when a connection fails.

See the retry_max parameter of ldappool.ConnectionManager.

POOL_SIZE: int = 10¶

The number of connections to keep in the pool.

See the size parameter of ldappool.ConnectionManager.

ROOT_DN: str = 'dc=example,dc=org'¶: The LDAP root DN.

TIMEOUT: float = -1¶: The LDAP connection timeout.

URI: str = 'ldap://localhost'¶: The LDAP server URI.

USER_BASE: str [Required]¶

The LDAP node under which users will be looked for and saved.

For instance ou=users,dc=example,dc=org.

USER_CLASS: list[str] = ['inetOrgPerson']¶: The object class to use for creating new users.

USER_RDN: str = 'uid'¶: The attribute to identify an object in the User DN.

canaille.hypercorn.configuration.HypercornSettings[source]¶

Hypercorn server configuration via environment variables.

ACCESSLOG: str | None = None¶: The target for access log outputs.

ACCESS_LOG_FORMAT: str | None = None¶: The access log format.

ALPN_PROTOCOLS: Annotated[list[str], NoDecode, BeforeValidator(func=parse_comma_separated, json_schema_input_type=PydanticUndefined)] = []¶

The ALPN protocols to advertise.

Constraints:

__module__ = pydantic_settings.sources.types
__firstlineno__ = 22
__doc__ = Annotation to prevent decoding of a field value.
__static_attributes__ = ()
__dict__ = {‘__module__’: ‘pydantic_settings.sources.types’, ‘__firstlineno__’: 22, ‘__doc__’: ‘Annotation to prevent decoding of a field value.’, ‘__static_attributes__’: (), ‘__dict__’: <attribute ‘__dict__’ of ‘NoDecode’ objects>, ‘__weakref__’: <attribute ‘__weakref__’ of ‘NoDecode’ objects>}
__weakref__ = <attribute ‘__weakref__’ of ‘NoDecode’ objects>
func = <function parse_comma_separated at 0x72dc973f7d80>
json_schema_input_type = PydanticUndefined

ALT_SVC_HEADERS: Annotated[list[str], NoDecode, BeforeValidator(func=parse_comma_separated, json_schema_input_type=PydanticUndefined)] = []¶

The alt-svc header values to advertise.

Constraints:

__module__ = pydantic_settings.sources.types
__firstlineno__ = 22
__doc__ = Annotation to prevent decoding of a field value.
__static_attributes__ = ()
__dict__ = {‘__module__’: ‘pydantic_settings.sources.types’, ‘__firstlineno__’: 22, ‘__doc__’: ‘Annotation to prevent decoding of a field value.’, ‘__static_attributes__’: (), ‘__dict__’: <attribute ‘__dict__’ of ‘NoDecode’ objects>, ‘__weakref__’: <attribute ‘__weakref__’ of ‘NoDecode’ objects>}
__weakref__ = <attribute ‘__weakref__’ of ‘NoDecode’ objects>
func = <function parse_comma_separated at 0x72dc973f7d80>
json_schema_input_type = PydanticUndefined

BACKLOG: int | None = None¶: The maximum number of pending connections.

BIND: Annotated[list[str], NoDecode, BeforeValidator(func=parse_comma_separated, json_schema_input_type=PydanticUndefined)] = []¶

The TCP host/address to bind to.

Constraints:

__module__ = pydantic_settings.sources.types
__firstlineno__ = 22
__doc__ = Annotation to prevent decoding of a field value.
__static_attributes__ = ()
__dict__ = {‘__module__’: ‘pydantic_settings.sources.types’, ‘__firstlineno__’: 22, ‘__doc__’: ‘Annotation to prevent decoding of a field value.’, ‘__static_attributes__’: (), ‘__dict__’: <attribute ‘__dict__’ of ‘NoDecode’ objects>, ‘__weakref__’: <attribute ‘__weakref__’ of ‘NoDecode’ objects>}
__weakref__ = <attribute ‘__weakref__’ of ‘NoDecode’ objects>
func = <function parse_comma_separated at 0x72dc973f7d80>
json_schema_input_type = PydanticUndefined

CA_CERTS: str | None = None¶: Path to the SSL CA certificate file.

CERTFILE: str | None = None¶: Path to the SSL certificate file.

CIPHERS: str | None = None¶: The available ciphers for SSL connections.

DEBUG: bool | None = None¶: Enable debug mode.

DOGSTATSD_TAGS: str | None = None¶: Comma separated list of tags to be applied to all StatsD metrics.

ERRORLOG: str | None = None¶: The target for error log outputs.

GRACEFUL_TIMEOUT: float | None = None¶: Time to wait for workers to finish current requests during graceful shutdown.

GROUP: int | None = None¶: The group id to switch to.

H11_MAX_INCOMPLETE_SIZE: int | None = None¶: The maximum size of the incomplete request/response body.

H11_PASS_RAW_HEADERS: bool | None = None¶: Pass raw headers to the application.

H2_MAX_CONCURRENT_STREAMS: int | None = None¶: The maximum number of concurrent streams per HTTP/2 connection.

H2_MAX_HEADER_LIST_SIZE: int | None = None¶: The maximum size of the header list.

H2_MAX_INBOUND_FRAME_SIZE: int | None = None¶: The maximum size of an inbound HTTP/2 frame.

INCLUDE_DATE_HEADER: bool | None = None¶: Include a date header in the response.

INCLUDE_SERVER_HEADER: bool | None = None¶: Include a server header in the response.

INSECURE_BIND: Annotated[list[str], NoDecode, BeforeValidator(func=parse_comma_separated, json_schema_input_type=PydanticUndefined)] = []¶

The TCP host/address to bind to for insecure connections.

Constraints:

__module__ = pydantic_settings.sources.types
__firstlineno__ = 22
__doc__ = Annotation to prevent decoding of a field value.
__static_attributes__ = ()
__dict__ = {‘__module__’: ‘pydantic_settings.sources.types’, ‘__firstlineno__’: 22, ‘__doc__’: ‘Annotation to prevent decoding of a field value.’, ‘__static_attributes__’: (), ‘__dict__’: <attribute ‘__dict__’ of ‘NoDecode’ objects>, ‘__weakref__’: <attribute ‘__weakref__’ of ‘NoDecode’ objects>}
__weakref__ = <attribute ‘__weakref__’ of ‘NoDecode’ objects>
func = <function parse_comma_separated at 0x72dc973f7d80>
json_schema_input_type = PydanticUndefined

KEEP_ALIVE_MAX_REQUESTS: int | None = None¶: The maximum number of requests per keep-alive connection.

KEEP_ALIVE_TIMEOUT: float | None = None¶: Seconds to wait before closing keep-alive connections.

KEYFILE: str | None = None¶: Path to the SSL key file.

KEYFILE_PASSWORD: str | None = None¶: The password for the SSL key file.

LOGCONFIG: str | None = None¶: The log config file path.

LOGCONFIG_DICT: str | None = None¶: The log config dictionary.

LOGLEVEL: str | None = None¶: The (error) log level.

MAX_APP_QUEUE_SIZE: int | None = None¶: The maximum size of the application task queue.

MAX_REQUESTS: int | None = None¶: The maximum number of requests a worker can handle before restarting.

MAX_REQUESTS_JITTER: int | None = None¶: The maximum jitter to add to the max_requests setting.

PID_PATH: str | None = None¶: Path to write the process id.

PROXY_MODE: str | None = None¶: Proxy headers handling mode: None (no proxy), legacy (X-Forwarded-*), or modern (RFC 7239 Forwarded).

PROXY_TRUSTED_HOPS: int = 1¶: Number of trusted proxy hops when PROXY_MODE is set.

QUIC_BIND: Annotated[list[str], NoDecode, BeforeValidator(func=parse_comma_separated, json_schema_input_type=PydanticUndefined)] = []¶

The UDP socket to bind for QUIC.

Constraints:

__module__ = pydantic_settings.sources.types
__firstlineno__ = 22
__doc__ = Annotation to prevent decoding of a field value.
__static_attributes__ = ()
__dict__ = {‘__module__’: ‘pydantic_settings.sources.types’, ‘__firstlineno__’: 22, ‘__doc__’: ‘Annotation to prevent decoding of a field value.’, ‘__static_attributes__’: (), ‘__dict__’: <attribute ‘__dict__’ of ‘NoDecode’ objects>, ‘__weakref__’: <attribute ‘__weakref__’ of ‘NoDecode’ objects>}
__weakref__ = <attribute ‘__weakref__’ of ‘NoDecode’ objects>
func = <function parse_comma_separated at 0x72dc973f7d80>
json_schema_input_type = PydanticUndefined

READ_TIMEOUT: int | None = None¶: The timeout for reading from connections.

ROOT_PATH: str | None = None¶: The ASGI root_path variable.

SERVER_NAMES: Annotated[list[str], NoDecode, BeforeValidator(func=parse_comma_separated, json_schema_input_type=PydanticUndefined)] = []¶

A comma separated list of server names.

Constraints:

__module__ = pydantic_settings.sources.types
__firstlineno__ = 22
__doc__ = Annotation to prevent decoding of a field value.
__static_attributes__ = ()
__dict__ = {‘__module__’: ‘pydantic_settings.sources.types’, ‘__firstlineno__’: 22, ‘__doc__’: ‘Annotation to prevent decoding of a field value.’, ‘__static_attributes__’: (), ‘__dict__’: <attribute ‘__dict__’ of ‘NoDecode’ objects>, ‘__weakref__’: <attribute ‘__weakref__’ of ‘NoDecode’ objects>}
__weakref__ = <attribute ‘__weakref__’ of ‘NoDecode’ objects>
func = <function parse_comma_separated at 0x72dc973f7d80>
json_schema_input_type = PydanticUndefined

SHUTDOWN_TIMEOUT: float | None = None¶: Time to wait for workers to shutdown during graceful shutdown.

SSL_HANDSHAKE_TIMEOUT: float | None = None¶: The SSL handshake timeout.

STARTUP_TIMEOUT: float | None = None¶: Time to wait for workers to start during startup.

STATSD_HOST: str | None = None¶: The host:port of the statsd server.

STATSD_PREFIX: str | None = None¶: Prefix for statsd messages.

UMASK: int | None = None¶: The umask to set for the process.

USER: int | None = None¶: The user id to switch to.

USE_RELOADER: bool | None = None¶: Enable automatic reloading on code changes.

VERIFY_FLAGS: str | None = None¶: The SSL verify flags.

VERIFY_MODE: str | None = None¶: The SSL verify mode.

WEBSOCKET_MAX_MESSAGE_SIZE: int | None = None¶: The maximum size of a WebSocket message.

WEBSOCKET_PING_INTERVAL: float | None = None¶: If set the time in seconds between pings.

WORKERS: int | None = None¶: The number of worker processes.

WORKER_CLASS: str | None = None¶: The type of worker to use.

WSGI_MAX_BODY_SIZE: int | None = None¶: The maximum size of WSGI request body.

Example file¶

Here is a configuration file example that can be generated with the canaille config dump command:

config.toml¶

# The Flask SECRET_KEY configuration setting.
#
# You MUST set a value before deploying in production.
# SECRET_KEY =

# The Flask SERVER_NAME configuration setting.
#
# This sets domain name on which canaille will be served.
# SERVER_NAME =

# The Flask TRUSTED_HOSTS configuration setting.
#
# This sets trusted values for hosts and validates hosts during requests.
# TRUSTED_HOSTS =

# The URL of the running task worker.
#
# It is passed as url keyword argument to broker class. For example:
#
# - redis://localhost:6379
# - amqp://localhost
# - redis://username:password@redis.example:6379/0
# - amqp://guest:guest@localhost:5672/?heartbeat=30&connection_timeout=10
#
# If none, all the tasks are executed synchronously without requiring to run a
# task worker. This has poor performance but can be useful in tests environments.
# BROKER_URL =

# Points to the broker class.
#
# If none, this will be guessed from the value of BROKER_URL:
#
# - dramatiq_eager_broker:EagerBroker is used if the broker URL is unset.
#    This broker executes that's synchronously, meaning there is no need to run a task worker.
# - dramatiq.brokers.rabbitmq:RabbitmqBroker is used if the URL is an AMQP URL.
# - dramatiq.brokers.redis:RedisBroker is used if the URL is a redis URL.
# BROKER =
BROKER = "dramatiq_eager_broker:EagerBroker"

# The Flask PREFERRED_URL_SCHEME configuration setting.
#
# This sets the url scheme by which canaille will be served.
# PREFERRED_URL_SCHEME = "https"

# The Flask DEBUG configuration setting.
#
# This enables debug options.
#
#     This is useful for development but should be absolutely
#     avoided in production environments.
# DEBUG = false

# The cache type.
#
# The default SimpleCache is a lightweight in-memory cache. See the Flask-Caching
# documentation for further details.
# CACHE_TYPE = "SimpleCache"

# The Flask PERMANENT_SESSION_LIFETIME configuration setting.
#
# This sets the lifetime of a permanent session. Users sessions are permanent when
# they check the "Remember me" checkbox during login.
#
# The value is expressed in ISO8601 duration format
# (https://en.wikipedia.org/wiki/ISO_8601#Durations). For example:
#
# - P365D for 365 days
# - P30D for 30 days
# - P1W for 1 week
# - PT12H for 12 hours
# - P1DT12H for 1 day and 12 hours
# PERMANENT_SESSION_LIFETIME = "P30D"

# The Flask-Session backend type.
#
# If None (default), Flask's default session implementation is used (client-side
# signed cookies). When set, sessions are stored server-side using the specified
# backend.
#
# Available backends:
#
# - redis: Store sessions in Redis (connects to localhost:6379 by default)
# - memcached: Store sessions in Memcached (connects to localhost:11211 by default)
# - filesystem: Store sessions in local files (uses /tmp/flask-session by default)
# - sqlalchemy: Store sessions in a SQL database
# - mongodb: Store sessions in MongoDB
# - cachelib: Store sessions using a cachelib backend
# - dynamodb: Store sessions in DynamoDB
#
# See the Flask-Session documentation for backend-specific details.
# SESSION_TYPE =

[CANAILLE]
# Your organization name.
#
# Used for display purpose.
# NAME = "Canaille"

# The database backend to use.
#
# Default is "sql" if available, else "memory".
# DATABASE =
DATABASE = "memory"

# The logo of your organization, this is useful to make your organization
# recognizable on login screens.
# LOGO = "/static/img/canaille-head.webp"

# You favicon.
#
# If unset and LOGO is set, then the logo will be used.
# FAVICON = "/static/img/canaille-c.webp"

# A path to a theme.
#
# See the theming documentation for more details.
# THEME =

# If a language code is set, it will be used for every user.
#
# If unset, the language is guessed according to the users browser.
# LANGUAGE =

# The timezone in which datetimes will be displayed to the users (e.g. CEST).
#
# If unset, the server timezone will be used.
# TIMEZONE =

# A Sentry (https://sentry.io) DSN to collect the exceptions.
#
# This is useful for tracking errors in test and production environments.
# SENTRY_DSN =

# Whether to force the rediction of http requests to https.
# FORCE_HTTPS = false

# Enables Javascript to smooth the user experience.
# JAVASCRIPT = true

# Accelerates webpages loading with asynchronous requests.
# HTMX = true

# If True, users will need to click on a confirmation link sent by email when they
# want to add a new email.
#
# By default, this is true if SMTP is configured, else this is false. If
# explicitly set to true and SMTP is disabled, the email field will be read-only.
# EMAIL_CONFIRMATION =

# If True, then users can freely create an account at this instance.
#
# If email verification is available, users must confirm their email before the
# account is created.
# ENABLE_REGISTRATION = false

# The attributes users can use to identify themselves, generally a combination of
# user_name, emails and phone_numbers.
#
# - When this is a list, it expects the attribute names to match.
# - When this is a dict, keys are expected to be the attribute names to match,
#   and values are a jinja:index string with a login variable available.
#   This can be used to tune the user input, and for example remove a domain name.
#
#     LOGIN_ATTRIBUTES = ["user_name", "emails"]
#     LOGIN_ATTRIBUTES = {user_name = "{{ login | replace('@example.org', '') }}", emails = "{{ login }}"}
# LOGIN_ATTRIBUTES = ["user_name", "emails"]

# If True, when users try to sign in with an invalid login, a message is shown
# indicating that the password is wrong, but does not give a clue whether the
# login exists or not.
#
# If False, when a user tries to sign in with an invalid login, a message is shown
# indicating that the login does not exist.
# HIDE_INVALID_LOGINS = true

# If False, then users cannot ask for a password recovery link by email.
# ENABLE_PASSWORD_RECOVERY = true

# If True, then users will have to wait for an increasingly long time between each
# failed login attempt.
# ENABLE_INTRUDER_LOCKOUT = false

# The authentication factors.
#
# Users will need to authenticate with factors in the order of this list. For
# instance, this will show a password form and then ask for a one-time passcode:
#
# Valid factors are password, otp, email, sms and fido2.
#
#     AUTHENTICATION_FACTORS = ["password", "otp"]
# AUTHENTICATION_FACTORS = ["password"]

# The OTP method to use if otp is set in AUTHENTICATION_FACTORS. If set to TOTP,
# the application will use time-based one-time passcodes, If set to HOTP, the
# application will use HMAC-based one-time passcodes.
# OTP_METHOD = "TOTP"

# The validity period for TOTP codes.
#
# Should be provided in ISO8601 duration format (e.g., "PT30S" for 30 seconds,
# "PT1M" for 1 minute).
# TOTP_LIFETIME = "PT30S"

# Timeout for FIDO2/WebAuthn operations.
# FIDO_TIMEOUT = "PT1M"

# User verification requirement for FIDO2/WebAuthn.
#
# - required: User verification (PIN/biometric) is required.
# - preferred: User verification is preferred but not required.
# - discouraged: User verification should not be used.
# FIDO_USER_VERIFICATION = "preferred"

# Attestation conveyance preference for FIDO2/WebAuthn.
#
# Attestation allows the server to verify the authenticator's identity
# (manufacturer, model) during registration. This is useful in high-security
# environments where only specific certified authenticators should be allowed.
#
# - none: No attestation requested. The server cannot identify the
#   authenticator type. Most privacy-preserving option, recommended for
#   most use cases.
# - indirect: Anonymized attestation. The authenticator may provide
#   manufacturer information without revealing the exact model.
# - direct: Full attestation. The authenticator provides a signed
#   certificate identifying its manufacturer and model. This can be validated
#   against the FIDO Alliance Metadata Service (MDS) to ensure only trusted
#   authenticators are accepted.
#
# Note that even with "direct", authenticators may refuse to provide attestation
# for privacy reasons. Additionally, validating attestation certificates requires
# additional server-side implementation.
# FIDO_ATTESTATION = "none"

# Maximum number of passkeys per user.
# FIDO_MAX_CREDENTIALS = 5

# The validity duration of registration invitations, in seconds.
#
# Defaults to 2 days.
# INVITATION_EXPIRATION = 172800

# User password minimum length.
#
# If 0 or None, password won't have a minimum length.
# MIN_PASSWORD_LENGTH = 8

# User password maximum length.
#
#     There is a technical limit of 4096 characters with the SQL backend.
#     If the value is 0, None, or greater than 4096,
#     then 4096 will be retained.
# MAX_PASSWORD_LENGTH = 1000

# Administration email contact.
#
# In certain special cases (example : questioning about password corruption), it
# is necessary to provide an administration contact email.
# ADMIN_EMAIL =

# If True, Canaille will check if passwords appears in compromission databases
# such as HIBP (https://haveibeenpwned.com) when users choose a new one.
# ENABLE_PASSWORD_COMPROMISSION_CHECK = false

# Have i been pwned api url for compromission checks.
# PASSWORD_COMPROMISSION_CHECK_API_URL = "https://api.pwnedpasswords.com/range/"

# Enable CAPTCHA on authentication and registration forms.
# CAPTCHA_ENABLED = true

# CAPTCHA length (number of characters).
# CAPTCHA_LENGTH = 5

# Number of failed login attempts before showing CAPTCHA.
#
# - If 0, CAPTCHA is always shown.
# - If > 0, CAPTCHA appears after N failed attempts and persists until successful login.
# - On registration forms, CAPTCHA is always shown when enabled.
# CAPTCHA_FAILURE_THRESHOLD = 3

# One-time password validity duration.
#
# Duration for which email and SMS one-time passwords remain valid. The value is
# expressed in ISO8601 duration format
# (https://en.wikipedia.org/wiki/ISO_8601#Durations).
#
# Examples:
#
# - PT10M for 10 minutes
# - PT5M for 5 minutes
# - PT30S for 30 seconds
# OTP_LIFETIME = "PT10M"

# Password validity duration.
#
# If set, user passwords expire after this delay. Users are forced to change their
# password when the lifetime of the password is over. The duration value is
# expressed in ISO8601 format (https://en.wikipedia.org/wiki/ISO_8601#Durations).
# For example, delay of 60 days is written "P60D".
# PASSWORD_LIFETIME =

# Configures the logging output using the python logging configuration format:
#
# - If None, everything is logged in the standard error output.
#   The log level is DEBUG if the DEBUG
#   setting is True, else this is INFO.
# - If this is a dict, it is passed to logging.config.dictConfig:
# - If this is a str, it is expected to be a file path that will be passed
#   to logging.config.fileConfig.
#
# For example:
#
#     [CANAILLE.LOGGING]
#     version = 1
#     formatters.default.format = "[%(asctime)s] - %(ip)s - %(levelname)s in %(module)s: %(message)s"
#     root = {level = "INFO", handlers = ["canaille"]}
#
#     [CANAILLE.LOGGING.handlers.canaille]
#     class = "logging.handlers.WatchedFileHandler"
#     filename = "/var/log/canaille.log"
#     formatter = "default"
# LOGGING =

# The settings related to SMTP and mail configuration.
#
# If unset, mail-related features like password recovery won't be enabled.

[CANAILLE.SMTP]
# The SMTP host.
# HOST = "localhost"

# The SMTP port.
# PORT = 25

# Whether to use TLS to connect to the SMTP server.
# TLS = false

# Whether to use SSL to connect to the SMTP server.
# SSL = false

# The SMTP login.
# LOGIN =

# The SMTP password.
# PASSWORD =

# The sender for Canaille mails.
#
# Some mail provider might require a valid sender address.
# FROM_ADDR =

# The settings related to SMPP configuration.
#
# If unset, sms-related features like sms one-time passcodes won't be enabled.

[CANAILLE.SMPP]
# The SMPP host.
# HOST = "localhost"

# The SMPP port. Use 8775 for SMPP over TLS (recommended).
# PORT = 2775

# The SMPP login.
# LOGIN =

# The SMPP password.
# PASSWORD =

# Mapping of permission groups. See ACLSettings for more details.
#
# The ACL name can be freely chosen. For example:
#
#     [CANAILLE.ACL.DEFAULT]
#     PERMISSIONS = ["edit_self", "use_oidc"]
#     READ = ["user_name", "groups"]
#     WRITE = ["given_name", "family_name"]
#
#     [CANAILLE.ACL.ADMIN]
#     WRITE = ["user_name", "groups"]
#
# The default ACL gives all permissions to users with the `admin` user name, and
# members of a group called `admin`.

[CANAILLE.ACL.DEFAULT]
# A list of Permission users in the access control will be able to manage.
#
# By default, users can edit their own profile, use OpenID Connect, and manage
# their own groups.
#
# For example:
#
#     PERMISSIONS = [
#         "manage_users",
#         "manage_all_groups",
#         "manage_oidc",
#         "delete_account",
#         "impersonate_users",
#     ]
# PERMISSIONS = ["edit_self", "use_oidc", "manage_own_groups"]

# A list of User attributes that users in the ACL will be able to read.
# READ = ["user_name", "groups", "lock_date"]

# A list of User attributes that users in the ACL will be able to edit.
# WRITE = ["photo", "given_name", "family_name", "display_name", "password", "phone_numbers", "emails", "profile_url", "formatted_address", "street", "postal_code", "locality", "region", "preferred_language", "employee_number", "department", "title", "organization"]

# FILTER can be:
#
# - None, in which case all the users will match this access control
# - a mapping where keys are user attributes name and the values those user
#   attribute values. All the values must be matched for the user to be part
#   of the access control.
# - a list of those mappings. If a user values match at least one mapping,
#   then the user will be part of the access control
#
# Here are some examples:
#
#     FILTER = {user_name = 'admin'}
#     FILTER = [
#         {groups = 'admin},
#         {groups = 'moderators'},
#     ]
# FILTER =

[CANAILLE.ACL.ADMIN]
# A list of Permission users in the access control will be able to manage.
#
# By default, users can edit their own profile, use OpenID Connect, and manage
# their own groups.
#
# For example:
#
#     PERMISSIONS = [
#         "manage_users",
#         "manage_all_groups",
#         "manage_oidc",
#         "delete_account",
#         "impersonate_users",
#     ]
# PERMISSIONS = ["edit_self", "use_oidc", "manage_own_groups"]
PERMISSIONS = [
    "manage_oidc",
    "manage_users",
    "manage_all_groups",
    "delete_account",
    "impersonate_users",
]

# A list of User attributes that users in the ACL will be able to read.
# READ = ["user_name", "groups", "lock_date"]

# A list of User attributes that users in the ACL will be able to edit.
# WRITE = ["photo", "given_name", "family_name", "display_name", "password", "phone_numbers", "emails", "profile_url", "formatted_address", "street", "postal_code", "locality", "region", "preferred_language", "employee_number", "department", "title", "organization"]
WRITE = ["groups", "lock_date"]

# FILTER can be:
#
# - None, in which case all the users will match this access control
# - a mapping where keys are user attributes name and the values those user
#   attribute values. All the values must be matched for the user to be part
#   of the access control.
# - a list of those mappings. If a user values match at least one mapping,
#   then the user will be part of the access control
#
# Here are some examples:
#
#     FILTER = {user_name = 'admin'}
#     FILTER = [
#         {groups = 'admin},
#         {groups = 'moderators'},
#     ]
FILTER = [{user_name = "admin"}, {groups = "admin"}]

[CANAILLE_SQL]
# The SQL server URI. For example:
#
#     DATABASE_URI = "postgresql://user:password@localhost/database_name"
# DATABASE_URI = "sqlite:///canaille.sqlite"

# Password hashing scheme.
#
# Defines password hashing scheme in SQL database. See the passlib.hash
# documentation for a complete list of available schemes.
#
# Examples: "mssql2000", "ldap_salted_sha1", "pbkdf2_sha512", "argon2", "scrypt"
# PASSWORD_SCHEMES = "pbkdf2_sha512"

# Additional parameters for password hashing.
#
# These parameters are passed directly to passlib's CryptContext. Useful for
# customizing hash parameters like rounds/iterations.
#
# Example to tune PBKDF2:
#
#     [CANAILLE_SQL]
#     PASSWORD_HASH_PARAMS = { "pbkdf2_sha512__rounds" = 100000 }
# PASSWORD_HASH_PARAMS =
PASSWORD_HASH_PARAMS = {}

# The number of connections to keep persistently in the pool.
#
# Set to 0 to indicate no size limit (not recommended in production). See the
# pool_size parameter of sqlalchemy.create_engine.
# POOL_SIZE = 5

# The number of connections to allow in overflow beyond POOL_SIZE.
#
# When all persistent connections are in use, additional connections will be
# created up to this limit. Set to -1 to indicate no overflow limit. See the
# max_overflow parameter of sqlalchemy.create_engine.
# POOL_MAX_OVERFLOW = 10

# Number of seconds after which a connection is automatically recycled.
#
# Useful to prevent the database server from closing idle connections. For
# example, MySQL/MariaDB closes idle connections after wait_timeout (default 8
# hours). Set this to a value below the server's timeout (e.g. 3600 for one hour).
# -1 disables recycling. See the pool_recycle parameter of
# sqlalchemy.create_engine.
# POOL_RECYCLE = -1

# Whether to test connections for liveness upon each checkout.
#
# When enabled, a SELECT 1 is emitted before each connection use to detect stale
# connections (e.g. after a database restart). The overhead is negligible compared
# to the cost of failed requests. See the pool_pre_ping parameter of
# sqlalchemy.create_engine.
# POOL_PRE_PING = false

# Whether to automatically apply database migrations.
#
# If True, database migrations will be automatically applied when Canaille web
# application is launched. If False, migrations must be applied manually with
# canaille db upgrade.
#
#     When running the CLI, migrations will never be applied.
# AUTO_MIGRATE = true

[CANAILLE_LDAP]
# The LDAP server URI.
# URI = "ldap://localhost"

# The LDAP root DN.
# ROOT_DN = "dc=example,dc=org"

# The LDAP bind DN.
# BIND_DN = "cn=admin,dc=example,dc=org"

# The LDAP bind password.
# BIND_PW = "admin"

# The LDAP connection timeout.
# TIMEOUT = -1

# The LDAP node under which users will be looked for and saved.
#
# For instance `ou=users,dc=example,dc=org`.
# USER_BASE =
USER_BASE = "ou=users,dc=example,dc=org"

# The object class to use for creating new users.
# USER_CLASS = ["inetOrgPerson"]

# The attribute to identify an object in the User DN.
# USER_RDN = "uid"

# The LDAP node under which groups will be looked for and saved.
#
# For instance `"ou=groups,dc=example,dc=org"`.
# GROUP_BASE =
GROUP_BASE = "ou=groups,dc=example,dc=org"

# The object class to use for creating new groups.
# GROUP_CLASS = "groupOfNames"

# The attribute to identify an object in the Group DN.
# GROUP_RDN = "cn"

# The attribute to use to identify a group.
# GROUP_NAME_ATTRIBUTE = "cn"

# The number of connections to keep in the pool.
#
# See the size parameter of ldappool.ConnectionManager.
# POOL_SIZE = 10

# Maximum lifetime of a connection in seconds.
#
# Connections older than this are automatically closed and replaced. Set to 0 to
# disable lifetime-based recycling. See the max_lifetime parameter of
# ldappool.ConnectionManager.
# POOL_MAX_LIFETIME = 600

# Number of retry attempts when a connection fails.
#
# See the retry_max parameter of ldappool.ConnectionManager.
# POOL_RETRY_MAX = 3

# Delay in seconds between connection retry attempts.
#
# See the retry_delay parameter of ldappool.ConnectionManager.
# POOL_RETRY_DELAY = 0.1

[CANAILLE_OIDC]
# Whether the Single Sign-On feature and the OpenID Connect API is enabled.
# ENABLE_OIDC = true

# Whether a token is needed for the RFC7591 dynamical client registration.
#
# If True, no token is needed to register a client. If False, dynamical client
# registration requires a valid JWT token generated by the canaille jwt
# registration command.
# DYNAMIC_CLIENT_REGISTRATION_OPEN = false

# Force the nonce exchange during the authentication flows.
#
# This adds security but may not be supported by all clients.
# REQUIRE_NONCE = true

# The active JSON Web Keys Set.
#
# Those keys are used to sign and verify JWTs. The keys can be in the form of JWK
# dict or raw keys.
# ACTIVE_JWKS =

# The inactive JSON Web Keys Set.
#
# Those keys are only used to verify JWTs. The keys can be in the form of JWK dict
# or raw keys.
# INACTIVE_JWKS =

# Trusted domains for automatic client trust.
#
# Clients with a client_uri matching these domains will be automatically
# considered as trusted and will not display the consent page to users. This is
# particularly useful for development environments.
#
# Supports these patterns:
#
# - Exact match: example.com matches example.com
# - Wildcard match: .example.com matches example.com and all its subdomains
#
# Examples:
#
# - [".localhost", "127.0.0.1"] (default for development)
# - [".dev.company.com", "staging.company.com"]
# - [".local", "localhost"]
# TRUSTED_DOMAINS = [".localhost", "127.0.0.1"]

# "Attribute mapping used to build an OIDC UserInfo object.
#
# UserInfo is used to fill the id_token and the userinfo endpoint.

[CANAILLE_OIDC.USERINFO_MAPPING]
# SUB = "{{ user.user_name }}"

# NAME = "{% if user.formatted_name %}{{ user.formatted_name }}{% endif %}"

# PHONE_NUMBER = "{% if user.phone_numbers %}{{ user.phone_numbers[0] }}{% endif %}"

# EMAIL = "{% if user.preferred_email %}{{ user.preferred_email }}{% endif %}"

# GIVEN_NAME = "{% if user.given_name %}{{ user.given_name }}{% endif %}"

# FAMILY_NAME = "{% if user.family_name %}{{ user.family_name }}{% endif %}"

# PREFERRED_USERNAME = "{% if user.display_name %}{{ user.display_name }}{% endif %}"

# LOCALE = "{% if user.preferred_language %}{{ user.preferred_language }}{% endif %}"

# ADDRESS = "{% if user.formatted_address %}{{ user.formatted_address }}{% endif %}"

# PICTURE = "{% if user.photo %}{{ user | photo_url(external=True) }}{% endif %}"

# WEBSITE = "{% if user.profile_url %}{{ user.profile_url }}{% endif %}"

# UPDATED_AT = "{% if user.last_modified %}{{ user.last_modified.timestamp() }}{% endif %}"

[CANAILLE_SCIM]
# Whether the SCIM server API is enabled.
#
# When enabled, services plugged to Canaille can update users and groups using the
# API.
# ENABLE_SERVER = true

# Whether the state of User and Group are broadcasted to clients using the SCIM
# protocol.
#
# When enabled, any creation, edition or deletion of a client or a group will be
# replicated on clients that implement the SCIM protocol.
# ENABLE_CLIENT = false

[CANAILLE_HYPERCORN]
# The access log format.
# ACCESS_LOG_FORMAT =

# The target for access log outputs.
# ACCESSLOG =

# The ALPN protocols to advertise.
# ALPN_PROTOCOLS = []

# The alt-svc header values to advertise.
# ALT_SVC_HEADERS = []

# The maximum number of pending connections.
# BACKLOG =

# The TCP host/address to bind to.
# BIND = []

# Path to the SSL CA certificate file.
# CA_CERTS =

# Path to the SSL certificate file.
# CERTFILE =

# The available ciphers for SSL connections.
# CIPHERS =

# Enable debug mode.
# DEBUG =

# Comma separated list of tags to be applied to all StatsD metrics.
# DOGSTATSD_TAGS =

# The target for error log outputs.
# ERRORLOG =

# Time to wait for workers to finish current requests during graceful shutdown.
# GRACEFUL_TIMEOUT =

# The group id to switch to.
# GROUP =

# The maximum size of the incomplete request/response body.
# H11_MAX_INCOMPLETE_SIZE =

# Pass raw headers to the application.
# H11_PASS_RAW_HEADERS =

# The maximum number of concurrent streams per HTTP/2 connection.
# H2_MAX_CONCURRENT_STREAMS =

# The maximum size of the header list.
# H2_MAX_HEADER_LIST_SIZE =

# The maximum size of an inbound HTTP/2 frame.
# H2_MAX_INBOUND_FRAME_SIZE =

# Include a date header in the response.
# INCLUDE_DATE_HEADER =

# Include a server header in the response.
# INCLUDE_SERVER_HEADER =

# The TCP host/address to bind to for insecure connections.
# INSECURE_BIND = []

# The maximum number of requests per keep-alive connection.
# KEEP_ALIVE_MAX_REQUESTS =

# Seconds to wait before closing keep-alive connections.
# KEEP_ALIVE_TIMEOUT =

# Path to the SSL key file.
# KEYFILE =

# The password for the SSL key file.
# KEYFILE_PASSWORD =

# The log config file path.
# LOGCONFIG =

# The log config dictionary.
# LOGCONFIG_DICT =

# The (error) log level.
# LOGLEVEL =

# The maximum size of the application task queue.
# MAX_APP_QUEUE_SIZE =

# The maximum number of requests a worker can handle before restarting.
# MAX_REQUESTS =

# The maximum jitter to add to the max_requests setting.
# MAX_REQUESTS_JITTER =

# Path to write the process id.
# PID_PATH =

# Proxy headers handling mode: None (no proxy), legacy (X-Forwarded-*), or modern
# (RFC 7239 Forwarded).
# PROXY_MODE =

# Number of trusted proxy hops when PROXY_MODE is set.
# PROXY_TRUSTED_HOPS = 1

# The UDP socket to bind for QUIC.
# QUIC_BIND = []

# The timeout for reading from connections.
# READ_TIMEOUT =

# The ASGI root_path variable.
# ROOT_PATH =

# A comma separated list of server names.
# SERVER_NAMES = []

# Time to wait for workers to shutdown during graceful shutdown.
# SHUTDOWN_TIMEOUT =

# The SSL handshake timeout.
# SSL_HANDSHAKE_TIMEOUT =

# Time to wait for workers to start during startup.
# STARTUP_TIMEOUT =

# The host:port of the statsd server.
# STATSD_HOST =

# Prefix for statsd messages.
# STATSD_PREFIX =

# The umask to set for the process.
# UMASK =

# Enable automatic reloading on code changes.
# USE_RELOADER =

# The user id to switch to.
# USER =

# The SSL verify flags.
# VERIFY_FLAGS =

# The SSL verify mode.
# VERIFY_MODE =

# The maximum size of a WebSocket message.
# WEBSOCKET_MAX_MESSAGE_SIZE =

# If set the time in seconds between pings.
# WEBSOCKET_PING_INTERVAL =

# The type of worker to use.
# WORKER_CLASS =

# The number of worker processes.
# WORKERS =

# The maximum size of WSGI request body.
# WSGI_MAX_BODY_SIZE =