OAuth

您正在查看的是 Apigee Edge 文档。
转到 Apigee X 文档
信息

OAuth 已成为 API 中领先的授权协议。本主题详细介绍的 OAuth 版本在 OAuth 2.0 规范中定义。

OAuth 是一种协议,可让应用最终用户授权应用代表他们执行操作。为此,应用会从 API 提供方获取访问令牌。API 提供商会对应用最终用户的凭据进行身份验证,确保用户已对应用授权,然后向应用颁发访问令牌。当应用使用受保护的 API 时,Apigee Edge 会检查访问令牌以确保其有效且未过期。作为 API 提供方,您需要公开可让应用获取访问令牌的端点。

为帮助您轻松开始使用 OAuth,Apigee Edge 让您可以使用 政策配置和强制执行 OAuth,而无需编写任何代码。在本主题中,您将了解如何保护您的 API、如何获取访问令牌,以及如何使用这些访问令牌访问受保护的 API。

您组织的默认 OAuth 配置

为方便起见,Apigee Edge 上的所有组织都预先配置了一组实现客户端凭据授权类型的 OAuth 2.0 端点。客户端凭据授权类型定义了签发访问令牌以换取应用凭据的过程。这些应用凭据就是 Apigee Edge 为组织中注册的每个应用签发的使用方键值和密钥对。“客户端凭据”是指使用方键值和密钥对本身。

如需详细了解如何使用边缘开发者服务向应用颁发凭据,请参阅注册应用和管理密钥

因此,将 API 安全方案从 API 密钥验证到 OAuth 客户端凭据相对容易。这两种方案使用相同的使用方键值和密钥来验证客户端应用。不同之处在于客户端凭据提供了一层额外的控制,因为您可以根据需要轻松撤消访问令牌,而无需撤消应用的使用方密钥。如需使用默认 OAuth 端点,您可以使用为组织中的应用生成的任何使用方键值和密钥,从令牌端点检索访问令牌。(您甚至可以为已具有使用方键值和密钥的应用启用客户端凭据。)

有关客户端凭据授权的完整规范,请参阅 OAuth 2.0 规范

使用政策保护您的 API

您需要先配置 API 以在运行时验证 OAuth 访问令牌,然后才能使用访问令牌。为此,可以配置一个 API 代理来validate访问令牌。这意味着,每当应用发出使用您的某个 API 的请求时,该应用都必须提供有效的访问令牌以及相应 API 请求。Apigee Edge 可处理生成、存储和验证呈现的访问令牌背后的复杂性。

创建新的 API 代理时,您可以轻松地向 API 添加 OAuth 验证。当您创建新的 API 代理时,可以添加功能。如下所示,您可以通过选择使用 OAuth v2.0 访问令牌进行安全保护旁边的单选按钮,添加对 OAuth 2.0 访问令牌的验证。选择此选项后,系统会将两项政策附加到新创建的 API 代理,一项用于验证访问令牌,另一项用于剥离访问令牌。

此外,当您选择使用 OAuth v2.0 访问令牌进行安全选项时,发布 API 产品复选框会变为可选状态,并会自动选中。如果您希望在构建新的 API 代理时自动生成产品,请勾选此复选框。自动生成的商品将与新的 API 代理相关联。如果您想将现有产品与此新 API 相关联,请务必取消选中此复选框,以免创建不必要的产品。如需了解产品,请参阅什么是 API 产品?

如果您需要为已存在的 API 代理启用访问令牌验证,只需将 OAuthV2 类型的政策附加到要保护的 API 即可。OAuthV2 政策的工作原理是指定一个操作。如果要验证访问令牌,请指定名为 VerifyAccessToken 的操作。(OAuthV2 政策类型支持的其他类型的操作包括 GenerateAccessToken 和 GenerateRefreshToken。您会在设置 OAuth 端点时了解这些操作。)

OAuthV2 类型的 VerifyOAuthTokens 政策

验证访问令牌的政策示例如下所示。(下表中介绍了具体设置。)

<OAuthV2 name="VerifyOAuthTokens"> 
  <Operation>VerifyAccessToken</Operation> 
</OAuthV2>

政策设置

名称 说明 默认 是否必需?
OAuthV2 政策类型
name API 代理端点配置中引用的政策名称。 不适用
Operation OAuthV2 政策要执行的操作。通过指定 VerifyAccessToken,您可以将政策配置为检查访问令牌请求,并验证访问令牌是否有效、未过期以及是否已获准使用所请求的 API 资源 (URI)。(为了进行此项检查,政策会读取应用获准使用的 API 产品。) 不适用

如需在管理界面中创建此政策,请前往 API > API 代理

从 API 代理列表中,选择 weatherapi

从 weatherapi 的概览中,选择开发视图。

从下拉菜单中选择 New Policy > OAuth v2.0(新建政策 > OAuth v2.0)

选择 OAuth v2.0 政策后,系统会显示 New Policy 配置菜单。

为您的政策指定一个描述性名称,并确保选择 Attach PolicyFlow PreFlowRequest 作为政策连接设置。

选择添加,系统即会创建政策并将其附加到 weatherapi 的请求 PreFlow。

添加政策后,下面的请求 PreFlow 配置将显示在 Designer 窗格中。

如果您在本地使用文本编辑器或 IDE,请将政策附加到要保护的 API 代理的请求 PreFlow 中

<PreFlow>
  <Request>
    <Step><Name>VerifyOAuthTokens</Name></Step>
  </Request>
</PreFlow>

通过将政策附加到请求 PreFlow 中,您可以确保始终对所有请求消息强制执行该政策。

您现在已经使用 OAuth 2.0 客户端凭据保护了 API。接下来,我们将了解如何获取访问令牌并使用它来访问安全的 API。

使用访问令牌访问受保护的资源

现在,weatherapi 已使用 OAuth 2.0 进行保护,应用必须提供访问令牌才能使用该 API。为了访问受保护的资源,该应用会在请求中以“Authorization”HTTP 标头的形式,在请求中呈现一个访问令牌,如下所示:

$ curl -H "Authorization: Bearer ylSkZIjbdWybfs4fUQe9BqP0LH5Z" http://{org_name}-test.apigee.net/weather/forecastrss?w=12797282

由于 API 附加了 OAuthV2 政策,因此 Apigee Edge 将验证提供的访问令牌是否有效,然后授予对该 API 的访问权限,并将天气预报返回给发出请求的应用。

但是,应用如何获取访问令牌?我们将在下一部分介绍相关内容。

如何将客户端凭据交换为访问令牌

应用通过将其使用方密钥/密钥对提供给令牌端点来获取访问令牌。令牌端点在名为 oauth 的 API 代理中配置。因此,应用需要调用 oauth API 代理公开的 API 以获取访问令牌。应用获得访问令牌后,便可重复调用 weatherapi,直到访问令牌过期或访问令牌被撤消为止。

现在,您需要换个方向,将自己视为应用开发者。您要调用 weatherapi,因此您需要为应用获取访问令牌。首先,您需要获取一个使用方密钥和密钥令牌对(也称为“API 密钥”或“应用密钥”)。

您可以在 Apigee Edge 上注册组织中的应用,以获取使用方键值和密钥。

您可以在 Apigee Edge 管理界面中查看组织中的所有应用。

系统会显示在贵组织中注册的应用的列表。

(如果系统未显示任何应用,请参阅注册应用和管理 API 密钥主题,了解如何注册应用。)

从列表中选择一个应用即可查看其详细资料。

在所选应用的详情视图中,记下 Consumer KeyConsumer Secret 字段。这两个值是您将用于获取 OAuth 访问令牌的客户端凭据

$ curl https://api.enterprise.apigee.com/v1/o/{org_name}/apps \
-u myname:mypass 

此调用按应用 ID 返回应用列表。

[ "da496fae-2a04-4a5c-b2d0-709278a6f9db", "50e3e831-175b-4a05-8fb6-05a54701af6e" ]

您可以通过对应用 ID 进行简单 GET 调用来检索应用的配置文件:

$ curl https://api.enterprise.apigee.com/v1/o/{org_name}/apps/{app_id} \
-u myname:mypass 

例如:

$ curl https://api.enterprise.apigee.com/v1/o/{org_name}/apps/da496fae-2a04-4a5c-b2d0-709278a6f9db \
-u myname:mypass 

API 调用会返回您指定应用的配置文件。例如,weatherapp 的应用配置文件具有以下 JSON 表示法:

{
  "accessType" : "read",
  "apiProducts" : [ ],
  "appFamily" : "default",
  "appId" : "da496fae-2a04-4a5c-b2d0-709278a6f9db",
  "attributes" : [ ],
  "callbackUrl" : "http://weatherapp.com",
  "createdAt" : 1380290158713,
  "createdBy" : "noreply_admin@apigee.com",
  "credentials" : [ {
    "apiProducts" : [ {
      "apiproduct" : "PremiumWeatherAPI",
      "status" : "approved"
    } ],
    "attributes" : [ ],
    "consumerKey" : "bBGAQrXgivA9lKu7NMPyoYpVKNhGar6K",
    "consumerSecret" : "hAr4Gn0gA9vAyvI4",
    "expiresAt" : -1,
    "issuedAt" : 1380290161417,
    "scopes" : [ ],
    "status" : "approved"
  } ],
  "developerId" : "5w95xGkpnjzJDBT4",
  "lastModifiedAt" : 1380290158713,
  "lastModifiedBy" : "noreply_admin@apigee.com",
  "name" : "weatherapp",
  "scopes" : [ ],
  "status" : "approved"
}

记下 consumerKeyconsumerSecret 的值。您可以使用这些凭据获取访问令牌,方法是在 HTTP 请求中将这些凭据作为基本身份验证凭据显示,如下所示。授权类型以查询参数的形式呈现在请求中。(请务必更改变量 {org_name} 的值,以反映 Apigee Edge 上的组织名称。)

创建获取访问令牌的请求

在以下请求中,将 client_id 替换成 consumerKey 的值。将 client_secret 替换为相关 consumerSecret 的值。

$ curl https://{org_name}-test.apigee.net/oauth/client_credential/accesstoken?grant_type=client_credentials -X POST -d 'client_id=bBGAQrXgivA9lKu7NMPyoYpVKNhGar6K&client_secret=hAr4Gn0gA9vAyvI4'

API 服务会验证使用方键值和密钥,然后生成包含此应用访问令牌的响应:

{
  "issued_at" : "1380892555397",
  "application_name" : "957aa73f-25c2-4ead-8021-adc01f0d2c6b",
  "scope" : "",
  "status" : "approved",
  "api_product_list" : "[oauth-test]",
  "expires_in" : "3599",
  "developer.email" : "tesla@weathersample.com",
  "organization_id" : "0",
  "client_id" : "bBGAQrXgivA9lKu7NMPyoYpVKNhGar6K",
  "access_token" : "ylSkZIjbdWybfs4fUQe9BqP0LH5Z",
  "organization_name" : "rqa",
  "refresh_token_expires_in" : "0",
  "refresh_count" : "0"
}

请注意上述响应中的 access_token 值。这是应用用于获取对受保护资源的运行时访问权限的访问令牌。此应用的访问令牌为 ylSkZIjbdWybfs4fUQe9BqP0LH5Z

您现在拥有一个有效的访问令牌 ylSkZIjbdWybfs4fUQe9BqP0LH5Z,它可用于访问受保护的 API。

使用默认 OAuth 配置

Apigee Edge 上的每个组织(甚至是免费试用组织)都预配有一个 OAuth 令牌端点。端点已预先配置了名为 oauth 的 API 代理中的政策。在 Apigee Edge 上创建帐号后,您就可以开始使用令牌端点。

默认 OAuth 端点提供以下端点 URI:

/oauth/client_credential/accesstoken

将此 URI 发布至需要获取访问令牌的开发者。应用开发者将其应用配置为调用此端点,并提供其使用方密钥和密文对,以获取访问令牌。

默认客户端凭据令牌端点通过网络在以下网址上公开:

https://{org_name}-{env_name}.apigee.net/oauth/client_credential/accesstoken

例如,如果您的单位名称为“apimakers”,则网址为:

https://apimakers-test.apigee.net/oauth/client_credential/accesstoken

这是开发者为获取访问令牌而调用的网址。

三方模式 OAuth 配置

三足式 OAuth 配置(授权代码、隐式和密码授权类型)要求您(API 提供商)对应用的最终用户进行身份验证。由于每个组织都会以不同的方式对用户进行身份验证,因此需要通过一些政策自定义或代码来将 OAuth 与用户存储区集成。例如,您的所有用户都可能存储在 Active Directory、LDAP 或某个其他用户存储区中。要启动并运行三足式 OAuth,您需要将针对此用户存储的检查集成到整个 OAuth 流程中。

OAuth 1.0a

如需详细了解 OAuth 1.0a 政策,请参阅 OAuth v1.0a 政策

获取帮助

如需帮助,请参阅 Apigee 客户支持