Authentication

There are different methods available for authentication.

Internal (default)

This is the internal authentication method of the system. Everything needed is stored in the relational database of the system.

LDAP (including Active Directory)

Using this authentication method you will be able to connect to existing user management and directory services like Active Diectory.

Setting “driver”

string, enum (””, “ads”), optional

Use this setting if connecting to an Active Directory.

Setting “crypt”

string, enum (””, “tls”, “ssl”), optional

While setting this to “ssl” results in having an LDAPS connection established, the use of “tls” will use the “STARTTLS” method which is the standard for secured LDAP connections.

Setting “hostname”

string, default “localhost”

The hostname or IP address of the LDAP server to use. Remember to pay attention to the certificate if using a different hostname or the IP address.

Setting “port”

integer, default 389 | 636

If the port differs from the standard ones then this would go here.

Setting “username”

string, optional

If - and only then - a user is required for query the directory, then you must give the appropriate (viewer) username here.

Setting “password”

string, optional

If - and only then - a user is required for query the directory, then you must give the appropriate (viewer) password here.

Setting “default_domain”

string, optional

If a domain is needed for authentication - specially if using “ads” driver - then you would give the default domain here, if you do not want your users to enter the domain with their username.

Setting “default_domain_only”

bool, default false

This set to true restricts authentication to only the given “default_domain”.

Setting “base_dn”

string, optional

The base of your directory tree. Normally something like “dc=example,dc=com”.

Setting “folder_users”

string, optional

If a standard LDAP query has to be built for user authentication, this is the folder where users reside. Normally something like “ou=people” or “cn=users”.

Setting “field_sid”

string, optional

This setting gives the field to use for building a unique user id for a LDAP authenticated user.

While normally the username is the direct connection, settings this will additionally link the resulting id where the user then gets blocked if the id is not corresponding to the stored one.

Setting “field_username”

string, default “uid”

The username of a LDAP authenticated user and the primary connection.

Setting “field_displayname”

string, default “gecos”

The full name of a LDAP authenticated user.

Setting “field_email”

string, default “mail”

The e-mail address of a LDAP authenticated user.

Setting “field_banned”

string, default “sambaacctflags”

The field (and implicitly given method) of the banned flag.

Setting “search_users”

string, optional

A LDAP filter string to apply for searching users.

Setting “search_groups”

string, optional

A LDAP filter string to apply for searching groups.

Setting “map_groups”

map(string => string[]), optional

With this map you able to translate LDAP groups into access levels and groups within your application for authorization.

There is a special group “_” being the default and always applied one.

{
                        "map_groups": {
                                "_": [
                                        "level.1",
                                        "group.user",
                                        "group.default"
                                ],
                                "sales": [
                                        "group.sales"
                                ],
                                "domain admins": [
                                        "level.9",
                                        "group.admin"
                                ]
                        }
}

It is recommended to use “map_groups” as you have much more control of what happens in the manner of security. However, if there is no “map_groups” then groups based on the names of the LDAP groups will get created.

Setting “map_groups_only”

bool, default false

With this setting enabled only groups in the “map_groups” setting will be used.

Database

If you do not have an appropriate user directory by hand or according to the use case (or security purposes) users must be stored (or are existing) in a different data source (for example a business software), then you should use this authentication method.

Setting “driver”

string, enum (””, “mysql”), optional

Not yet implemented; always defaults to “mysql”. Use this setting to specify the database to connect to.

Setting “hostname”

string, default config_item(“database_hostname”)

The hostname or IP address of the database server to use.

Setting “username”

string, default config_item(“database_username”)

The username to connect to the database server.

Setting “password”

string, default config_item(“database_password”)

The password to connect to the database server.

Setting “database”

string, default config_item(“database_database”)

The database or scheme to use when connected to the database server. If the setting is not given, then the system database is used.

Setting “default_domain”

string, optional

If a domain is needed for authentication then you would give the default domain here, if you do not want your users to enter the domain with their username.

Setting “default_domain_only”

bool, default false

This set to true restricts authentication to only the given “default_domain”.

Setting “field_sid”

string, optional

This setting gives the field to use for building a unique user id for an authenticated user.

While normally the username is the direct connection, settings this will additionally link the resulting id where the user then gets blocked if the id is not corresponding to the stored one.

Setting “field_username”

string, default “username”

The field holding the username of an authenticated user and the primary connection.

Setting “field_password”

string, default “password”

The field holding the hashed password of an authenticated user.

Appropriate SQL queries should return the hashing algorithm used in a special syntax before the according hash value.

Setting “field_displayname”

string, optional

The full name of an authenticated user.

Setting “field_email”

string, optional

The e-mail address of an authenticated user.

Setting “field_banned”

string, optional

The field of the banned flag.

Setting “field_banned_value”

string, optional

The field value which the field “field_banned” must have to set an user banned.

Setting “field_role”

string, optional

The field gives a role out of the appropriate record which is then used as an additional group membership.

Setting “search_users”

string, optional

A SQL query to find the needed users.

Setting “search_groups”

string, optional

A SQL query to find the needed groups.

Setting “map_groups”

map(string => string[]), optional

With this map you able to translate the groups out of the database into access levels and groups within your application for authorization.

There is a special group “_” being the default and always applied one.

{
                        "map_groups": {
                                "_": [
                                        "level.1",
                                        "group.user",
                                        "group.default"
                                ],
                                "sales": [
                                        "group.sales"
                                ],
                                "admins": [
                                        "level.9",
                                        "group.admin"
                                ]
                        }
}

It is recommended to use “map_groups” as you have much more control of what happens in the manner of security. However, if there is no “map_groups” then groups based on the names out of the database will get created.

Setting “map_groups_only”

bool, default false

With this setting enabled only groups in the “map_groups” setting will be used.