SOGo 6 - User Sources (Domain Settings)

Introduction

In SOGo 6, a User Source is the external service where SOGo finds information about users, about other users for autocompletion, and for the Global Address Book. A User Source may also be used for the authentication step with the plain login method. However, even if you’re using an SSO or an external authentication system, the User Source is still mandatory.

Authentication only tells SOGo that: "The user is 'XXX' and is legitimate." The User Source then fetches information about XXX such as mail, name, aliases, rights…​

SOGo 6 supports two kinds of User Sources:

  • LDAP server: any brand, as long as it supports the LDAP protocol. SOGo 6 supports the standard LDAP schema but can also be tuned to match your own LDAP schema.

  • Database server: PostgreSQL or MariaDB. In this case, you will need to create and manage the users table, since no "standard user table for SQL" exists.

If you come from SOGo 5, your User Sources will work with SOGo 6 with no change needed.

Domain, domain and domain

The term "domain" is one of those web terms that can refer to several things depending on the context. (Top 3 of confusing words, along with namespace and blob)

In SOGo, "domain" refers 99% of the time to the user’s main mail domain. If not, it will be explained.

E.g.:
Your SOGo 6 application is hosted on https://my.sogo.nu, the user logs in with the uid "sogo1@main.nu", their mail is sogo1@sogo.nu, they have an alias sogo@sogo.net, and the LDAP DC is "dc=example,dc=org": the domain is sogo.nu.

You can have one or several User Sources. Having two User Sources doesn’t mean they are two different LDAP/DB servers. They can be the same server with different filters or conditions. E.g. one LDAP server but two User Sources in SOGo, one with the filter "is_user == 1" and one with "is_group == 1". It allows users to see two distinct Global Address Books.

A Global Address Book is an Address Book that users can see but only read from. The admin (you) chooses whether a User Source is a Global Address Book or not.

Some recommendations

Because of the legacy of previous SOGo versions and the improvements in SOGo 6, there are several ways to achieve the same behavior. If you’re coming from SOGo 5, it’s worth reading this documentation to possibly build a better, simpler configuration.

In many cases you will only need one User Source, so don’t be overwhelmed by all the settings.

Some settings here override settings found in other domain topics. This will be explained where relevant.

Don’t forget that you set default domain settings first, and then you can set per-domain settings that override the defaults.
E.g. you have one User Source with 5 different domains, and domain sogo5.nu is not allowed to authenticate. Set the default domain settings with US_CAN_AUTH = True, then create a domain sogo5.nu where US_CAN_AUTH = False. Some use cases will be given.

Name and UID settings

  • US_UID: A string, the unique identifier of this User Source. It can be anything as long as it’s unique. If you’re using the SOGo 6 UI, it will be generated for you. If you’re using the API directly, choose it yourself. Once it’s set, it cannot be changed. This uid is only used by the SOGo 6 backend logic and is not shown to users or admins.

  • US_NAME: A string, a name for this User Source that will be seen by admins. You can use the setting US_DISPLAY_NAME to change the name that will be seen by users. It is not required to be unique, even if that would be strange.

  • US_DESCRIPTION: A string, only seen by admins. Only add information for admins, nothing else.

  • US_TYPE: Defines the kind of User Source. Can be either 'ldap' or 'db'.

Common settings

Some settings ask for the name of:

  • a field in the case of LDAP

  • a column in the case of SQL

This field or column must store the information needed by the setting. E.g. US_FIELD_UID needs to know where the uid (what your users log in with) is stored. It can be the field 'uid' or 'mail' in the case of LDAP, or the column 'c_uid' or 'login' for SQL.

Such cases will be referred to as field/column.

  • US_FIELD_UID: Defaults to 'uid'. The field/column where the unique identifier of your user is found. This is what your users will use to log in. It must be unique.

If you’re using the same SQL User Source as SOGo 5, set this setting to 'c_uid'.

  • US_FIELD_CN: Defaults to 'cn'. The field/column where to find the Common Name of your user.

If you’re using the same SQL User Source as SOGo 5, set this setting to 'c_cn'.

  • US_MAIL: Defaults to ['mail']. A list of fields/columns where the user’s mail addresses can be found.

The first element of the list must contain the main mail address of the users. All the others will be considered as aliases. Users will be able to choose an alias when sending a mail.

For aliases:

With LDAP (considering you have a field mailAlias):

mailAlias: myalias@sogo.nu
mailAlias: myotheralias@sogo.nu

With SQL: the value must be a space-separated list of the aliases.

Obviously, you can also have several fields/columns and add them all to the list.

  • US_MAIL_SERVER_LOGIN: By default, SOGo uses the user uid for mail server (Dovecot, Cyrus) authentication. If this is not the case, set this setting to the field/column where the correct login can be found.

  • US_MAIL_FILTERING_LOGIN: Same for the filtering server (Sieve).

  • US_MAIL_OUTGOING_LOGIN: Same for the outgoing server (Postfix), if you have enabled authentication for it.

  • US_FILTER: Additional filter to use when querying the User Source. It uses a simplified syntax that will be converted into an LDAP filter or an SQL WHERE condition.

E.g. if you have a field/column 'active', you can set this setting to active == 1. For LDAP, that will add the filter (&(other_filters)(active=1)). And for SQL, WHERE other_filters AND active = 1.

Rules for the syntax:

{field_column}{space}{comparison_operator}{space}{value}

  • {field_column} is unquoted

  • {space} is required before and after the operator!

  • {comparison_operator} is one of: == (equal), != (not equal), ⇐ (less than or equal), >= (greater than or equal)

  • {value} is either a number or a quoted string. E.g.:

    • kind == group is not valid; use kind == "group" instead.

You can also build complex filters with logical operator AND and OR:

{opening_parenthesis}{filter1}{space}{logical_operator}{space}{filter2}{closing_parenthesis}

E.g. (mind the parentheses):

  • (active == 1 AND kind == "user")

  • (active == 1 OR admin == 1)

You can chain the conditions:

  • (p1 == 'v1' AND p2 == 'v2' AND p3 == 'v3' AND p4 == 'v4')

Mix them (AND takes precedence over OR):

  • (p1 == 'v1' OR p2 == 'v2' AND p3 == 'v3')

And also use groups to control the order of evaluation:

  • ((p1 == 'v1' OR p2 == 'v2') AND p3 == 'v3')

  • Same as (p3 == 'v3' AND (p1 == 'v1' OR p2 == 'v2'))

  • Same as (p3 == 'v3' AND p1 == 'v1' OR p3 == 'v3' AND p2 == 'v2')

  • US_IMAP_HOST_FIELDNAME: WARNING: this setting overrides the configuration done in the Mail Settings! TODO: add links when it’s done.
    The field/column where the user’s IMAP hostname can be found.

First, you must set the IMAP settings in the Mail Settings.

The expected value is the URI or hostname that will be parsed to overwrite:

  • SOGO_D_IMAP_SERVER

  • SOGO_D_IMAP_PORT

  • SOGO_D_IMAP_ENCRYPTION

If the URI is missing a value (port or encryption) or contains only the host, the port used will fall back to SOGO_D_IMAP_PORT and the encryption to SOGO_D_IMAP_ENCRYPTION.

If there is no value for a user, it will fall back to the IMAP configuration from the Mail Settings.

This setting exists for legacy reasons but will not be deprecated. SOGo 6’s mail configuration is mainly designed per domain and not per user, at least for now.

If you do want different IMAP servers per user, you should handle that in your Dovecot/Cyrus implementation by setting up a proxy server that receives all IMAP requests and redirects them to the correct IMAP server. That way, you only expose one IMAP server to SOGo 6.

If you’re starting a new project, do not use this setting. Only use it if you’re migrating from SOGo 5 and were already using it.

Settings for LDAP only

In the current SOGo 6 version, we cannot state any requirements about your LDAP server (version, schemas…​). However, all SOGo 5 behaviors have been or will be carried over.

Basic

  • US_LDAP_HOSTNAME: A string, the hostname or IP of your LDAP server.

  • US_LDAP_PORT: An integer, the port of your LDAP server. Defaults to 389.

  • US_LDAP_ENCRYPTION: Can be one of "None", "SSL/TLS" or "StartTLS". Mind the case:

    • "None": Will only use plain (unencrypted) communication

    • "SSL/TLS": Will only use encrypted communication

    • "StartTLS": Will start in plain mode, then negotiate an encrypted communication with the StartTLS command

Admin Bind

  • US_LDAP_BIND_DN: The admin bind DN. E.g.: "cn=admin,dc=example,dc=org"

  • US_LDAP_BIND_DN_PWD: The admin password

By default, the bind DN is used before each user search query. If you do not want that, see the setting US_LDAP_BIND_AS_USER, where the user binds as themselves before the search query. This changes what the search can see (an admin can generally see everything, while a user can be restricted to seeing only some users).

On a side note, an LDAP server can be configured to allow anonymous search requests. First, you may not want that. And if you do, SOGo will still perform the bind anyway, which should have no side effects.

Base DN

  • US_LDAP_BASE_DN: A string, the base DN, meaning the part of the DN common to all of your users. It is used for bind and search. It can use the wildcard %d to insert the user’s domain. Examples are given just below.

  • US_LDAP_BASE_DN_USE_TLD: Boolean, only useful if you’re using the wildcard %d in US_LDAP_BASE_DN. It states whether the top-level domain must be inserted:

    • If true, for the domain sogo.nu, %d will be sogo.nu.

    • If false, for the domain sogo.nu, %d will be sogo.

  • US_LDAP_ID: A string, the field whose value is the user login, which is added before the base DN. Defaults to 'uid'.

  • US_LDAP_BIND_FIELD: A list of strings, only useful if you cannot build a user’s DN from the base DN and the user login. SOGo will first run a search query to find the user’s DN, and only then bind with the credentials. There is an example below, under the IMPORTANT note.

Examples

For binding, which in SOGo 6 mainly means checking the credentials, LDAP expects a DN (Distinguished Name) and a password. The DN of a user is unique and the parameters above will build it.

A DN can look like this: uid=sogo1,ou=users,dc=sogo,dc=nu. The only information SOGo knows is the base DN and the user login. In this case the user is expected to log in with "sogo1":

  • US_LDAP_BASE_DN="ou=users,dc=sogo,dc=nu"

  • US_LDAP_ID="uid"

If the user DN is uid=sogo1@sogo.nu,ou=users,dc=sogo,dc=nu, the user will have to log in with sogo1@sogo.nu.

  • US_LDAP_BASE_DN="ou=users,dc=sogo,dc=nu"

  • US_LDAP_ID="uid"

If the DN looks like this: mail=sogo1@sogo.nu,ou=users,dc=sogo,dc=nu, the user will have to log in with sogo1@sogo.nu.

  • US_LDAP_BASE_DN="ou=users,dc=sogo,dc=nu"

  • US_LDAP_ID="mail"

As you can see, US_LDAP_BASE_DN is the part common to all your users, US_LDAP_ID sets the name of the field that will be added before the base DN, and the value is the user login.

For searching, the base DN is used. If a user searches for contacts matching "sog":

  • US_LDAP_BASE_DN="ou=users,dc=sogo,dc=nu"

  • The search query will try to find all users matching the word "sog" inside ou=users,dc=sogo,dc=nu.

That’s when the wildcard %d and US_LDAP_BASE_DN_USE_TLD become useful. If your users are separated by domain in their DN:

  • ou=sogo.nu,dc=example,dc=org

  • ou=sogo.net,dc=example,dc=org

You can partition your user search by setting US_LDAP_BASE_DN="ou=%d,dc=example,dc=org":

  • Users with the domain sogo.nu will only search and find users under ou=sogo.nu

  • Users with the domain sogo.net will only search and find users under ou=sogo.net

The parameter US_LDAP_BASE_DN_USE_TLD only defines how the placeholder %d works:

  • US_LDAP_BASE_DN_USE_TLD=True → sogo.nu gives sogo.nu

  • US_LDAP_BASE_DN_USE_TLD=False → sogo.nu gives sogo

Do not set US_LDAP_BASE_DN_USE_TLD=False if you have different domains that share the same name once the TLD is removed (E.g. sogo.nu and sogo.net), or only use it if you understand what that implies.

There are other ways to partition domains. It mainly depends on your LDAP structure. If you can do it directly with the DN, use the wildcard. If not, see US_DOMAIN_PARTITION.

If your DNs cannot be built from the base DN and the user login, see US_LDAP_BIND_FIELD. It will tell SOGo to first fetch the user DN before binding.

E.g.:

dn: uid=user13245,ou=users,dc=sogo,dc=nu
uid: sogo1
mail: sogo1@sogo.nu

And you want your users to log in with sogo1:

  • US_LDAP_BASE_DN="ou=users,dc=sogo,dc=nu"

  • US_LDAP_BIND_FIELD=["uid"]

SOGo will first search for the user with uid=sogo1, get the DN uid=user13245,ou=users,dc=sogo,dc=nu, and then bind as that user to check the credentials.

If you want your users to log in with sogo1@sogo.nu:

  • US_LDAP_BASE_DN="ou=users,dc=sogo,dc=nu"

  • US_LDAP_BIND_FIELD=["mail"]

If you want your users to log in with both sogo1 and sogo1@sogo.nu:

  • US_LDAP_BASE_DN="ou=users,dc=sogo,dc=nu"

  • US_LDAP_BIND_FIELD=["uid", "mail"]

Password Policy

NOT IMPLEMENTED YET

If your LDAP server supports the pwdPolicy object class, set the setting US_LDAP_PWD_POLICY to true. SOGo 6 will handle it and show more detailed warning or error messages when a user tries to log in or update their password.

The pwdPolicy is defined in the Internet-Draft draft-behera-ldap-password-policy-11, which has expired but seems to be widely adopted nonetheless.

  • US_LDAP_PWD_POLICY: Boolean, defaults to false.

  • US_LDAP_PWD_UPDATE_SAMBA: Boolean, defaults to false. Only set it to true if you allow your users to change their password and if you’re using Samba.

Others

  • US_LDAP_SCOPE: Can be 'base', 'one' or 'sub'. Defaults to sub. The search scope, see the LDAP documentation.

  • US_LDAP_QUERY_TIMEOUT (NOT IMPLEMENTED): Integer >= 0. The timeout of any query, in seconds. The value 0 means no limit.

  • US_LDAP_BIND_AS_USER: Boolean, defaults to false. When a search query is made for autocompletion, SOGo binds with the admin credentials. Set this to true if you want SOGo to use the user’s credentials instead.

  • US_LDAP_ATTR_FIELD: A list of strings. Tells SOGo which attributes to fetch when doing a search query. By default the value is ['*'], meaning all attributes.

As of now, if you enable the LDAP logger for debugging, the python-ldap library will print all queries and results. If US_LDAP_ATTR_FIELD=['*'], this also includes the userPassword field.

  • US_LDAP_GROUP_CLASS: A list of strings telling SOGo which objectClasses represent a group of users. Defaults to ['group', 'groupOfNames', 'groupOfUniqueNames', 'posixGroup'].

Settings for Database only

The database of your User Source can be completely different from SOGo 6’s own database. The database user must have read rights, and write rights if you enable the password update feature.

Basic

  • US_DB_TYPE: Can be either "postgresql" or "mysql".

  • US_DB_NAME: String, the name of your database.

  • US_DB_TABLE: String, the name of the table.

  • US_DB_USER: String, the username.

  • US_DB_PASS: String, the password.

  • US_DB_HOST: String, the hostname of the server.

  • US_DB_PORT: Integer, the port of your database. Defaults to 5432.

  • US_DB_ENCRYPTION (NOT IMPLEMENTED YET): Boolean, defaults to false. Set to true if your database uses SSL.

  • US_DB_ENCODING: String, defaults to 'utf8'. The encoding of your database.

Columns

  • US_DB_FIELD_PWD: String, defaults to 'c_password'. The name of the column where the passwords are stored.

  • US_DB_PREPEND_PWD_SCHEME: Boolean, defaults to false. If true, prepends the encryption scheme to the password (E.g. '{SHA-256}adsqhjgdsjqgdqs')

Password Policy

The password policy is used when:

  • Users change their password (if the feature is enabled)

  • After a successful login, if the admin has enabled the password strength check. See doc TODO

The settings are:

  • US_DB_PWD_POLICY: Boolean, defaults to false. Enables or disables the password policy.

  • US_DB_PWD_LEN_MIN: Integer, defaults to 4. Minimum length of a password.

  • US_DB_PWD_LEN_MAX: Integer, defaults to 0. Maximum length of a password. 0 means no limit. Must obviously be greater than US_DB_PWD_LEN_MIN (unless it is 0).

  • US_DB_PWD_UPPERCASE_MIN: Integer, defaults to -1. Required number of uppercase characters in the password. -1 means not required but allowed. 0 means they are not allowed.

  • US_DB_PWD_LOWERCASE_MIN: Integer, defaults to -1. Required number of lowercase characters in the password. -1 means not required but allowed. 0 means they are not allowed.

  • US_DB_PWD_DIGITS_MIN: Integer, defaults to -1. Required number of digits in the password. -1 means not required but allowed. 0 means they are not allowed.

  • US_DB_PWD_SPECIAL_MIN: Integer, defaults to -1. Required number of special characters in the password. -1 means not required but allowed. 0 means they are not allowed.

  • US_DB_PWD_SPECIAL_ALLOWED: String, defaults to %$&*(){}[]!?\/@#.,:;+=<>-_ The list of allowed special characters.

Contact Info

NOT IMPLEMENTED YET: only the cn and email addresses are returned and mapped

As you can see, only the Common Name and Mail are required. However, you can map any other columns/fields you have with the parameter US_MAPPING.

E.g. if you have this information:

dn: uid=user13245,ou=users,dc=sogo,dc=nu
uid: sogo1
mail: sogo1@sogo.nu
department: R&D
job: Lead Dev
US_MAPPING = {
    "job_title": "job",
    "department": "department"
}

This information will be visible to the user on their own profile page, and to others if the User Source is an Address Book.

Auth and Address Book

A User Source can be used for Authentication and/or be an Address Book.

Authentication is used when SOGO_D_AUTH_TYPE is set to plain (See Auth Setting). If several User Sources are configured for authentication, SOGo 6 will try the user’s login against each source until one matches. If no User Source is set for authentication, SOGo will throw an error.

Being an Address Book means users will:

  • See a Global Address Book in their contacts view

  • Be able to share their mail folders, calendars and address books with others

  • Have the autocompletion feature when writing a mail, adding an attendee to an event, etc.

AUTH

  • US_CAN_AUTH: Boolean. Users of this User Source can log in.

  • US_PWD_ALGO: String. Mainly used for SQL User Sources. If your passwords are stored with the scheme prepended like this {SHA256.HEX}dg..dsqf, SOGo will detect it and use the proper algorithm. This means you can have different algorithms in your User Source if the scheme is prepended. If this is not the case, set this value to the proper algorithm. The supported algorithms and values are listed below. With LDAP, this parameter is only used when updating a password if your server does not support the Password Modify Extended Operation.

Currently supported algorithms. Note that some of them are here for legacy reasons and are not recommended:

  • 'none', 'plain',

  • 'crypt',

  • 'md5','md5-crypt',

  • 'smd5', 'cram-md5', 'ldap-md5',

  • 'sha', 'sha.hex'

  • 'sha256', 'sha256-crypt', 'ssha256', 'sha256.hex',

  • 'sha512', 'sha512-crypt', 'ssha512', 'sha512.hex',

  • 'blf-crypt',

  • 'PBKDF2',

  • 'argon2i', 'argon2id'

ADDRESS BOOK

  • US_IS_ADDRESSBOOK: Boolean, enables autocompletion and sharing.

  • US_DISPLAY_NAME: String, the name of this address book as seen by users. Falls back to US_NAME if not set.

  • US_SEARCH_FIELD: A list of strings. By default SOGo searches on US_FIELD_UID, US_FIELD_CN and US_MAIL[0]. If you want to add more fields, set a list here, e.g. ["displayName", "nickname"].

  • US_AUTO_SEARCH: NOT IMPLEMENTED YET

  • US_EXTRA_CONTACT_INFO: NOT IMPLEMENTED YET

  • US_HIDDEN_USER: A list of strings. If you have specific users you want to hide from others, add their US_FIELD_UID values here, e.g. ["super-admin"].

With SOGo 6, you can set more precisely who can see whom. There are two ways of doing this: US_UNIT_FIELD or US_DOMAIN_PARTITION. If both are set, only US_UNIT_FIELD will be used.

  • US_UNIT_FIELD: String. Name of the column/field. Users with the same value for this column/field will see each other, and not the others.

It’s the equivalent of the SOGo 5 parameter DomainFieldName for SQL User Sources, now extended to LDAP too.

E.g.

dn: uid=sogo1,ou=users,dc=sogo,dc=nu
uid: sogo1
mail: sogo1@sogo.nu
company: firma
dn: uid=sogo2,ou=users,dc=sogo,dc=nu
uid: sogo2
mail: sogo2@example.org
company: firma
dn: uid=sogo3,ou=users,dc=sogo,dc=nu
uid: sogo3
mail: sogo3@pro.org
company: external
dn: uid=sogo4,ou=users,dc=sogo,dc=nu
uid: sogo4
mail: sogo4@pro.org
company: external

If you set US_UNIT_FIELD: "company", sogo1 and sogo2 will only see each other, and sogo3 and sogo4 will also only see each other.

For LDAP, keep in mind that this only works on fields that are attributes of the entry, not on values that only appear in the DN. In our case, the ou component won’t work as it only appears in the DN. See US_LDAP_BASE_DN.

  • US_DOMAIN_PARTITION: Integer. This one uses the user’s mail domain. It has 3 modes:

    • 0 → (default) everyone can see everyone

    • 1 → users can only see users with the same mail domain

    • -1 → nobody can see anyone, except the domains in US_DOMAIN_VISIBLE

  • US_DOMAIN_VISIBLE: A list of strings.

    • If US_DOMAIN_PARTITION == 1, list of mail domains that will still be seen by all users

    • If US_DOMAIN_PARTITION == -1, list of mail domains that will still be seen by all users

    • If US_DOMAIN_PARTITION == 0, no effect

  • US_DOMAIN_NOT_VISIBLE: A list of strings.

    • If US_DOMAIN_PARTITION == 1, no effect

    • If US_DOMAIN_PARTITION == -1, no effect

    • If US_DOMAIN_PARTITION == 0, list of mail domains that will be hidden from everyone