极狐 GitLab

在极狐GitLab中使用SSH密钥

Tier: 基础版，专业版，旗舰版

Offering: JihuLab.com，私有化部署

在极狐GitLab中使用SSH密钥

使用 SSH 密钥可以安全地向极狐GitLab 进行身份验证，无需每次推送或拉取代码时输入用户名和密码。

要在极狐GitLab 中使用 SSH 密钥，你必须：

  1. 在本地系统上生成 SSH 密钥对。
  2. 将你的 SSH 密钥添加到极狐GitLab 账户。
  3. 验证与极狐GitLab 的连接。

有关高级 SSH 密钥配置的信息， 请参见高级 SSH 密钥配置。

什么是 SSH 密钥#

SSH 使用两个密钥，一个公钥和一个私钥。

  • 公钥可以分发。
  • 私钥应受到保护。

上传公钥不会泄露机密数据。当你需要复制或上传 SSH 公钥时，请确保不会意外复制或上传你的私钥。

你可以使用私钥来签署提交， 这会让你的极狐GitLab 使用和数据更加安全。 然后任何人都可以使用你的公钥验证此签名。

有关详细信息，请参见非对称加密，也称为公钥加密。

前提条件#

要通过 SSH 与极狐GitLab 通信，你需要：

  • OpenSSH 客户端，GNU/Linux、macOS 和 Windows 10 上已预装。
  • SSH 6.5 或更高版本。早期版本使用了不安全的 MD5 签名。

要查看系统上安装的 SSH 版本，请运行 ssh -V。

支持的 SSH 密钥类型#

版本历史
  • 最大 RSA 密钥长度在极狐GitLab 16.3 中已更改。

要与极狐GitLab 通信，可以使用以下 SSH 密钥类型：

算法说明
ED25519（首选）比 RSA 密钥更安全且性能更好。在 OpenSSH 6.5（2014）中引入，适用于大多数操作系统。可能并非所有 FIPS 系统都完全支持。
ED25519_SK要求本地客户端和极狐GitLab 服务器上的 OpenSSH 均为 8.2 或更高版本。
ECDSA_SK要求本地客户端和极狐GitLab 服务器上的 OpenSSH 均为 8.2 或更高版本。
RSA安全性低于 ED25519。如果使用，极狐GitLab 建议密钥大小至少为 4096 位。由于 Go 的限制，最大密钥长度为 8192 位。默认密钥大小取决于你的 ssh-keygen 版本。
ECDSA与 DSA 相关的安全问题同样适用于 ECDSA 密钥。

检查现有的 SSH 密钥对#

在创建密钥对之前，请检查是否已存在密钥对。

  1. 转到你的主目录。

  2. 进入 .ssh/ 子目录。如果 .ssh/ 子目录不存在， 说明你不在主目录中，或者你之前未使用过 ssh。 如果是后者，则需要生成 SSH 密钥对。

  3. 查看是否有符合以下任一格式的文件：

    算法公钥私钥
    ED25519（首选）id_ed25519.pubid_ed25519
    ED25519_SKid_ed25519_sk.pubid_ed25519_sk
    ECDSA_SKid_ecdsa_sk.pubid_ecdsa_sk
    RSA（至少 4096 位密钥大小）id_rsa.pubid_rsa
    DSA（已弃用）id_dsa.pubid_dsa
    ECDSAid_ecdsa.pubid_ecdsa

生成 SSH 密钥对#

如果你还没有 SSH 密钥对，请生成新的：

  1. 打开终端。

  2. 使用密钥类型运行 ssh-keygen -t，并附带可选注释以帮助以后识别该密钥。 一个常见的做法是使用你的电子邮件地址作为注释。 注释会包含在 .pub 文件中。

    例如，对于 ED25519：

    shell
    ssh-keygen -t ed25519 -C "<comment>"

    对于 4096 位 RSA：

    shell
    ssh-keygen -t rsa -b 4096 -C "<comment>"

  3. 按 Enter。显示类似于以下的输出：

    plaintext
    Generating public/private ed25519 key pair.
Enter file in which to save the key (/home/user/.ssh/id_ed25519):

  4. 接受建议的文件名和目录，除非你要生成部署密钥 或希望保存到用于存储其他密钥的特定目录。

    你也可以将 SSH 密钥对专门用于特定主机。

  5. 指定密码短语：

    plaintext
    Enter passphrase (empty for no passphrase):
Enter same passphrase again:

    将显示确认信息，包括你的文件存储位置。 同时生成公钥和私钥。

  6. 将私有的 SSH 密钥添加到 ssh-agent。

    例如，对于 ED25519：

    shell
    ssh-add ~/.ssh/id_ed25519

将 SSH 密钥添加到极狐GitLab 账户#

版本历史
  • 建议的默认密钥过期日期在极狐GitLab 15.4 中引入。
  • SSH 密钥的用途类型在极狐GitLab 15.7 中添加。

要通过 SSH 使用极狐GitLab，请将你的公钥复制到极狐GitLab 账户。极狐GitLab 无法 访问你的私钥。

添加 SSH 密钥时，极狐GitLab 会将其与已知的泄露密钥列表进行核对。 无法添加泄露的密钥，因为相关的私钥是公开的，可能被用来访问账户。此限制无法配置。

如果你的密钥被阻止，请生成新的 SSH 密钥对。

要将 SSH 密钥添加到极狐GitLab 账户：

  1. 复制你的公钥文件内容。你可以手动完成或使用脚本。

    在这些示例中，将 id_ed25519.pub 替换为你的文件名。例如，对于 RSA，使用 id_rsa.pub。

shell
   tr -d '\n' < ~/.ssh/id_ed25519.pub | pbcopy
shell
   xclip -sel clip < ~/.ssh/id_ed25519.pub
shell
   cat ~/.ssh/id_ed25519.pub | clip
  1. 登录极狐GitLab。
  2. 在右上角，选择你的头像。
  3. 选择 编辑配置文件。
  4. 在左侧边栏中，选择 访问权限 > SSH 密钥。
  5. 选择 添加新密钥。
  6. 在 密钥 框中，粘贴你的公钥内容。 如果你手动复制了密钥，请确保复制整个密钥， 它以 ssh-rsa、ssh-dss、ecdsa-sha2-nistp256、ecdsa-sha2-nistp384、ecdsa-sha2-nistp521、 ssh-ed25519、sk-ecdsa-sha2-nistp256@openssh.com 或 sk-ssh-ed25519@openssh.com 开头，并可能以注释结尾。
  7. 在 标题 框中，输入描述，例如 Work Laptop 或 Home Workstation。
  8. 可选。选择密钥的 用途类型。它可用于 Authentication 或 Signing 或两者。Authentication & Signing 是默认值。
  9. 可选。更新 过期日期 以修改默认过期日期。有关更多信息，请参见 SSH 密钥过期。
  10. 选择 添加密钥。

验证 SSH 连接#

验证你的 SSH 密钥是否已正确添加，以及能否连接到极狐GitLab实例：

  1. 为确保你连接到正确的服务器，请标识 SSH 主机密钥指纹：
    • 对于 JihuLab.com，请参见 SSH 主机密钥指纹文档。
    • 对于私有化部署的极狐GitLab，请查看 https://gitlab.example.com/help/instance_configuration#ssh-host-keys-fingerprints 其中 gitlab.example.com 是极狐GitLab实例 URL。
  2. 打开终端并运行此命令：
    • 对于 JihuLab.com，使用 ssh -T git@gitlab.com。
    • 对于私有化部署的极狐GitLab，使用 ssh -T git@gitlab.example.com 其中 gitlab.example.com 是极狐GitLab实例 URL。

默认情况下，连接使用 git 用户名，但私有化部署的极狐GitLab管理员可以更改用户名。

  1. 首次连接时，你可能需要验证极狐GitLab 主机的真实性。 如果看到以下类似消息，请按照屏幕上的提示操作：

    plaintext
    The authenticity of host 'gitlab.example.com (35.231.145.151)' can't be established.
ECDSA key fingerprint is SHA256:HbW3g8zUjNSksFbqTiUWPWg2Bq1x8xdGUrliXFzSnUw.
Are you sure you want to continue connecting (yes/no)?

    你应该会收到一条欢迎消息。

    plaintext
    Welcome to GitLab, <username>!

    如果没有出现该消息，你可以排查 SSH 连接问题。

查看你的 SSH 密钥#

要查看你账户的 SSH 密钥：

  1. 在右上角，选择你的头像。
  2. 选择 编辑配置文件。
  3. 在左侧边栏中，选择 访问权限 > SSH 密钥。

你现有的 SSH 密钥会列在页面底部。信息包括：

  • 密钥的标题
  • 公钥指纹
  • 允许的用途类型
  • 创建日期
  • 上次使用日期
  • 过期日期

移除 SSH 密钥#

你可以吊销或删除你的 SSH 密钥，将其从账户中永久移除。

如果使用该密钥签署提交，移除 SSH 密钥会带来额外影响。有关更多信息，请参见已移除 SSH 密钥的签署提交。

吊销 SSH 密钥#

版本历史
  • 在极狐GitLab 15.9 中引入。

如果你的 SSH 密钥泄露，请吊销该密钥。

前提条件：

  • SSH 密钥的用途类型必须为 Signing 或 Authentication & Signing。

要吊销 SSH 密钥：

  1. 在右上角，选择你的头像。
  2. 选择 编辑配置文件。
  3. 在左侧边栏中，选择 访问权限 > SSH 密钥。
  4. 在要吊销的 SSH 密钥旁边，选择 吊销。
  5. 选择 吊销。

删除 SSH 密钥#

要删除 SSH 密钥：

  1. 在右上角，选择你的头像。
  2. 选择 编辑配置文件。
  3. 在左侧边栏中，选择 访问权限 > SSH 密钥。
  4. 在要删除的密钥旁边，选择 移除 ()。
  5. 选择 删除。

SSH 密钥过期#

你可以在向账户添加 SSH 密钥时设置过期日期。这个可选设置有助于限制安全漏洞的风险。

SSH 密钥过期后，你将无法再使用它进行身份验证或签署提交。你必须生成新的 SSH 密钥并将其添加到你的账户。

在私有化部署的极狐GitLab 中，管理员可以查看过期日期，并在删除密钥时将其作为参考。

极狐GitLab 每天检查即将过期的 SSH 密钥并发送通知：

  • 在过期前七天的 UTC 时间 01:00。
  • 在过期当天的 UTC 时间 02:00。