Skip to content

LDAP Setup and Configuration

This functionality is available in the Enterprise and On-Premise versions. This feature is guaranteed to work with: OpenLDAP or FreeIPA.

Creating an LDAP Connection

To create an LDAP connection, go to the administrator panel, open the SSO Settings section, and in the LDAP Setup section, click the Create button.

Creating an LDAP connection

Configuring the LDAP Connection

When creating a new LDAP connection or editing an existing one, you must fill in the following required fields:

Warning!

Do not use LDAP attributes that return values in hexadecimal format. This can lead to incorrect data processing in the application.

  • Name - the name of the LDAP connection, which will be displayed in the administrator panel, on the LDAP login page, or on the group synchronization page
  • LDAP server address - the address where the LDAP server is located (if it is running locally, specify localhost)
  • LDAP server port - the port of the LDAP server (default port is 389)
  • User DN - DN of the administrator or user used to search LDAP
  • User password - password of the user used to search LDAP. The password must be re-entered when editing an existing connection.
  • BaseDn - the DN of the LDAP server for searching users
  • LDAP attribute for user's email - LDAP attributes that are mapped to the user's email. For proper LDAP integration, it is recommended to use an email like mail@domain.ru in this attribute. You can specify multiple attributes separated by a semicolon without spaces.
  • LDAP attribute for user's login - LDAP attributes that are mapped to the user's login. These attributes must be unique for each user. One of these attributes is used for system login. You can specify multiple attributes separated by a semicolon without spaces. When logging in to GitFlic for the first time, a user will be created using the first non-empty attribute from this field as the login.
  • User UID - a unique and immutable LDAP attribute required to identify the user.

The User UID field is available in GitFlic starting from version 4.0.0. After upgrading from an older version, this field will automatically be filled with the first value from the LDAP attribute for user's login field. For correct system operation, it is recommended to manually set uid as the attribute containing a globally unique user identifier, for example, sAMAccountName. Please note that at the moment, GitFlic does not support such attributes from Active Directory as objectGUID and entryUUID.

The fields described below are not required to create an LDAP connection, but filling them in can make user synchronization more complete:

  • LDAP attribute for user's first name - attribute for filling in the user's first name. If the field is not filled in, the default attribute is givenName
  • LDAP attribute for user's last name - attribute for filling in the user's last name. If the field is not filled in, the default attribute is sn
  • Description of the LDAP connection - description that will be displayed in the GitFlic administrator panel

In addition, the LDAP connection settings include extra parameters:

  • Use SSL connection (ldaps) - allows the use of SSL connection for LDAP. More details can be found here.
  • Authenticate user if the LDAP server is unavailable - allows users to log in using previously successfully entered data if the LDAP server is unavailable. More details can be found here
  • Request limit - indicates the server-side limit on the number of objects retrieved in a single request. Default is 1000
  • Ignore case when checking login - allows logging in to the service regardless of login case

After filling in the required fields, click the "Create" button. After successful creation, you will be redirected to a page listing all created LDAP connections.

Configuring the LDAP connection

Logging in with LDAP

On the login page, select the LDAP section. After entering the credentials provided by your administrator, click the "Login" button.

Logging in with LDAP

LDAP Group Synchronization

This functionality is available in the Enterprise version

LDAP Group Synchronization Setup

To activate LDAP group synchronization with teams or companies in GitFlic, use the "Enable group synchronization" setting. To create an LDAP connection with group synchronization enabled, fill in the required fields:

  • GroupDN - the DN of the LDAP server for searching groups
  • User id attribute - the attribute indicating the id of the group member
  • Group name attribute - the attribute indicating the name of the group
  • Group member search attribute - the group attribute listing all the ids of its members

For more flexible group synchronization setup, you can use optional filters:

  • Group search filters - a filter that specifies the group search

LDAP group synchronization setup

Applying LDAP Group Synchronization

After configuring the LDAP connection with all necessary parameters for group synchronization, administrators of teams and companies will see an LDAP Synchronization tab available.

Groups specified in the LDAP connection settings do not appear in GitFlic immediately — the built-in mechanism updates their information once an hour. The Synchronize LDAP groups button lets you skip the wait. Clicking this button performs synchronization, and the current LDAP group information becomes available in GitFlic. Therefore, it is recommended to always start working with group synchronization by clicking this button.

The LDAP server selector allows you to choose the specific connection whose groups need to be added to a team or company. There are two synchronization methods:

  • LDAP group cn - select a group from the list automatically formed based on the LDAP group synchronization settings
  • LDAP user filter - form a group using the specified filter

After selecting a group using either method, you must choose a role that all users in the specified group will receive when it is synchronized with a team or company.

To add users from the selected group to all projects of the team or company being synchronized, activate the Add synchronized users to company projects toggle. Once the toggle is enabled, a selector will appear where you need to select the role users will be assigned in the projects. You can select both a basic and a custom role.

  • If a user is synchronized to team or company projects in several groups, they will be assigned the highest role. When comparing custom roles, their base roles are compared.

    For example, a user is in group1, which is synchronized with the option to add to projects as a Guest, and in group2, which is synchronized with a custom role whose base role is Developer. In this case, the user will be added to the project with the custom role, since its base role Developer is higher than Guest (the set of permissions in the custom role does not matter).

  • If a user is synchronized to team or company projects in several groups with different custom roles that have the same base role, the project will use the role from the group that was synchronized last.

After clicking the Add button, the group appears in the Active Synchronizations section. After adding enough groups, click the Synchronize button. All group members will receive the specified roles in the team or company.

  • If a user is present in several groups, the highest role will be assigned during synchronization.

    For example, a user is in group1, synchronized with the Guest role, and in group2, synchronized with the Developer role. After clicking the Synchronize button, this user will receive the Developer role in the team or company being synchronized.

  • If synchronization is performed in an entity owned by a company or team, the user will be added to the parent company as a Guest.

    For example, synchronization is performed in a subgroup. Then, during synchronization, the user will be added to the company that is the parent for the team in which the subgroup was created.

  • Before synchronizing groups, you must log in with the LDAP user account to create a profile in GitFlic.

Applying LDAP group synchronization

Managing Synchronized Users

Users added to a team or company using group synchronization are locked for changes in the Access Management section. To change the role or remove such users, you must unlock them using the lock-shaped button. After re-synchronization, the roles of these users will not be changed.

  • If you remove a user from a team or company after unlocking, on the next synchronization this user will regain access with the role assigned to their group. To completely remove a user, it is recommended to delete them from the LDAP server configuration and re-synchronize both the LDAP connection and the LDAP groups.
  • If you need to restore the role with which the user's group was added to the team or company, lock the user again and click the Synchronize button once more.

Managing synchronized users

Additional Information about Working with LDAP

  • It is recommended to specify the gitFlic.aes.secret parameter in application.properties, which is used as the password for encrypting the LDAP database password. You can set your own password or leave it blank; in this case, the default password is used (not secure).

  • The server stores a password hash, which is only used if the "Authenticate user if LDAP server is unavailable" option is enabled. When the user logs in and the LDAP server is unavailable, GitFlic checks the hash in the database and the entered password. If this option is disabled, when the server is unavailable, the account is blocked: working with the project via SSH will not be possible, tokens will become invalid, etc.

  • When working over https, with each request to GitFlic (clone, push, pull, etc.), GitFlic contacts the LDAP server and, if the LDAP server is unavailable, the user is blocked. When working via SSH, this check is not performed, i.e., if the user is blocked in the LDAP system, access to the web interface and working via http in git will not be possible, but if the user continues to work via SSH, their GitFlic account will not be blocked.

  • GitFlic has a worker configured to check the LDAP server for users every hour. The process performs the following access checks:

    • Checks that the user is still present in LDAP
    • If the LDAP server is Active Directory, make sure the user is active (not blocked/disabled). In Active Directory, a user is marked as disabled/blocked if bit 2 is set in the user account control attribute (userAccountControl:1.2.840.113556.1.4.803). (bitmask search in LDAP)

  • For urgent blocking of users, you can manually block a user in the GitFlic administrator panel.

  • The first and last name fields are filled from the givenName (first name) and sn (last name) attributes. After the first login, these parameters can be manually overridden.

Adding a Local Certificate for LDAPS

If you need to use a local certificate for LDAPS, in addition to adding it to the server running GitFlic, you also need to import the certificate into the JRK. If you do not do this, when enabling Use SSL connection (ldaps) in the LDAP settings, the logs will show the message Ошибка при создании LDAP подключения: simple bind failed. For certificates validated through global certification authorities, this setting is not required.

Ubuntu

  • Find where the Java certificate folder is located. To find the $JAVA_HOME location, run:
readlink -f /usr/bin/java | sed "s\:bin/java::"

cacerts is located in lib/security/cacerts. The line below can be used as a variable with the correct path to cacerts.

\$(readlink -f /usr/bin/java | sed "s\:bin/java::")lib/security/cacerts
  • Import the certificate.
keytool -import -alias <alias> -file \<file\_path> -keystore \$JAVA\_HOME/lib/security/cacerts

The example below uses: * -alias ya.ru * Full certificate path -file ~/tmp/ya.crt * Path to JRK certificates -keystore /usr/lib/jvm/java-18-openjdk-amd64/lib/security/cacerts

keytool -import -alias ya.ru -file \~/tmp/ya.crt  -keystore /usr/lib/jvm/java-18-openjdk-amd64/lib/security/cacerts

When prompted for the password Enter keystore password:, just press Enter or use the password changeit

You can view the certificates with the command:

keytool -list -v -keystore \$(readlink -f /usr/bin/java | sed "s\:bin/java::")lib/security/cacerts

Automated translation!

This page was translated using automatic translation tools. The text may contain inaccuracies.