使用 OAuth 保护 API

<ph type="x-smartling-placeholder"></ph> 您正在查看 Apigee Edge 文档。
转到 Apigee X 文档
信息

学习内容

  • 下载并部署示例 API 代理。
  • 创建受 OAuth 保护的 API 代理。
  • 创建产品、开发者和应用。
  • 交换 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 文件,然后点击 下一步
  7. 点击创建
  8. 构建完成后,点击修改代理以查看新代理 。
  9. 在“API 代理编辑器概览”页面上,点击部署下拉列表,然后选择测试。这是您的组织中的测试环境。

    在确认提示时,点击部署
    再次点击 Deployment 下拉列表时,绿色图标表示代理已部署到测试环境。

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

查看 OAuth 流程和政策

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

  1. 在 API 代理编辑器中,点击开发标签页。左侧 Navigator 窗格中,您会看到两项政策。您还会看到两个POST Proxy Endpoints 部分中的流。
  2. 点击 AccessTokenClientCredential(位于 Proxy Endpoints

    在 XML 代码视图中,您会看到一个名为 AccessTokenClientCredentialFlow

    <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> 元素声明,如果对 API 代理调用 /accesstoken 资源,请求动词为 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 代理

关于“mocktarget”

mocktarget 服务托管在 Apigee 上,并返回简单的数据。实际上,您可以在网络浏览器中访问它。尝试通过点击以下网址访问:

http://mocktarget.apigee.net/ip

目标将返回您最终调用此 API 代理时应该看到的内容。

您还可以点击 http://mocktarget.apigee.net/help 以查看 mocktarget 中提供的其他 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. Build 页面上,确保已选择 test 环境,并且 点击创建和部署
  10. 摘要页面上,您会看到一条确认消息,表明您的新 API 代理 已成功创建,并且 API 代理已部署到您的测试 环境
  11. 点击修改代理以显示 API 代理的概览页面。
    请注意,这一次会自动部署 API 代理。点击“部署”下拉列表,确保“测试”环境旁边有一个绿色部署点。

查看政策

我们来详细了解一下您创建的内容。

  1. 在 API 代理编辑器中,点击开发标签页。您将看到 API 代理的请求流程中添加了两个政策:
    • 验证 OAuth v2.0 访问令牌 –检查 API 调用以确保存在有效的 OAuth 令牌。
    • Remove Header Authorization(移除标头授权)- 用于评估 则会在经过检查后移除访问令牌,这样就不会将其传递到 目标服务。(如果目标服务需要 OAuth 访问令牌,您将不会使用此政策)。
  2. 点击流程视图中的验证 OAuth v2.0 访问令牌图标,然后在代码窗格中查看其下方的 XML。

    <OAuthV2 async="false" continueOnError="false" enabled="true" name="verify-oauth-v2-access-token">
        <DisplayName>Verify OAuth v2.0 Access Token</DisplayName>
        <Operation>VerifyAccessToken</Operation>
    </OAuthV2>
    

    请注意,<Operation>VerifyAccessToken。操作定义了政策应该执行的操作。在这种情况下,它将检查请求中的有效 OAuth 令牌。

添加 API 产品

如需使用 Apigee 界面添加 API 产品,请执行以下操作:

  1. 选择发布 > API 产品
  2. 点击 +API 产品
  3. 为您的 API 产品输入商品详情
    字段 说明
    名称 API 产品的内部名称。请勿在名称中指定特殊字符。
    注意:API 产品一经创建,便无法修改此名称。例如 helloworld_oauth2-Product
    显示名称 API 产品的显示名。显示名称在界面中使用,您可以修改 。如果未指定,则系统会使用 Name 值。此字段会自动填充 使用“名称”值您可以修改或删除其内容显示名称可以包括 特殊字符。例如 helloworld_oauth2-Product
    说明 API 产品的说明。
    环境 API 产品将允许访问的环境。选择要添加到的环境 您部署了 API 代理例如 test
    访问 选择公开
    自动批准访问请求 从任何应用启用此 API 产品的密钥请求的自动批准。
    配额 在本教程中忽略。
    允许的 OAuth 范围 在本教程中忽略。
  4. API 代理字段中,选择您刚刚创建的 API 代理。
  5. 路径字段中,输入“/”。忽略其他字段。
  6. 点击保存

将开发者和应用添加到您的组织

接下来,您将模拟开发者注册使用 API 的工作流程。理想情况下,开发者可通过开发者门户注册自己及其应用。但在此步骤中,您将以管理员的身份添加开发者和应用。

开发者将拥有一个或多个调用您的 API 的应用,并且每个应用都具有唯一的使用方密钥和使用方密码。每个应用的密钥/密码还为您(API 提供商)提供了对 API 访问更精细的控制,以及对 API 流量的更精细的分析报告,因为 Edge 知道哪个开发者和应用属于哪个 OAuth 令牌。

创建一个开发者

我们来创建一个名为“Nigel Tufnel”的开发者名称。

  1. 在菜单中选择 Publish > Developers
  2. 点击 + 开发者
  3. New Developer 窗口中输入以下内容:
    在此字段中 输入
    名字 Nigel
    姓氏 Tufnel
    用户名 nigel
    电子邮件 nigel@example.com
  4. 点击创建

注册一个应用

让我们为 Nigel 创建一个应用。

  1. 选择发布 > 应用
  2. 点击 + 应用
  3. New App 窗口中输入以下内容:
    在此字段中 执行该操作
    名称显示名 输入:nigel_app
    开发者 点击开发者,然后选择:Nigel Tufnel (nigel@example.com)
    回调网址备注 留空
  4. 产品下,点击添加产品
  5. 选择 helloworld_oauth2-Product
  6. 点击创建

获取使用方密钥和使用方密码

现在,您将获取将用于交换 OAuth 访问令牌的使用方密钥和使用方密码。

  1. 确保将显示 nigel_app 页面。如果没有,请在“应用”页面(发布 > 应用)上点击 nigel_app
  2. 在 Nigel_app 页面上,点击密钥密码列中的显示。请注意,密钥/密码与先前自动创建的“helloworld_oauth2-Product”相关联。

  3. 选择并复制密钥和密码。将其粘贴到临时文本文件中。您将在后面的步骤中使用这些密钥和密码,以便在调用 API 代理时将这些凭据交换为 OAuth 访问令牌。

尝试调用 API 以获取 IP 地址(失败!)

请尝试调用应该返回您的 IP 地址的受保护 API 代理。在终端窗口中执行以下 c网址 命令,注意替换上您的 Edge 组织名称。网址中的 test 文字是组织的测试环境,即您将代理部署到的测试环境。代理基本路径为 /hellooauth2,即您在创建代理时指定的基本路径。请注意,您在调用中传递 OAuth 访问令牌。

curl https://ORG_NAME-test.apigee.net/hellooauth2

由于 API 代理使用 Verify OAuth v2.0 Access Token 政策检查请求中的有效 OAuth 令牌,因此调用应会失败并显示以下消息:

{"fault":{"faultstring":"Invalid access token","detail":{"errorcode":"oauth.v2.InvalidAccessToken"}}}

这种情况下,失败是好消息!这表示您的 API 代理更加安全。只有具有有效 OAuth 访问令牌的可信应用才能成功调用此 API。

获取 OAuth 访问令牌

现在我们将得到巨大回报。您将使用复制并粘贴到文本文件中的密钥和密码,并用其换取 OAuth 访问令牌。您现在要对导入的 API 示例代理 oauth 进行 API 调用,该代理将生成 API 访问令牌。

使用该键值和密钥进行以下 c网址 调用(请注意,协议是 https),并将您的 Edge 组织名称、密钥和 Secret 的相应说明:

curl -X POST -H "Content-Type: application/x-www-form-urlencoded" \
"https://ORG_NAME-test.apigee.net/oauth/client_credential/accesstoken?grant_type=client_credentials" \
-d "client_id=CLIENT_KEY&client_secret=CLIENT_SECRET"

请注意,如果您使用 Postman 等客户端发起调用,则 client_idclient_secret 将进入请求的正文中,并且必须为 x-www-form-urlencoded

您应该得到如下所示的响应:

{
  "issued_at" : "1466025769306",
  "application_name" : "716bbe61-f14a-4d85-9b56-a62ff8e0d347",
  "scope" : "",
  "status" : "approved",
  "api_product_list" : "[helloworld_oauth2-Product]",
  "expires_in" : "3599", //--in seconds
  "developer.email" : "nigel@example.com",
  "token_type" : "BearerToken",
  "client_id" : "xNnREu1DNGfiwzQZ5HUN8IAUwZSW1GZW",
  "access_token" : "GTPY9VUHCqKVMRB0cHxnmAp0RXc0",
  "organization_name" : "myOrg",
  "refresh_token_expires_in" : "0", //--in seconds
  "refresh_count" : "0"
}

您获得了 OAuth 访问令牌!复制 access_token 值(不带引号)并将其粘贴到您的文本文件。稍后您将用到它。

刚刚出现了什么情况?

还记得之前,您在查看条件流oauth代理,用于说明资源 URI 是否为 /accesstoken,请求动词为 POST,以执行 生成访问令牌的 GenerateAccessTokenClient OAuth 政策?您的 cURL 命令符合这些条件,因此执行 OAuth 政策。它会验证您的使用方密钥和使用方密码,并将其交换为在 1 小时内到期的 OAuth 令牌。

使用访问令牌调用 API(成功!)

您拥有访问令牌之后,就可以使用该令牌来调用 API 代理了。进行以下 cURL 调用。替换您的 Edge 组织名称和访问令牌。

curl https://ORG_NAME-test.apigee.net/hellooauth2 -H "Authorization: Bearer TOKEN"

现在,您应该成功地调用了返回您的 IP 地址的 API 代理。例如:

{"ip":"::ffff:192.168.14.136"}

您可以重复该 API 调用接近一小时,之后访问令牌将过期。要在一小时之后发起调用,您需要使用上一步生成新的访问令牌。

恭喜!您已创建 API 代理,并要求在调用中包含有效的 OAuth 访问令牌,从而保护它。

相关主题