设置 OS Login

本文档介绍设置 OS Login 的基本步骤。

OS Login 可让您使用 Compute Engine IAM 角色授予或撤消对 Linux 实例的 SSH 访问权限。这种方法可代替通过在元数据中添加和移除 SSH 密钥管理实例访问权限。如需详细了解使用此功能的好处，请参阅 OS Login。

如果您想使用双重身份验证来启用带有安全层的 OS Login，请参阅设置 OS Login 及两步验证。如需查看有关管理虚拟机访问权限的所有选项，请参阅选择访问方法。

如需配置 OS Login 并连接到您的实例，请完成以下步骤：

安装或更新客机环境。
可选：如果您是组织管理员，请查看管理组织中的 OS Login。
在您的项目或单个实例上启用 OS Login 功能。
向您自己、项目成员或组织成员授予必要的 IAM 角色。
可选：针对您自己、项目成员或组织成员向用户帐号添加自定义 SSH 密钥。如果您未添加 SSH 密钥，Compute Engine 会在连接到实例时为您生成 SSH 密钥。
连接实例。

准备工作

如果您要使用本指南中的命令行示例，请执行以下操作：
1. 安装或更新到 gcloud 命令行工具的最新版本。
2. 设置默认区域和可用区。
如果您要使用本指南中的 API 示例，请设置 API 访问权限。
如需了解 SSH 连接在 Compute Engine 中的工作原理（包括 SSH 密钥配置和存储），请参阅与 Linux 虚拟机的 SSH 连接。

限制

运行 1.20.5 或更高版本的节点池的专用 Google Kubernetes Engine (GKE) 集群支持 OS Login。
公共 GKE 集群不支持 OS Login。启用 OS Login 后，公共集群节点将继续使用元数据 SSH 密钥。
目前，Fedora CoreOS 映像不支持 OS Login。如需管理对使用这些映像创建的虚拟机的实例访问权限，请使用 Fedora CoreOS Ignition 系统。
Windows Server 和 SQL Server 映像不支持 OS Login。

第 1 步：安装或更新客机环境

您的虚拟机实例必须安装最新版本的客机环境。大多数公共映像均已安装最新版本。如果您没有最新的客机环境，请更新您的客机环境。

如果虚拟机运行您导入的自定义映像，请在这些虚拟机上安装客机环境。

如果您没有最新的客机环境，请更新您的客机环境。

第 2 步：（可选）查看如何管理组织中的 OS Login

如果您是组织管理员，则可以设置一些配置，例如在组织级层启用 OS Login。请参阅管理组织中的 OS Login。

第 3 步：启用或停用 OS Login

您可以通过在实例级层或项目级层设置元数据值来启用或停用 OS Login。要设置这些值，您可以使用 Google Cloud Console 或 gcloud 命令行工具。

控制台

您可以使用以下选项之一将元数据值应用于您的项目或虚拟机：

方法 1：在项目级元数据中设置 enable-oslogin，以将此项设置应用于项目中的所有实例。
1. 在 Google Cloud Console 中，转到元数据页面。
  
  转到元数据
2. 点击修改。
3. 添加元数据条目，将键设置为 enable-oslogin，并将值设置为 TRUE。或者，将值设置为 FALSE 以停用该功能。
4. 点击保存以应用更改。
方法 2：在现有实例的实例元数据中设置 enable-oslogin。
1. 在 Google Cloud Console 中，转到虚拟机实例页面。
  
  转到虚拟机实例
2. 点击要启用 OS Login 的实例的名称。
3. 在“实例详情”页面上，点击修改。
4. 在自定义元数据下方，添加一个元数据条目，并将键设置为 enable-oslogin，将值设置为 TRUE。或者，将值设置为 FALSE 以在实例上停用 OS Login。
5. 点击保存以将更改应用于实例。
方法 3：创建实例时，在实例元数据中设置 enable-oslogin。
1. 在 Cloud Console 中，转到虚拟机实例页面。
  转到“虚拟机实例”
2. 点击创建实例。
3. 在创建新实例页面上，填写实例的属性。
4. 在元数据部分，添加一个元数据条目，其中键为 enable-oslogin，值为 TRUE。或者，将该值设置为 FALSE 以对实例停用该功能。
5. 点击创建以创建实例。

gcloud

您可以使用下列其中一种方法将元数据值应用于项目或虚拟机：

方法 1：在项目级元数据中设置 enable-oslogin，以将此项设置应用于项目中的所有实例。

在 gcloud 命令行工具中使用 project-info add-metadata 命令，并设置元数据值，其中 oslogin=TRUE，以启用 OS Login：
```
gcloud compute project-info add-metadata \
    --metadata enable-oslogin=TRUE
```
或者，您可以将 enable-oslogin 设置为 FALSE 以停用 OS Login。
方法 2：在现有实例的元数据中设置 enable-oslogin。

在 gcloud 命令行工具中使用 instances add-metadata 命令，并设置 oslogin=TRUE 以启用 OS Login。将 VM_NAME 替换为虚拟机名称。
```
gcloud compute instances add-metadata VM_NAME \
    --metadata enable-oslogin=TRUE
```
或者，您可以将 enable-oslogin 设置为 FALSE 以使实例停用 OS Login。
方法 3：创建实例时，在实例元数据中设置 enable-oslogin。

在 gcloud 命令行工具中使用 instances create 命令，并设置 oslogin=TRUE 以启用 OS Login。将 VM_NAME 替换为您的实例名称。
```
gcloud compute instances create VM_NAME \
    --metadata enable-oslogin=TRUE
```
或者，您可以将 enable-oslogin 设置为 FALSE 以使实例停用 OS Login。

在项目中的实例上启用操作系统登录后，请向用户授予连接这些实例的权限。

第 4 步：为用户帐号配置 OS Login 角色

为 OS Login 授予 IAM 角色

当您在项目中的一个或多个实例上启用 OS Login 后，这些虚拟机将只接受在项目或组织中拥有必要 IAM 角色的用户帐号发出的连接。

如需授予对这些虚拟机的 OS Login 访问权限，您需要向相关用户授予必要的角色。如需授予 OS Login 访问权限，请完成以下步骤：

授予以下实例访问角色之一。
- roles/compute.osLogin，该角色不授予管理员权限
- roles/compute.osAdminLogin，该角色可授予管理员权限
注意：如果用户具有基本 roles/owner 或 roles/editor 角色，或者他们具有 roles/compute.instanceAdmin 角色，则这些角色已包含拥有管理员权限的实例访问角色。
您可以使用 gcloud compute instances add-iam-policy-binding 命令在实例级层授予这些实例访问角色。

注意：如果您在实例级层授予实例访问角色，那么除非您直接向用户提供有关虚拟机的详细信息或这些虚拟机的外部 IP 地址，否则用户无法查看这些详细信息。您需要向用户授予额外的 IAM 角色，这样他们才能查看虚拟机实例的详细信息。例如，向用户授予 roles/compute.viewer 角色即可让他们查看项目中的所有资源，包括虚拟机实例的详细信息。
如果您的虚拟机实例使用一个服务帐号，则必须将每个用户配置为对该服务帐号拥有 roles/iam.serviceAccountUser 角色。如需了解如何将用户的访问权限添加到服务帐号，请参阅管理服务帐号模拟。

注意：使用 Google Cloud Console 或 gcloud 命令行工具创建的虚拟机默认具有一个关联的服务帐号。没有关联服务帐号的虚拟机不要求此权限。如需检查您是否具有关联的服务帐号，请参阅检查您的虚拟机是否具有服务帐号。
如需允许组织外部的用户访问您的虚拟机，除了授予实例访问角色之外，还应授予 roles/compute.osLoginExternalUser 角色。该角色必须由组织管理员在组织级层授予。如需了解详情，请参阅向组织外部的用户授予实例访问权限。

向服务帐号授予 SSH 访问权限

您可以使用 OS Login 角色来允许服务帐号建立与实例的 SSH 连接。这对于以下任务非常有用：

如果您的应用需要 Compute Engine 实例的 SSH 访问权限，您可以通过服务帐号提供该访问权限。如需了解详情，请参阅使用 SSH 将应用连接到实例。
如需了解如何承担服务帐号的权限，并使用这些权限在第二个实例上执行命令，请参阅以服务帐号的身份在实例之间手动建立连接。

您可以通过以下过程向您的服务帐号授予 SSH 访问权限：

创建服务帐号。
向您的服务帐号授予必要的 OS Login 角色。服务帐号需要使用与用户帐号相同的角色。如需了解如何为服务帐号配置角色和权限，请参阅向服务帐号授予角色。
向您的服务帐号提供应用默认凭据，以便它可以为向必要 API 发出的请求授权。可使用以下选项之一提供应用默认凭据：
- 创建与您的服务帐号关联的实例。该实例会为您的服务帐号提供应用默认凭据。
- 如果您在 Compute Engine 环境之外运行应用，请手动为应用提供服务帐号凭据。

向您的服务帐号授予 SSH 访问权限之后，可以对应用进行配置以创建 SSH 密钥，并建立与 VPC 网络上其他实例的 SSH 连接。如需查看服务帐号 SSH 的示例应用，请参阅使用 SSH 将应用连接到实例教程。

撤消 OS Login IAM 角色

要撤消用户对可以使用操作系统登录的实例的访问权限，请从该用户帐号中移除用户角色。如需了解如何移除用户的 IAM 角色，请参阅授予、更改和撤消对资源的访问权限。

撤消某用户的访问权限后，该用户仍然拥有与其帐号关联的公共 SSH 密钥，但这些密钥不再会对虚拟机实例起作用。

第 5 步：（可选）将 SSH 密钥添加到用户帐号

如果您想使用第三方工具连接到虚拟机，则需要将 SSH 密钥添加到您的用户帐号。如果您使用其他选项（如 gcloud 命令行工具或在浏览器中使用 SSH）连接到实例，则可以跳过此步骤，因为 Compute Engine 会自动为您生成 SSH 密钥。

您可以将 SSH 公钥与以下用户帐号类型相关联：

属于组织资源的托管用户帐号：
- Google Workspace
- Cloud Identity
消费者 Google 帐号，例如 gmail.com 帐号

您可以使用 gcloud 命令行工具或 OS Login API 将 SSH 密钥添加到自己的帐号中。或者，如果您是组织的网域管理员，则可以使用 Directory API 将 SSH 密钥添加到组织中的用户资源。

gcloud

gcloud compute os-login 命令仅适用于 Cloud SDK 版本 184 及更高版本。

使用 gcloud 命令行工具将 SSH 公钥与帐号相关联。

gcloud compute os-login ssh-keys add \
    --key-file=KEY_FILE_PATH \
    --ttl=EXPIRE_TIME

请替换以下内容：

KEY_FILE_PATH：指向本地工作站上 SSH 公钥的路径。确保 SSH 公钥格式正确。如果您在 Linux 系统上使用 PuTTYgen 来生成公钥，则必须使用 public-openssh 格式。
EXPIRE_TIME：一个可选标志，用于设置 SSH 公钥的到期时间。例如，您可以指定 30m，则 SSH 密钥将在 30 分钟后过期。此标志使用下列单位：
- s 表示秒数
- m 表示分钟数
- h 表示小时数
- d 表示天数
- 将值设置为 0 以指示没有到期时间。

使用 OS Login API 以将 SSH 公钥与帐号相关联：

POST https://oslogin.googleapis.com/v1/users/ACCOUNT_EMAIL:importSshPublicKey

{
 "key": "SSH_KEY",
 "expirationTimeUsec": "EXPIRATION_TIMESTAMP"
}

请替换以下内容：

ACCOUNT_EMAIL：表示您的代管式用户帐号的电子邮件地址。
SSH_KEY：您想要应用于帐号的公钥。确保 SSH 公钥格式正确。如果您在 Linux 系统上使用 PuTTYgen 来生成公钥，则必须使用 public-openssh 格式。
EXPIRATION_TIMESTAMP：密钥的到期时间（以微秒为单位，从纪元开始算起）。

Directory API

如果您是组织的网域管理员，则可以使用 Directory API 参考将 SSH 密钥添加到组织中其他用户的帐号。例如，使用一个或多个 SSH sshPublicKeys 条目创建对 directory.users.update 方法发出的 PUT 请求：

PUT https://www.googleapis.com/admin/directory/v1/users/USER_ID_KEY

{
 "sshPublicKeys": [
  {
   "key": "SSH_KEY",
   "expirationTimeUsec": "EXPIRATION_TIMESTAMP"
  },
  {
   "key": "SSH_KEY",
   "expirationTimeUsec": "EXPIRATION_TIMESTAMP"
  }
 ]
}

请替换以下内容：

USER_ID_KEY：用户的不可变 ID。
SSH_KEY：您要应用于帐号的公钥。确保 SSH 公钥格式正确。如果您在 Linux 系统上使用 PuTTYgen 来生成公钥，则必须使用 public-openssh 格式。
EXPIRATION_TIMESTAMP：密钥的到期时间（以微秒为单位，从纪元开始算起）。

如需从帐号中移除所有密钥，请指定 "sshPublicKeys": null 作为正文，并将 USER_ID_KEY 替换为用户的不可变 ID：

PUT https://www.googleapis.com/admin/directory/v1/users/USER_ID_KEY

{
  "sshPublicKeys": null
}

将密钥添加到帐号后，您可以使用第三方工具以及与帐号关联的用户名连接实例。请注意，您的组织管理员可以更改此用户名。不属于组织的帐号不能更改默认用户名。

您可以通过运行 gcloud compute os-login describe-profile 命令找到帐号的当前用户名。

例如，输出结果可能类似于以下内容：

name: '314159265358979323846'
posixAccounts:
- gid: '27182818'
  homeDirectory: /home/user_example_com
  ⋮
  uid: '27182818'
  username: user_example_com
⋮

第 6 步：连接到实例

您可以通过以下 3 种主要方式连接到虚拟机：

如果您连接到虚拟机的方式是使用 gcloud 工具或通过浏览器进行 SSH 连接，Compute Engine 会自动生成 SSH 密钥并将其与您的用户帐号关联。

如果您使用第三方工具连接到实例，则需要将公钥添加到您的用户帐号。虚拟机从您的用户帐号获取您的公钥，允许您在提供了正确的用户名和匹配的 SSH 私钥后连接到该实例。

连接到实例后，请查看预期的登录行为。

查看预期的登录行为

在某些使用操作系统登录的实例上，您可能会在建立连接后收到以下错误消息：
```
/usr/bin/id: cannot find name for group ID 123456789
```
忽略此错误消息。此错误不会影响您的实例。
Cloud Identity 管理员可以配置 POSIX 信息，并为组织成员设置用户名。如果 Cloud Identity 管理员未设置用户名，则 OS Login 会生成一个默认 Linux 用户名，具体方法是将用户的 Google 个人资料关联的电子邮件地址中的用户名和网域组合在一起。此命名惯例可确保唯一性。例如，如果与 Google 个人资料关联的用户电子邮件地址是 user@example.com，则其生成的用户名为 user_example_com。

Google Workspace 组织可以更改其默认值，为新生成的用户名移除域名后缀。例如，如果与 Google 个人资料关联的用户电子邮件地址是 user@example.com，则其生成的用户名为 user。如需了解详情，请参阅管理 OS Login API。

如果用户来自另一个 Google Workspace 组织，则生成的用户名会带有“ext_”前缀。例如，如果 user@example.com 正在访问其他组织中的虚拟机，则其生成的用户名为 ext_user_example_com。
使用 gcloud compute ssh 命令登录实例时，对于属于 example.com 域的用户 user，登录消息的格式如下：
```
Using OS Login user user_example_com instead of default user user
```
此消息确认用户是使用 OS Login 个人资料登录的。

后续步骤

连接实例。
了解与 Linux 虚拟机的 SSH 连接在 Compute Engine 上的工作原理。
详细了解 Compute Engine 访问控制。
了解服务帐号。
如需了解服务帐号 SSH 的示例应用，请参阅使用 SSH 将应用连接到实例教程。
了解 Google Cloud 项目访问权限。
排查 OS Login 问题。