# User lookup via OpenSSH's AuthorizedPrincipalsCommand

> 原文：[https://docs.gitlab.com/ee/administration/operations/ssh_certificates.html](https://docs.gitlab.com/ee/administration/operations/ssh_certificates.html)

*   [Why use OpenSSH certificates?](#why-use-openssh-certificates)
*   [Setting up SSH certificate lookup via GitLab Shell](#setting-up-ssh-certificate-lookup-via-gitlab-shell)
*   [Principals and security](#principals-and-security)
*   [Interaction with the `authorized_keys` file](#interaction-with-the-authorized_keys-file)
*   [Other security caveats](#other-security-caveats)
*   [Disabling the global warning about users lacking SSH keys](#disabling-the-global-warning-about-users-lacking-ssh-keys)

# User lookup via OpenSSH’s AuthorizedPrincipalsCommand[](#user-lookup-via-opensshs-authorizedprincipalscommand "Permalink")

> [在](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/19911) GitLab 社区版 11.2 中[可用](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/19911) .

GitLab 的默认 SSH 身份验证要求用户上载 SSH 公钥，然后才能使用 SSH 传输.

在集中式（例如公司）环境中，这在操作上可能会很麻烦，特别是如果 SSH 密钥是颁发给用户的临时密钥，例如在发行后 24 小时过期的临时密钥.

在这种设置中，需要一些外部自动化过程来不断将新密钥上载到 GitLab.

> **警告：需要** OpenSSH 6.9+版本，因为该版本引入了`AuthorizedPrincipalsCommand`配置选项. 如果使用 CentOS 6，则可以[按照以下说明](fast_ssh_key_lookup.html#compiling-a-custom-version-of-openssh-for-centos-6)来编译最新版本.

## Why use OpenSSH certificates?[](#why-use-openssh-certificates "Permalink")

通过使用 OpenSSH 证书，有关 GitLab 上用户拥有密钥的所有信息都被编码在密钥本身中，并且 OpenSSH 自身保证用户无法伪造此信息，因为他们需要访问私有 CA 签名密钥.

正确设置后，就不需要完全将用户 SSH 密钥上传到 GitLab.

## Setting up SSH certificate lookup via GitLab Shell[](#setting-up-ssh-certificate-lookup-via-gitlab-shell "Permalink")

如何完全设置 SSH 证书不在本文档的范围之内. 请参阅[OpenSSH 的`PROTOCOL.certkeys`](https://cvsweb.openbsd.org/cgi-bin/cvsweb/src/usr.bin/ssh/PROTOCOL.certkeys?annotate=HEAD)了解其工作方式，例如[RedHat 的文档](https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/6/html/deployment_guide/sec-using_openssh_certificate_authentication) .

我们假设您已经设置了 SSH 证书，并且已经将 CA 的`TrustedUserCAKeys`添加到了`sshd_config` ，例如：

```
TrustedUserCAKeys /etc/security/mycompany_user_ca.pub 
```

通常，在这种设置中， `TrustedUserCAKeys`不会在" `Match User git`范围内，因为它也将用于系统登录到 GitLab 服务器本身，但是您的设置可能会有所不同. 如果 CA 仅用于 GitLab，请考虑将其放在" `Match User git`部分（如下所述）.

由该 CA 颁发的 SSH 证书**务必**具有与该用户在 GitLab 上的用户名相对应的"密钥 ID"，例如（为简洁起见，省略了一些输出）：

```
$ ssh-add -L | grep cert | ssh-keygen -L -f -

(stdin):1:
        Type: ssh-rsa-cert-v01@openssh.com user certificate
        Public key: RSA-CERT SHA256:[...]
        Signing CA: RSA SHA256:[...]
        Key ID: "aearnfjord"
        Serial: 8289829611021396489
        Valid: from 2018-07-18T09:49:00 to 2018-07-19T09:50:34
        Principals:
                sshUsers
                [...]
        [...] 
```

从技术上讲，这不是完全正确，例如，它可以`prod-aearnfjord`如果它是你通常会登录到服务器作为一个 SSH 证书`prod-aearnfjord`用户，但你必须指定自己的`AuthorizedPrincipalsCommand`做映射，而不是使用我们提供的默认.

重要的是， `AuthorizedPrincipalsCommand`必须能够以某种方式从"密钥 ID"映射到 GitLab 用户名，我们提供的默认命令假设两者之间存在 1 = 1 的映射，因为这样做的重点是允许我们从密钥本身提取 GitLab 用户名，而不是依赖默认的公共密钥到用户名的映射.

然后，在您的`sshd_config`为`git`用户设置`AuthorizedPrincipalsCommand` . 希望您可以使用 GitLab 随附的默认值：

```
Match User git
    AuthorizedPrincipalsCommandUser root
    AuthorizedPrincipalsCommand /opt/gitlab/embedded/service/gitlab-shell/bin/gitlab-shell-authorized-principals-check %i sshUsers 
```

该命令将发出类似于以下内容的输出：

```
command="/opt/gitlab/embedded/service/gitlab-shell/bin/gitlab-shell username-{KEY_ID}",no-port-forwarding,no-X11-forwarding,no-agent-forwarding,no-pty {PRINCIPAL} 
```

其中`{KEY_ID}`是传递给脚本的`%i`参数（例如`aeanfjord` ），而`{PRINCIPAL}`是传递给脚本的主体（例如`sshUsers` ）.

您将需要自定义其中的`sshUsers`部分. 对于可以登录到 GitLab 的所有用户，它应该是一定要保证是密钥的一部分的主体，或者您必须提供一个主体列表，其中一个将提供给用户，例如：

```
 [...]
    AuthorizedPrincipalsCommand /opt/gitlab/embedded/service/gitlab-shell/bin/gitlab-shell-authorized-principals-check %i sshUsers windowsUsers 
```

## Principals and security[](#principals-and-security "Permalink")

您可以根据需要提供任意数量的委托人，这些委托人将变成多行`authorized_keys`输出，如`sshd_config(5)`中的`AuthorizedPrincipalsFile`文档中所述.

通常，将`AuthorizedKeysCommand`与 OpenSSH 一起使用时，主体是允许登录到该服务器的某个"组". 但是，在 GitLab 中，它仅用于满足 OpenSSH 的要求，我们实际上只关心"密钥 ID"的正确性. 一旦解压缩，GitLab 将为该用户强制执行自己的 ACL（例如，用户可以访问哪些项目）.

因此，例如对用户接受的内容过分慷慨是可以的，因为如果用户（例如）根本无法访问 GitLab，它只会出错并显示一条有关该用户无效的消息.

## Interaction with the `authorized_keys` file[](#interaction-with-the-authorized_keys-file "Permalink")

SSH 证书可以与`authorized_keys`文件结合使用，并且如果按照上述`authorized_keys`文件的配置进行设置，它仍将作为后备.

这是因为，如果`AuthorizedPrincipalsCommand`无法对用户进行身份验证，则 OpenSSH 将回退到`~/.ssh/authorized_keys` （或`AuthorizedKeysCommand` ）上.

因此，仍然有理由结合使用["在数据库中快速查找授权的 SSH 密钥"](fast_ssh_key_lookup.html)方法. 由于您将对所有普通用户使用 SSH 证书，并且如果使用密钥，则依靠`~/.ssh/authorized_keys`后备来部署密钥.

但是您可能会发现没有必要这样做，因为所有普通用户都将使用快速的`AuthorizedPrincipalsCommand`路径，并且只有自动部署密钥访问才会落在`~/.ssh/authorized_keys` ，或者您还有更多的密钥可以使用普通用户（尤其是续订的用户）比您拥有的部署密钥.

## Other security caveats[](#other-security-caveats "Permalink")

用户仍然可以通过手动将 SSH 公钥上载到他们的配置文件中来绕过 SSH 证书身份验证，依靠`~/.ssh/authorized_keys`后备来对其进行身份验证. 当前没有阻止它的功能， [但是有一个添加它的公开请求](https://gitlab.com/gitlab-org/gitlab/-/issues/23260) .

当前，可以通过提供一个自定义的`AuthorizedKeysCommand`来破解这种限制，该命令可检查从`gitlab-shell-authorized-keys-check`返回的已发现密钥 ID `gitlab-shell-authorized-keys-check`为部署密钥（应拒绝所有非部署密钥）.

## Disabling the global warning about users lacking SSH keys[](#disabling-the-global-warning-about-users-lacking-ssh-keys "Permalink")

默认情况下，GitLab 将向尚未将 SSH 密钥上载到其配置文件的用户显示"您将无法通过 SSH 推送或推送项目代码"警告.

This is counterproductive when using SSH certificates, since users aren’t expected to upload their own keys.

要全局禁用此警告，请转到"应用程序设置->帐户和限制设置"，然后禁用"显示用户添加 SSH 密钥消息"设置.

This setting was added specifically for use with SSH certificates, but can be turned off without using them if you’d like to hide the warning for some other reason.