将 App Identity 迁移到 OIDC ID 令牌

当在 Python 2 运行时中运行的应用向另一个 App Engine 应用发送请求时，它可以使用 App Engine App Identity API 来声明其身份。接收请求的应用可以使用此身份来确定是否应处理该请求。

如果您的 Python 3 应用在向其他 App Engine 应用发送请求时需要声明其身份，则您可以使用由 Google 的 OAuth 2.0 API 颁发并解码的 OpenID Connect (OIDC) ID 令牌。

下文概述了如何使用 OIDC ID 令牌来声明和验证身份：

1. 名为“应用 A”的 App Engine 应用从 Google Cloud 运行时环境检索 ID 令牌。
2. 应用 A 在向应用 B（它是另一个 App Engine 应用）发送请求之前，会先在请求标头中添加此令牌。
3. 应用 B 使用 Google 的 OAuth 2.0 API 来验证令牌载荷。解码后的载荷包含应用 A 经过验证的身份，其采用应用 A 的默认服务账号的电子邮件地址格式。
4. 应用 B 将载荷中的身份与允许响应的身份列表进行比较。如果请求来自允许的应用，则应用 B 会处理该请求并做出响应。

本指南介绍了如何更新 App Engine 应用以便使用 OpenID Connect (OIDC) ID 令牌来声明身份，以及如何更新其他 App Engine 应用以便在处理请求之前先使用 ID 令牌来验证身份。

App Identity API 和 OIDC API 之间的主要区别

• Python 2 运行时版本的应用无需明确声明身份。当应用使用 httplib、urllib 或 urllib2 Python 库或 App Engine URL Fetch 服务来发送出站请求时，运行时使用 App Engine URL Fetch 服务发出请求。如果请求正在发送至 appspot.com 网域，则 URL Fetch 会在请求中添加 X-Appengine-Inbound-Appid 标头，以自动声明发出请求的应用的身份。该标头包含应用的 ID（也称为项目 ID）。

  Python 3 运行时版本的应用确实需要明确声明身份，方法是从 Google Cloud 运行时环境检索 OIDC ID 令牌并将其添加到请求标头中。您需要更新向其他 App Engine 应用发送请求的所有代码，以便请求包含 OIDC ID 令牌。

• 请求中的 X-Appengine-Inbound-Appid 标头包含发送请求的应用的项目 ID。

  Google OIDC ID 令牌的载荷并不会直接标识应用本身的项目 ID。相反，该令牌会提供此服务账号的电子邮件地址，以标识运行该应用的服务账号。您需要添加一些代码，以从令牌载荷中提取用户名。

  如果该服务账号是项目的应用级默认 App Engine 服务账号，则您可以在服务账号的电子邮件地址中找到项目 ID。此地址的用户名部分与项目 ID 相同。在这种情况下，接收方应用代码可在其允许发来请求的项目 ID 列表中查找。

  但是，如果请求方应用使用的是用户管理的服务账号，而不是默认 App Engine 服务账号，则接收方应用可以仅验证该服务账号的身份，这不一定会定义请求方应用的项目 ID。 在这种情况下，接收方应用必须维护一个允许的服务账号电子邮件地址列表，而不是允许的项目 ID 列表。

• URL Fetch API 调用的配额与用于授予令牌的 Google 的 OAuth 2.0 API 配额不同。您可以在 Google Cloud 控制台 OAuth 同意屏幕中查看您每天可以授予的令牌数量上限。URL Fetch（即 App Identity API）和 Google 的 OAuth 2.0 API 都不会产生费用。

迁移过程概览

如需迁移 Python 应用以使用 OIDC API 声明和验证身份，请执行以下操作：

1. 在向其他 App Engine 应用发送请求时需要声明身份的应用中：

   1. 等待直至您的应用在 Python 3 环境中运行以迁移到 ID 令牌。

      尽管在 Python 2 运行时中可以使用 ID 令牌，但 Python 2 中的步骤非常复杂，只有在更新应用以在 Python 3 运行时中运行时才暂时需要执行这些步骤。

   2. 当应用在 Python 3 中运行之后，请更新应用以请求 ID 令牌并将该令牌添加到请求标头中。

2. 在处理请求之前需要验证身份的应用中：

   1. 首先升级 Python 2 应用以便支持 ID 令牌和 App Identity API 身份。这样一来，您的应用就能够验证并处理来自使用 App Identity API 的 Python 2 应用或使用 ID 令牌的 Python 3 应用的请求。

   2. 升级后的 Python 2 应用稳定之后，请将它们迁移至 Python 3 运行时中。继续支持 ID 令牌和 App Identity API 身份，直至确定应用不再需要支持来自旧版应用的请求。

   3. 如果您不再需要处理来自旧版 App Engine 应用的请求，请移除用于验证 App Identity API 身份的代码。

3. 测试应用之后，请先部署用于处理请求的应用。然后部署更新后的 Python 3 应用，该应用使用 ID 令牌来声明身份。

声明身份

等待直到您的应用在 Python 3 环境中运行，然后按照以下步骤操作来升级应用，以使用 ID 令牌声明身份：

1. 安装 google-auth 客户端库。

2. 添加代码以向 Google 的 OAuth 2.0 API 请求 ID 令牌，并在发送请求之前将令牌添加到请求标头中。

3. 测试您的更新。

为 Python 3 应用安装 google-auth 客户端库

如需将 google-auth 客户端库提供给 Python3 应用，请在 app.yaml 文件所在的文件夹中创建一个 requirements.txt 文件，并添加以下行：

     google-auth

部署应用时，App Engine 将下载 requirements.txt 文件中定义的所有依赖项。

对于本地开发，我们建议您在虚拟环境（例如 venv）中安装依赖项。

添加代码以声明身份

搜索您的代码并查找所有向其他 App Engine 应用发送请求的实例。请先更新上述实例以执行以下操作，然后再发送请求：

1. 添加以下 import 命令：

   from google.auth.transport import requests as reqs
   from google.oauth2 import id_token
   

2. 使用 google.oauth2.id_token.fetch_id_token(request, audience) 检索 ID 令牌。在方法调用中添加下列参数：

   • request：传递您准备发送的请求对象。

   • audience：传递您要将请求发送到的应用的网址。这样可以将令牌绑定到请求并防止其他应用使用该令牌。

     为清楚明确起见，我们建议您传递 App Engine 为接收请求的特定服务创建的 appspot.com 网址，即使您对应用使用自定义网域也是如此。

3. 在请求对象中，设置以下标头：

   'Authorization': 'ID {}'.format(token)
   

例如：

# Copyright 2020 Google LLC
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

from flask import Flask, render_template, request
from google.auth.transport import requests as reqs
from google.oauth2 import id_token
import requests

app = Flask(__name__)

@app.route("/", methods=["GET"])
def index():
    return render_template("index.html")

@app.route("/", methods=["POST"])
def make_request():
    url = request.form["url"]
    token = id_token.fetch_id_token(reqs.Request(), url)

    resp = requests.get(url, headers={"Authorization": f"Bearer {token}"})

    message = f"Response when calling {url}:\n\n"
    message += resp.text

    return message, 200, {"Content-type": "text/plain"}

测试用于声明身份的更新

如需在本地运行您的应用并测试应用是否能够成功发送 ID 令牌，请执行以下操作：

1. 请按照以下步骤在本地环境中提供默认 App Engine 服务账号的凭据（Google OAuth API 需要这些凭据才能生成 ID 令牌）：

   1. 输入以下 gcloud 命令以针对项目的默认 App Engine 账号检索服务账号密钥：

      gcloud iam service-accounts keys create ~/key.json --iam-account [e-mail]

      将 project-ID 替换为您的 Google Cloud 项目的 ID。

      现在，服务账号密钥文件已下载到您的机器上。您可以根据需要移动并重命名此文件。务必要安全存储此文件，因为它能够以服务账号的身份进行身份验证。如果丢失了该文件，或者该文件向未授权的用户公开了，请删除服务账号密钥，然后创建一个新密钥。

   2. 输入以下命令：

      <code>export GOOGLE_APPLICATION_CREDENTIALS=<var>service-account-key</var></code>
      

   将 service-account-key 替换为包含所下载服务账号密钥的文件的绝对路径名。

2. 在您导出 GOOGLE_APPLICATION_CREDENTIALS 环境变量的同一 shell 中，启动 Python 应用。

3. 从应用发送请求并确认操作是否成功。如果您还没有可以接收请求并使用 ID 令牌来验证身份的应用，请执行以下操作：

   1. 下载“传入的”应用示例。

   2. 在示例的 main.py 文件中，将您的 Google Cloud 项目 ID 添加到 allowed_app_ids 中。例如：

       allowed_app_ids = [
          '<APP_ID_1>',
          '<APP_ID_2>',
          'my-project-id'
        ]
      

   3. 在 Python 2 本地开发服务器中运行更新后的示例。

验证和处理请求

如需升级 Python 2 应用以便在处理请求之前先使用 ID 令牌或 App Identity API 身份，请执行以下操作：

1. 安装 google-auth 客户端库。

2. 更新代码以便执行以下操作：

   1. 如果请求中包含 X-Appengine-Inbound-Appid 标头，请使用该标头验证身份。在旧版运行时（如 Python 2）中运行的应用将包含此标头。

   2. 如果请求不包含 X-Appengine-Inbound-Appid 标头，请检查是否存在 OIDC ID 令牌。如果该令牌存在，请验证令牌载荷并检查发送者的身份。

3. 测试您的更新。

为 Python 2 应用安装 google-auth 客户端库

如需使 Python 2 应用能够使用 google-auth 客户端库，请执行以下操作：

1. 在 app.yaml 文件所在的文件夹中创建 requirements.txt 文件，并添加以下行：

    google-auth==1.19.2
   

   我们建议您使用 1.19.2 版的 Cloud Logging 客户端库，因为它支持 Python 2.7 应用。

2. 在应用的 app.yaml 文件的 libraries 部分中，指定 SSL 库（如果尚未指定的话）：

   libraries:
   - name: ssl
     version: latest
   

3. 创建一个用于存储第三方库的目录，如 lib/。然后使用 pip install 将库安装到该目录中。 例如：

   pip install -t lib -r requirements.txt
   

4. 在 app.yaml 文件所在的文件夹中创建 appengine_config.py 文件。将以下内容添加到 appengine_config.py 文件：

   # appengine_config.py
   import pkg_resources
   from google.appengine.ext import vendor
   
   # Set path to your libraries folder.
   path = 'lib'
   # Add libraries installed in the path folder.
   vendor.add(path)
   # Add libraries to pkg_resources working set to find the distribution.
   pkg_resources.working_set.add_entry(path)
   

   上例中的 appengine_config.py 文件假定 lib 文件夹位于当前工作目录中。如果您无法保证 lib 始终位于当前工作目录中，请指定 lib 文件夹的完整路径。例如：

   import os
   path = os.path.join(os.path.dirname(os.path.realpath(__file__)), 'lib')
   

对于本地开发，我们建议您在虚拟环境（如 Python 2 的 virtualenv）中安装依赖项。

更新用于验证请求的代码

搜索您的代码并查找所有获取 X-Appengine-Inbound-Appid 标头值的实例。更新上述实例以执行以下操作：

1. 添加以下 import 命令：

   from google.auth.transport import requests as reqs
   from google.oauth2 import id_token
   

2. 如果传入的请求不包含 X-Appengine-Inbound-Appid 标头，请查找 Authorization 标头并检索其值。

   标头值的格式为“ID: token”。

3. 使用 google.oauth2.id_token.verify_oauth2_token(token, request, audience) 验证并检索解码后的令牌载荷。在方法调用中添加下列参数：

   • token：传递您从传入的请求中提取的令牌。

   • request：传递新的 google.auth.transport.Request 对象。

   • audience：传递当前应用（即正在发送验证请求的应用）的网址。Google 的授权服务器会将此网址与最初生成令牌时提供的网址进行比较。如果网址不匹配，则令牌将无法通过验证，而授权服务器将返回错误。

4. verify_oauth2_token 方法会返回解码后的令牌载荷，其中包含多个名称/值对，包括生成该令牌的应用的默认服务账号的电子邮件地址。

5. 从令牌载荷的电子邮件地址中提取用户名。

   用户名与发送请求的应用的项目 ID 相同。此值与之前在 X-Appengine-Inbound-Appid 标头中返回的值相同。

6. 如果用户名/项目 ID 位于允许的项目 ID 列表中，请处理请求。

例如：

# Copyright 2020 Google LLC
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

"""
Authenticate requests coming from other App Engine instances.
"""

from google.oauth2 import id_token
from google.auth.transport import requests

import logging
import webapp2

def get_app_id(request):
    # Requests from App Engine Standard for Python 2.7 will include a
    # trustworthy X-Appengine-Inbound-Appid. Other requests won't have
    # that header, as the App Engine runtime will strip it out
    incoming_app_id = request.headers.get("X-Appengine-Inbound-Appid", None)
    if incoming_app_id is not None:
        return incoming_app_id

    # Other App Engine apps can get an ID token for the App Engine default
    # service account, which will identify the application ID. They will
    # have to include at token in an Authorization header to be recognized
    # by this method.
    auth_header = request.headers.get("Authorization", None)
    if auth_header is None:
        return None

    # The auth_header must be in the form Authorization: Bearer token.
    bearer, token = auth_header.split()
    if bearer.lower() != "bearer":
        return None

    try:
        info = id_token.verify_oauth2_token(token, requests.Request())
        service_account_email = info["email"]
        incoming_app_id, domain = service_account_email.split("@")
        if domain != "appspot.gserviceaccount.com":  # Not App Engine svc acct
            return None
        else:
            return incoming_app_id
    except Exception as e:
        # report or log if desired, as here:
        logging.warning("Request has bad OAuth2 id token: {}".format(e))
        return None

class MainPage(webapp2.RequestHandler):
    allowed_app_ids = ["other-app-id", "other-app-id-2"]

    def get(self):
        incoming_app_id = get_app_id(self.request)

        if incoming_app_id is None:
            self.abort(403)

        if incoming_app_id not in self.allowed_app_ids:
            self.abort(403)

        self.response.write("This is a protected page.")

app = webapp2.WSGIApplication([("/", MainPage)], debug=True)

测试用于验证身份的更新

如需测试应用是否能够使用 ID 令牌或 X-Appengine-Inbound-Appid 标头来验证请求，请在 Python 2 本地开发服务器中运行应用，然后从 Python 2 应用（它将使用 App Identity API）和发送 ID 令牌的 Python 3 应用发送请求。

如果您尚未更新应用以发送 ID 令牌，请执行以下操作：

1. 下载“发出请求的”应用示例。

2. 按照测试声明应用的更新中的说明，将服务账号凭据添加到本地环境。

3. 使用标准 Python 3 命令启动 Python 3 示例应用。

4. 从示例应用发送请求并确认操作是否成功。

部署应用

准备好部署应用后，您应该执行以下操作：

1. 在 App Engine 上测试应用。

2. 如果应用可无错误正常运行，请使用流量拆分功能为更新后的应用缓慢增加流量。请先仔细监控应用是否存在任何问题，若无再将更多流量路由到更新后的应用。

使用其他服务账号声明身份

当您请求 ID 令牌时，请求默认使用 App Engine 默认服务账号的身份。在验证令牌时，令牌载荷包含默认服务账号的电子邮件地址，该地址映射到您的应用的项目 ID。

App Engine 默认服务账号默认具有较高的权限级别。它可以查看和修改整个 Google Cloud 项目，因此在大多数情况下，如果您的应用需要通过 Cloud 服务进行身份验证，则不适合使用此账号。

但是，在声明应用身份时，可以安全地使用默认服务账号，因为您只使用 ID 令牌来验证发送请求的应用的身份。在此过程中，不考虑或不需要已向服务账号授予的实际权限。

如果您仍希望使用其他服务账号来处理 ID 令牌请求，请执行以下操作：

1. 将名为 GOOGLE_APPLICATION_CREDENTIALS 的环境变量设置为包含服务账号凭据的 JSON 文件的路径。请参阅我们提供的建议以了解如何安全存储这些凭据。

2. 使用 google.oauth2.id_token.fetch_id_token(request, audience) 检索 ID 令牌。

3. 验证此令牌时，令牌载荷将包含新服务账号的电子邮件地址。