Databases

Canaille can read and save data in different databases. This page presents the different database backends and their specificities:

Memory

Canaille comes with a lightweight inmemory backend by default. It is used when no other backend has been configured.

This backend is only for test purpose and should not be used in production environments.

SQL

Canaille can use any database supported by SQLAlchemy, such as sqlite, postgresql or mariadb.

It is used when the CANAILLE_SQL configuration parameter is defined. For instance:

config.toml
[CANAILLE_SQL]
SQL_DATABASE_URI = "postgresql://user:password@localhost/database"

You can find more details on the SQL configuration in the dedicated section.

LDAP

Canaille can use OpenLDAP as its main database. It is used when the CANAILLE_LDAP configuration parameter is defined. For instance:

config.toml
[CANAILLE_LDAP]
URI = "ldap://ldap"
ROOT_DN = "dc=mydomain,dc=tld"
BIND_DN = "cn=admin,dc=mydomain,dc=tld"
BIND_PW = "very-secret-password"

USER_BASE = "ou=users,dc=mydomain,dc=tld"
USER_CLASS = "inetOrgPerson"
USER_FILTER = "(|(uid={{ login }})(mail={{ login }}))"

GROUP_BASE = "ou=groups,dc=mydomain,dc=tld"

If you want to use TOTP/HOTP authentication, you will need to add the oathHOTPToken class to the user:

USER_CLASS = ["inetOrgPerson", "oathHOTPToken"]

You can find more details on the LDAP configuration in the dedicated section.

Note

Currently, only the inetOrgPerson, oathHOTPToken and groupOfNames schemas have been tested. If you want to use different schemas or LDAP servers, adaptations may be needed. Patches are welcome.

OpenLDAP overlays integration

Canaille can integrate with several OpenLDAP overlays:

memberof / refint

memberof and refint overlays are needed for the Canaille group membership to work correctly.

Here is a configuration example compatible with canaille:

memberof-config.ldif
dn: cn=module,cn=config
cn: module
objectClass: olcModuleList
olcModuleLoad: memberof

dn: olcOverlay=memberof,olcDatabase={1}mdb,cn=config
objectClass: olcConfig
objectClass: olcMemberOf
objectClass: olcOverlayConfig
objectClass: top
olcOverlay: memberof
olcMemberOfDangling: ignore
olcMemberOfRefInt: TRUE
olcMemberOfGroupOC: groupOfNames
olcMemberOfMemberAD: member
olcMemberOfMemberOfAD: memberOf
refint-config.ldif
dn: cn=module,cn=config
cn: module
objectClass: olcModuleList
olcModuleLoad: refint

dn: olcOverlay=refint,olcDatabase={1}mdb,cn=config
objectClass: olcConfig
objectClass: olcOverlayConfig
objectClass: olcRefintConfig
objectClass: top
olcOverlay: refint
olcRefintAttribute: memberof
olcRefintAttribute: member
olcRefintAttribute: manager
olcRefintAttribute: owner

You can adapt and load those configuration files with:

# Adapt those commands according to your setup
sudo ldapadd -Q -H ldapi:/// -Y EXTERNAL -f memberof-config.ldif
sudo ldapadd -Q -H ldapi:/// -Y EXTERNAL -f refint-config.ldif

ppolicy

If the ppolicy overlay is configured and the pwdEndTime attribute is available (since OpenLDAP 2.6), then account locking support will be enabled in canaille. To allow users to manage account expiration, they need to have a write permission on the lock_date attribute.

Here is a configuration example compatible with canaille:

ppolicy-config.ldif
dn: cn=module,cn=config
cn: module
objectClass: olcModuleList
olcModuleLoad: ppolicy

dn: olcOverlay=ppolicy,olcDatabase={1}mdb,cn=config
objectClass: olcOverlayConfig
objectClass: olcPPolicyConfig
olcOverlay: ppolicy
olcPPolicyDefault: cn=passwordDefault,dc=mydomain,dc=tld
olcPPolicyUseLockout: TRUE
ppolicy.ldif
dn: cn=passwordDefault,dc=mydomain,dc=tld
objectClass: person
objectClass: top
objectClass: pwdPolicy
sn: passwordDefault
cn: passwordDefault
pwdAttribute: userPassword
pwdMustChange: TRUE
pwdLockout: TRUE
pwdAllowUserChange: TRUE
pwdGraceAuthNLimit: 1
pwdMaxFailure: 999

You can adapt and load those configuration files with:

# Adapt those commands according to your setup
sudo ldapadd -Q -H ldapi:/// -Y EXTERNAL -f ppolicy-config.ldif
sudo ldapadd -Q -H ldapi:/// -Y EXTERNAL -f ppolicy.ldif

otp

If the otp overlay is configured, you will be able to add one-time password authentication in canaille.

Here is a configuration example compatible with canaille:

otp-config.ldif
dn: cn=module,cn=config
cn: module
objectClass: olcModuleList
olcModuleLoad: otp

dn: olcOverlay=otp,olcDatabase={1}mdb,cn=config
objectClass: olcOverlayConfig
olcOverlay: otp

You can adapt and load this configuration file with:

# Adapt this command according to your setup
sudo ldapadd -Q -H ldapi:/// -Y EXTERNAL -f otp-config.ldif

You will also need to add the oathHOTPToken class to the user:

config.toml
[CANAILLE_LDAP]
...
USER_CLASS = ["inetOrgPerson", "oathHOTPToken"]