使用 OAuth 保护 API

本教程介绍如何使用 OAuth 2.0 保护 API。

OAuth 是一种授权协议，使应用能够代表用户访问信息，而用户无需泄露其用户名和密码。

使用 OAuth 时，安全凭据（例如用户名/密码或密钥/密码）会被交换为访问令牌。例如：

joe:joes_password （用户名：密码） 或
Nf2moHOASMJeUmXVdDhlMbPaXm2U7eMc:unUOXYpPe74ZfLEb （密钥：密码）

会变为：

b0uiYwjRZLEo4lEu7ky2GGxHkanN

访问令牌是随机字符串，并且是临时的（应该会在相对较短的时间后过期），因此在应用工作流中传递它来对用户进行身份验证要比传递实际凭据安全得多。

OAuth 2.0 规范定义了不同的机制（称为“授权类型”），用于分配应用的访问令牌。OAuth 2.0 定义的最基本的授权类型称为“客户端凭据”。在此类授权类型中，系统会生成 OAuth 访问令牌用于交换客户端凭据，即使用方密钥/使用方密钥对，如上例所示。

Edge 中的客户端凭据授予类型是使用 API 代理中的政策实现的。典型的 OAuth 流程涉及两个步骤：

• 调用 API 代理 1，以从客户端凭据生成 OAuth 访问令牌。API 代理上的 OAuth v2.0 政策进行处理。
• 调用 API 代理 2，在 API 调用中发送 OAuth 访问令牌。API 代理使用 OAuth v2.0 政策验证访问令牌。

所需条件

• Apigee Edge 账号。如果您还没有该账号，可以按照创建 Apigee Edge 账号中的说明进行注册。
• 在您的机器上安装 cURL，以从命令行进行 API 调用。

下载并部署一个生成令牌的 API 代理

在此步骤中，您将创建 API 代理，该代理可通过在 API 调用中发送的使用方密钥和使用方密码生成 OAuth 访问令牌。Apigee 提供了一个示例 API 代理来执行此操作。您现在可以下载并部署代理，稍后在本教程的后面使用该代理。（您可以轻松自行构建此 API 代理。此下载和部署步骤是为了方便起见，并向您展示共享已创建的代理有多么容易。）

1. 将“oauth”示例 API 代理 ZIP 文件下载到文件系统中的任何目录。
2. 转到 https://apigee.com/edge 并登录。
3. 在左侧导航栏中，选择开发 > API 代理。
4. 点击 + Proxy。
   
5. 在创建代理向导中，点击上传代理软件包。
6. 选择下载的 oauth.zip 文件，然后点击 Next。
7. 点击创建。
8. 构建完成后，点击修改代理以在 API 代理编辑器中查看新代理。
9. 在“API 代理编辑器概览”页面上，点击部署下拉列表，然后选择测试。这是您的组织中的测试环境。
   
   在确认提示时，点击部署。
   再次点击 Deployment 下拉列表时，绿色图标表示代理已部署到测试环境。
   

做得好！您已成功下载一个访问令牌生成 API 代理，并将其部署到 Edge 组织中。

查看 OAuth 流程和政策

我们来详细了解一下 API 代理包含的内容。

1. 在 API 代理编辑器中，点击开发标签页。在左侧的导航器窗格中，您会看到两项政策。您还会在 Proxy Endpoints 部分看到两个 POST 流程。

2. 点击 Proxy Endpoints 下的 AccessTokenClientCredential。
   

   在 XML 代码视图中，您会看到一个名为 AccessTokenClientCredential 的 Flow：

   <Flow name="AccessTokenClientCredential">
       <Description/>
       <Request>
           <Step>
               <Name>GenerateAccessTokenClient</Name>
           </Step>
       </Request>
       <Response/>
       <Condition>(proxy.pathsuffix MatchesPath "/accesstoken") and (request.verb = "POST")</Condition>
   </Flow>
   

   流程是 API 代理中的一个处理步骤。在这个示例中，流程会在满足特定条件时触发（这称为“条件流”）。<Condition> 元素中定义的条件表明，如果对 /accesstoken 资源进行 API 代理调用，且请求动词为 POST，则执行 GenerateAccessTokenClient 政策，从而生成访问令牌。

3. 现在我们来看看条件流程将触发的政策。点击流程图中的 GenerateAccessTokenClient 政策图标。
   
   以下 XML 配置加载到代码视图中：

   <OAuthV2 name="GenerateAccessTokenClient">
       <!-- This policy generates an OAuth 2.0 access token using the client_credentials grant type -->
       <Operation>GenerateAccessToken</Operation>
       <!-- This is in millseconds, so expire in an hour -->
       <ExpiresIn>3600000</ExpiresIn>
       <SupportedGrantTypes>
           <!-- This part is very important: most real OAuth 2.0 apps will want to use other
            grant types. In this case it is important to NOT include the "client_credentials"
            type because it allows a client to get access to a token with no user authentication -->
           <GrantType>client_credentials</GrantType>
       </SupportedGrantTypes>
       <GrantType>request.queryparam.grant_type</GrantType>
       <GenerateResponse/>
   </OAuthV2>
   

   配置包括以下内容：

   • <Operation> 可以是几个预定义值之一，用于定义政策要执行的操作。在此情况下，它将会生成访问令牌。
   • 令牌将在生成后 1 小时（3600000 毫秒）过期。
   • 在 <SupportedGrantTypes> 中，应使用的 OAuth <GrantType> 为 client_credentials（交换 OAuth 令牌的使用方密钥和密码）。
   • 第二个 <GrantType> 元素指示政策根据 OAuth 2.0 规范的要求在 API 调用中的何处查找授权类型参数。（此授权类型参数稍后会在 API 调用中看到）。授权类型还可以 HTTP 标头 (request.header.grant_type) 的形式或作为表单参数 (request.formparam.grant_type) 发送。

目前，您无需对 API 代理执行任何其他操作。在后续步骤中，您将使用此 API 代理生成 OAuth 访问令牌。但首先，您还需要执行以下操作：

• 使用 OAuth 创建您真正希望保护的 API 代理。
• 再创建几个工件，这会导致交换访问令牌所需的使用方密钥和使用方密码。

创建受 OAuth 保护的 API 代理

现在，您将创建要保护的 API 代理。此 API 调用会返回您所需的内容。在此情况下，API 代理将调用 Apigee 的 mocktarget 服务来返回您的 IP 地址。但是，只有当您通过 API 调用传递有效的 OAuth 访问令牌时，您才会看到。

您在此处创建的 API 代理将包含一个政策，用于检查请求中的 OAuth 令牌。

1. 在左侧导航栏中，选择开发 > API 代理。
2. 点击 + Proxy。
   
3. 在构建代理向导中，选择反向代理（最常见），然后点击下一步。
4. 请使用以下操作配置代理：
   

   在此字段中	执行该操作
   代理名称	输入：helloworld_oauth2
   项目基本路径	更改为：/hellooauth2 项目基本路径是用于向 API 代理发出请求的网址的一部分。
   现有 API	输入：https://mocktarget.apigee.net/ip 这定义了 Apigee Edge 在对 API 代理的请求上调用的目标网址。
   说明	输入：hello world protected by OAuth

5. 点击下一步。
6. 在通用政策 (Common policies) 页面上，执行以下操作：

   在此字段中	执行该操作
   安全授权	选择：OAuth 2.0

7. 点击下一步。
8. 在 Virtual Hosts（虚拟主机）页面上，点击 Next（下一步）。
9. 在构建页面上，确保已选择测试环境，然后点击创建和部署。
10. 在摘要页面上，您会看到一条确认消息，告知您新 API 代理已成功创建，且 API 代理已部署到测试环境。
11. 点击修改代理以显示 API 代理的概览页面。
    请注意，这一次，系统会自动部署 API 代理。点击“部署”下拉列表，确保“测试”环境旁边有一个绿色部署点。