Skip to main content
Version: v41

GitLab Integration

You can integrate PrivX with GitLab to authenticate git commands using PrivX SSH certificates.

Overview​

The integration requires:

Both PrivX and GitLab must be configured in order to support certificate-based authentication.

GitLab Configuration Steps​

  1. Configure GitLab to accept certificate authentication from PrivX:

    • Add the following Match block to the SSH server configuration (typically at /etc/ssh/sshd_config or /assets/sshd_config):

      Match User git
          TrustedUserCAKeys /etc/ssh/privx_ca.pub
          AuthorizedPrincipalsCommandUser root
          AuthorizedPrincipalsCommand /opt/gitlab/embedded/service/gitlab-shell/bin/gitlab-shell-authorized-principals-check %i PrivXUsers

    • Set the PrivX CA certificate as a trusted CA key:

      To obtain the PrivX CA certificate from the PrivX GUI, go to Administration→Deployment→Deploy and Configure SSH target hosts, select Configure manually, and copy the CA certificate shown in Step 5. Then, save the certificate content to /etc/ssh/privx_ca.pub on the GitLab Server.

    • Restart the SSH service of the GitLab server to apply the configuration changes.

  2. Configure GitLab user accounts for PrivX access:

    As defined in PrivX's OpenSSH certificate template, the Windows Username attribute of each user is set as the certificate Key ID for GitLab authentication via SSH.

    Ensure that:

    • One or more GitLab user account exist for the PrivX users.
    • The GitLab usernames match the PrivX users' Windows Username attribute.

    GitLab also supports LDAP integration, which can help synchronize user accounts between PrivX and GitLab.

    info

    You may customize certificate templates to use different PrivX user attributes instead of the default Windows Username. For details, see SSH Certificate Templates.

PrivX Configuration Steps​

  1. Create a PrivX role for GitLab access:

    In the PrivX GUI, go to Administration→Roles, then click Add Role.

    Define the role name, mapping rules, and access restrictions as needed, then save the role.

  2. Add GitLab as a connection target (host):

    In the PrivX GUI, navigate to Administration→Hosts, and click Add Host.

    Provide the address and host key of your GitLab server. Under Certificate template, select GitLab:

    Then, add an account to the host with the following settings:

    • Account type: Explicit
    • Username: git
    • Password: Leave empty (PrivX will use certificate-based authentication)
    • Roles: Assign the GitLab access role you created

    Click Save to finish adding the host.

    info

    Instead of using an Explicit account type, you can assign a Directory account. This requires additional configuration. For details, see Active Directory Integration.

  3. Grant GitLab access to users:

    For each PrivX user who needs access to GitLab:

  4. Test SSH access through PrivX:

    From a PrivX user machine, use the following command to test the connection, replacing {GITLAB_SERVER_ADDR}, {PRIVX_SERVER_ADDR}, and /path/to/your/.ssh/private_key with appropriate values:

    # If you provided the Bastion configuration options in the client's SSH configuration:
    ssh git@{GITLAB_SERVER_ADDR}

    # If you haven't, provide the configuration options in the 'ssh' command:
    ssh -o "IdentityFile /path/to/your/.ssh/private_key" \
        -o "HostKeyAlias {PRIVX_SERVER_ADDR}:2222" \
        -o "ProxyCommand nc -X connect -x {PRIVX_SERVER_ADDR}:1080 %h %p" \
        git@{GITLAB_SERVER_ADDR}

    Expected output (considering that the GitLab user that logged in is jdoe):

    PTY allocation request failed on channel 0
    Welcome to GitLab, @jdoe!
    Connection to {GITLAB_SERVER_ADDR} closed.

    Once verified, you can start using Git:

    git clone git@{GITLAB_SERVER_ADDR}:git-test-project/test-repo.git

Active Directory Integration​

When multiple users need access to GitLab, manually creating an Explicit host account for each user can be inefficient. Instead, you can configure PrivX to use Directory accounts mapped from an external directory, such as Active Directory (AD), and assign them dynamically to GitLab users.

This section explains how to modify Steps 2 and 3 of the previous PrivX Configuration to support Active Directory integration.

Steps for AD Integration​

  • Step 2: Add the GitLab host as a connection target, just as before. Then, when adding an account to the host, use the following settings:

    • Account type: Directory
    • Username Attribute: git_account
    • Password: Leave empty
    • Roles: Assign the GitLab access role you created

  • Step 3: Update the GitLab access role to automatically include your AD users:

    • Go to the role details, and add a Mapping Rule that matches the appropriate AD users.
    • Ensure users can still connect via the PrivX SSH Bastion using ProxyCommand, as explained in Connecting Directly Using ProxyCommand.

In addition to these changes, two other configuration steps are required:

  1. Set a user attribute in AD for SSH login:

    Ensure each relevant AD user has an attribute whose value is git. This will be used as the SSH username when connecting to GitLab.

  2. Map the AD attribute in PrivX:

    In the PrivX GUI, go to Administration→Directories, select your AD directory, then go to Attribute Mapping and map the AD attribute (e.g., comment) containing the value git to the internal PrivX attribute git_account (e.g., comment=git_account).

    info

    You may also need to update the LDAP Attributes Filter in the Role Store settings to include the attribute used for git_account. To do this, go to Administration→Settings, then select Role Store from the dropdown menu and change the necssary settings.

After performing these steps, continue with the normal configuration, as explained in the previous section.