As of Firefly III 4.7.8 there are two ways to authenticate users. The settings to change these can be accessed through the
.env-file in the root directory of your installation, or they can be changed through environment variables (Docker).
If an environment variable itself contains the
= character, you must escape the entire value using quotes:
-e NORMAL_VAR=hello \-e COMPLEX_VAR="dn=example" \
By default Firefly III uses the "eloquent" driver that allows users to register and login locally. This is based on the user's email address.
Firefly III will allow just one user to register itself after which registration will be blocked. The user who first registered is made administrator and can change the setting over at
/admin to allow others to register.
In the following instructions I will refer to environment variables in all caps, like
To enable LDAP authentication first set
ADLDAP_CONNECTION_SCHEME to say either
ActiveDirectory, depending on your server.
false. I highly recommend to leave this at
Continue the configuration by changing the following settings:
ADLDAP_CONTROLLERS. A space separated list of LDAP controllers.
ADLDAP_USE_TLS to fine tune the connection. Use
ADLDAP_FOLLOW_REFFERALS if you have multiple LDAP servers that may redirect requests.
ADLDAP_BASEDN to indicate where the users can be located. If necessary, set
ADLDAP_ADMIN_PASSWORD to authenticate towards your LDAP server.
Users type the
ADLDAP_DISCOVER_FIELD into the "User identifier"-box of Firefly III. This could be the distinguishedname, the uid or something else entirely. Firefly III will then use the
ADLDAP_AUTH_FIELD to bind users to itself. The
ADLDAP_SYNC_FIELD finally, will be stored in the user table of Firefly III. My strong suggestion is to keep all of these the same.
If necessary, you can set the following prefixes and suffixes so that the user's LDAP accounts are properly formatted for use with your LDAP server:
The administrator account should have these already set in your configuration.
When you're feeling especially daring, you can change the following fields to fine tune authentication with Firefly III.
If you set
ADLDAP_PASSWORD_SYNC to true, Firefly III will sync the user's password to its local user table. This allows users to login to Firefly III when the LDAP server is unavailable. This requires
ADLDAP_LOGIN_FALLBACK to be
true as well.
Generally speaking, Firefly III will give you a "password not accepted" error when something goes wrong. I refer you to the log files of your LDAP server and those of Firefly III to see what went wrong. When in doubt, turn on debug mode and try again.
If you get "cannot be NULL"-errors or "field unavailable"-errors or something like that it means that the discover field, sync field or auth field is empty. Make sure you pick the right field.
The following configuration will allow you to connect to Forum System's excellent example LDAP server. If you configure your Firefly III system, you can login with user "einstein" with password "password".
LOGIN_PROVIDER=ldap# LDAP connection configuration# OpenLDAP, FreeIPA or ActiveDirectoryADLDAP_CONNECTION_SCHEME=OpenLDAPADLDAP_AUTO_CONNECT=true# LDAP connection settingsADLDAP_CONTROLLERS=ldap.forumsys.comADLDAP_PORT=389ADLDAP_TIMEOUT=5ADLDAP_BASEDN="dc=example,dc=com"ADLDAP_FOLLOW_REFFERALS=falseADLDAP_USE_SSL=falseADLDAP_USE_TLS=falseADLDAP_ADMIN_USERNAME="cn=read-only-admin,dc=example,dc=com"ADLDAP_ADMIN_PASSWORD=passwordADLDAP_ACCOUNT_PREFIX="uid="ADLDAP_ACCOUNT_SUFFIX=",dc=example,dc=com"# LDAP authentication settings.ADLDAP_PASSWORD_SYNC=falseADLDAP_LOGIN_FALLBACK=falseADLDAP_DISCOVER_FIELD=uidADLDAP_AUTH_FIELD=uid# Will allow SSO if your server provides an AUTH_USER field.WINDOWS_SSO_DISCOVER=samaccountnameWINDOWS_SSO_KEY=AUTH_USER# field to sync as local username.ADLDAP_SYNC_FIELD=uid
The following is an example configuration for Active Directory:
LOGIN_PROVIDER=ldap# LDAP connection configuration# OpenLDAP, FreeIPA or ActiveDirectoryADLDAP_CONNECTION_SCHEME=ActiveDirectoryADLDAP_AUTO_CONNECT=true# LDAP connection settingsADLDAP_CONTROLLERS=ldap.example.comADLDAP_PORT=389ADLDAP_TIMEOUT=5ADLDAP_BASEDN="dc=example,dc=com"ADLDAP_FOLLOW_REFFERALS=falseADLDAP_USE_SSL=falseADLDAP_USE_TLS=falseADLDAP_ADMIN_USERNAME="ldap"ADLDAP_ADMIN_PASSWORD=password#ADLDAP_ACCOUNT_PREFIX=#ADLDAP_ACCOUNT_SUFFIX=# LDAP authentication settings.ADLDAP_PASSWORD_SYNC=falseADLDAP_LOGIN_FALLBACK=falseADLDAP_DISCOVER_FIELD=samaccountnameADLDAP_AUTH_FIELD=distinguishedname# Will allow SSO if your server provides an AUTH_USER field.WINDOWS_SSO_DISCOVER=samaccountnameWINDOWS_SSO_KEY=AUTH_USER# field to sync as local username.ADLDAP_SYNC_FIELD=samaccountname
Two-step authentication, or two-factor authentication (2FA) asks you for an extra code to enter. This adds security, so even when you lose your password your account is still protected.
You can enable it in your profile.
If you enable 2FA, you will also see eight backup codes that you should save just in case you lose access to your Authenticator app.
To confirm your 2FA settings, submit a code from your Authenticator app twice. In your settings, you will see the upgraded status for 2FA: