forked from Github-Mirrors/canaille
320 lines
11 KiB
ReStructuredText
320 lines
11 KiB
ReStructuredText
Configuration
|
|
#############
|
|
|
|
Here are the different options you can have in your configuration file.
|
|
|
|
.. contents::
|
|
:local:
|
|
|
|
.. note ::
|
|
|
|
Any configuration entry can be suffixed by *_FILE* and point to the path of
|
|
a file that contains the actual value. For instance you could have
|
|
``SECRET_KEY_FILE = "/path/to/secret.txt"`` instead of ``SECRET_KEY = "very-secret"``
|
|
|
|
Sections
|
|
========
|
|
|
|
Miscellaneous
|
|
-------------
|
|
Canaille is based on Flask, so any `flask configuration <https://flask.palletsprojects.com/en/2.3.x/config/#builtin-configuration-values>`_ option will be usable with canaille:
|
|
|
|
:SECRET_KEY:
|
|
**Required.** The Flask secret key. You should set a random string here.
|
|
|
|
.. note ::
|
|
|
|
Remember that you can also use SECRET_KEY_FILE to store the secret key
|
|
outside the configuration file.
|
|
|
|
:NAME:
|
|
*Optional.* The name of your organization. If not set `Canaille` will be used.
|
|
|
|
:LOGO:
|
|
*Optional.* The URL ot the logo of your organization. The default is the canaille logo.
|
|
|
|
:FAVICON:
|
|
*Optional.* An URL to a favicon. The default is the value of ``LOGO``.
|
|
|
|
:THEME:
|
|
*Optional.* The name or the path to a canaille theme.
|
|
If the value is just a name, the theme should be in a directory with that namein the *themes* directory.
|
|
|
|
:LANGUAGE:
|
|
*Optional.* The locale code of the language to use. If not set, the language of the browser will be used.
|
|
|
|
:TIMEZONE:
|
|
*Optional.* The timezone in which datetimes will be displayed to the users. If unset, the server timezone will be used.
|
|
|
|
:JAVASCRIPT:
|
|
*Optional.* Wether javascript is used to smooth the user experience.
|
|
|
|
:HTMX:
|
|
*Optional.* Wether `HTMX <https://htmx.org>`_ will be used to accelerate webpages. Defaults to true.
|
|
|
|
:SENTRY_DSN:
|
|
*Optional.* A DSN to a sentry instance.
|
|
This needs the ``sentry_sdk`` python package to be installed.
|
|
This is useful if you want to collect the canaille exceptions in a production environment.
|
|
|
|
:ENABLE_REGISTRATION:
|
|
*Optional.* If true, then users can freely create an account
|
|
at this instance. If ``EMAIL_CONFIRMATION`` is true, users must confirm
|
|
their email before the account is created.
|
|
Defaults to false.
|
|
|
|
:EMAIL_CONFIRMATION:
|
|
*Optional.* If set to 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 explicitely set to
|
|
true and SMTP is disabled, the email field will be read-only.
|
|
|
|
:HIDE_INVALID_LOGINS:
|
|
*Optional.* Wether to tell the users if a username exists during failing login attempts.
|
|
Defaults to ``True``. This may be a security issue to disable this, as this give a way to malicious people to if an account exists on this canaille instance.
|
|
|
|
:ENABLE_PASSWORD_RECOVERY:
|
|
*Optional* Wether the password recovery feature is enabled or not.
|
|
Defaults to ``True``.
|
|
|
|
:INVITATION_EXPIRATION:
|
|
*Optional* The validity duration of registration invitations, in seconds.
|
|
Defaults to 2 days.
|
|
|
|
LOGGING
|
|
-------
|
|
|
|
:LEVEL:
|
|
*Optional.* The logging level. Must be an either *DEBUG*, *INFO*, *WARNING*, *ERROR* or *CRITICAL*. Defults to *WARNING*.
|
|
|
|
:PATH:
|
|
*Optional.* The log file path. If not set, logs are written in the standard error output.
|
|
|
|
BACKENDS.LDAP
|
|
-------------
|
|
|
|
:URI:
|
|
**Required.** The URI to the LDAP server.
|
|
e.g. ``ldaps://ldad.mydomain.tld``
|
|
|
|
:ROOT_DN:
|
|
**Required.** The root DN of your LDAP server.
|
|
e.g. ``dc=mydomain,dc=tld``
|
|
|
|
:BIND_DN:
|
|
**Required.** The LDAP DN to bind with.
|
|
e.g. ``cn=admin,dc=mydomain,dc=tld``
|
|
|
|
:BIND_PW:
|
|
**Required.** The LDAP user associated with ``BIND_DN``.
|
|
|
|
:TIMEOUT:
|
|
*Optional.* The time to wait for the LDAP server to respond before considering it is not functional.
|
|
|
|
:USER_BASE:
|
|
**Required.** The DN of the node in which users will be searched for, and created.
|
|
e.g. ``ou=users,dc=mydomain,dc=tld``
|
|
|
|
:USER_CLASS:
|
|
*Optional.* The LDAP object class to filter existing users, and create new users.
|
|
Can be a list of classes.
|
|
Defaults to ``inetOrgPerson``.
|
|
|
|
:USER_RDN:
|
|
*Optional.* The attribute to identify an object in the User DN.
|
|
For example, if it has the value ``uid``, users DN will be in the form ``uid=foobar,ou=users,dc=mydomain,dc=tld``.
|
|
Defaults to ``cn``.
|
|
|
|
:USER_FILTER:
|
|
*Optional.* The filter to match users on sign in.
|
|
Jinja syntax is supported and a `login` variable is available containing
|
|
the value passed in the login field.
|
|
Defaults to ``(|(uid={{ login }})(mail={{ login }}))``
|
|
|
|
:GROUP_BASE:
|
|
**Required.** The DN where of the node in which LDAP groups will be created and searched for.
|
|
e.g. ``ou=groups,dc=mydomain,dc=tld``
|
|
|
|
:GROUP_CLASS:
|
|
*Optional.* The LDAP object class to filter existing groups, and create new groups.
|
|
Can be a list of classes.
|
|
Defaults to ``groupOfNames``
|
|
|
|
:GROUP_RDN:
|
|
*Optional.* The attribute to identify an object in a group DN.
|
|
For example, if it has the value ``cn``, groups DN will be in the form ``cn=foobar,ou=users,dc=mydomain,dc=tld``.
|
|
Defaults to ``cn``
|
|
|
|
:GROUP_NAME_ATTRIBUTE:
|
|
*Optional.* The attribute to identify a group in the web interface.
|
|
Defaults to ``cn``
|
|
|
|
ACL
|
|
---
|
|
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`` that users will be able to perform, and fields users will be able
|
|
to ``READ`` and ``WRITE``. Users matching several filters will cumulate permissions.
|
|
|
|
The 'READ' and 'WRITE' attributes are the LDAP attributes of the user
|
|
object that users will be able to read and/or write.
|
|
|
|
:FILTER:
|
|
*Optional.* It can be:
|
|
|
|
- absent, in which case all the users will have the permissions in this ACL.
|
|
- 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:
|
|
*Optional.* A list of items the users in the access control will be able to manage. Values can be:
|
|
|
|
- **edit_self** to allow users to edit their own profile
|
|
- **use_oidc** to allow OpenID Connect authentication
|
|
- **manage_oidc** to allow OpenID Connect client managements
|
|
- **manage_users** to allow other users management
|
|
- **manage_groups** to allow group edition and creation
|
|
- **delete_account** allows a user to delete his own account. If used with *manage_users*, the user can delete any account
|
|
- **impersonate_users** to allow a user to take the identity of another user
|
|
|
|
:READ:
|
|
*Optional.* A list of attributes of ``USER_CLASS`` the user will be able to see, but not edit.
|
|
If the users has the ``edit_self`` permission, they will be able to see those fields on their own account.
|
|
If the users has the ``manage_users`` permission, the user will be able to see this fields on other users profile.
|
|
If the list containts the special ``groups`` field, the user will be able to see the groups he belongs to.
|
|
|
|
:WRITE:
|
|
*Optional.* A list of attributes of ``USER_CLASS`` the user will be able to edit.
|
|
If the users has the ``edit_self`` permission, they will be able to edit those fields on their own account.
|
|
If the users has the ``manage_users`` permission, they will be able to edit those fields on other users profile.
|
|
If the list containts the special ``groups`` field, the user will be able to edit the groups he belongs to.
|
|
|
|
OIDC
|
|
----
|
|
|
|
:DYNAMIC_CLIENT_REGISTRATION_OPEN:
|
|
*Optional.* Wether 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 needs a token defined
|
|
in `DYNAMIC_CLIENT_REGISTRATION_TOKENS``
|
|
Defaults to ``False``
|
|
|
|
:DYNAMIC_CLIENT_REGISTRATION_TOKENS:
|
|
*Optional.* A list of tokens that can be used for dynamic client registration
|
|
|
|
:REQUIRE_NONE:
|
|
*Optional.* Forces the nonce exchange during the authentication flows.
|
|
This adds security but may not be supported by all clients.
|
|
Defaults to ``True``
|
|
|
|
OIDC.JWT
|
|
--------
|
|
Canaille needs a key pair to sign the JWT. The installation command will generate a key pair for you, but you can also do it manually. In debug mode, a in-memory keypair will be used.
|
|
|
|
:PRIVATE_KEY:
|
|
**Required.** The content of the private key..
|
|
|
|
:PUBLIC_KEY:
|
|
**Required.** The content of the public key.
|
|
|
|
.. note ::
|
|
|
|
Remember that you can also use PRIVATE_KEY_FILE and PUBLIC_KEY_FILE
|
|
to store the keys outside the configuration file.
|
|
|
|
:ISS:
|
|
*Optional.* The URI of the identity provider.
|
|
Defaults to ``SERVER_NAME`` if set, else the current domain will be used.
|
|
e.g. ``https://auth.mydomain.tld``
|
|
|
|
:KTY:
|
|
*Optional.* The key type parameter.
|
|
Defaults to ``RSA``.
|
|
|
|
:ALG:
|
|
*Optional.* The key algorithm.
|
|
Defaults to ``RS256``.
|
|
|
|
:EXP:
|
|
*Optional.* The time the JWT will be valid, in seconds.
|
|
Defaults to ``3600``
|
|
|
|
OIDC.JWT.MAPPINGS
|
|
-----------------
|
|
|
|
A mapping where keys are JWT claims, and values are LDAP user object attributes.
|
|
Attributes are rendered using jinja2, and can use a ``user`` variable.
|
|
|
|
:SUB:
|
|
*Optional.* Defaults to ``{{ user.user_name[0] }}``
|
|
|
|
:NAME:
|
|
*Optional.* Defaults to ``{{ user.cn[0] }}``
|
|
|
|
:PHONE_NUMBER:
|
|
*Optional.* Defaults to ``{{ user.phone_number[0] }}``
|
|
|
|
:EMAIL:
|
|
*Optional.* Defaults to ``{{ user.mail[0] }}``
|
|
|
|
:GIVEN_NAME:
|
|
*Optional.* Defaults to ``{{ user.given_name[0] }}``
|
|
|
|
:FAMILY_NAME:
|
|
*Optional.* Defaults to ``{{ user.family_name[0] }}``
|
|
|
|
:PREFERRED_USERNAME:
|
|
*Optional.* Defaults to ``{{ user.display_name[0] }}``
|
|
|
|
:LOCALE:
|
|
*Optional.* Defaults to ``{{ user.locale }}``
|
|
|
|
:ADDRESS:
|
|
*Optional.* Defaults to ``{{ user.address[0] }}``
|
|
|
|
:PICTURE:
|
|
*Optional.* Defaults to ``{% if user.photo %}{{ url_for('core.account.photo', user_name=user.user_name[0], field='photo', _external=True) }}{% endif %}``
|
|
|
|
:WEBSITE:
|
|
*Optional.* Defaults to ``{{ user.profile_url[0] }}``
|
|
|
|
|
|
SMTP
|
|
----
|
|
Canaille needs you to configure a SMTP server to send some mails, including the *I forgot my password* and the *invitation* mails.
|
|
Without this section Canaille will still be usable, but all the features related to mail will be disabled.
|
|
|
|
:HOST:
|
|
The SMTP server to connect to.
|
|
Defaults to ``localhost``
|
|
|
|
:PORT:
|
|
The port to use with the SMTP connection.
|
|
Defaults to ``25``
|
|
|
|
:TLS:
|
|
Whether the SMTP connection use TLS.
|
|
Default to ``False``
|
|
|
|
:SSL:
|
|
Whether the SMTP connection use SSL.
|
|
Default to ``False``
|
|
|
|
:LOGIN:
|
|
The SMTP server authentication login.
|
|
*Optional.*
|
|
|
|
:PASSWORD:
|
|
The SMTP server authentication password.
|
|
*Optional.*
|
|
|
|
:FROM_ADDR:
|
|
*Optional.* The mail address to use as the sender for Canaille emails.
|
|
Defaults to `admin@<HOSTNAME>` where `HOSTNAME` is the current hostname.
|