OTDS 身份验证的 OAuth 2.0
0/5 (0投票)
本文档提供了将 OTDS 10.5 Patch 6 配置为 OAuth 2.0 授权服务器的分步指南。它还通过一个示例场景，演示了如何使用 OAuth 2.0 资源所有者密码凭据授权访问 RESTful API。
本文档详细介绍了如何将 OTDS 10.5 Patch 6 配置为 OAuth 2.0 授权服务器，并通过一个示例场景，演示了如何使用 OAuth 2.0 资源所有者密码凭据授权来授权访问 RESTful API。
必备组件
- OTDS 10.5 Patch 6（或更高版本）。您可以在 OpenText Knowledge Centre 此处下载。
安装和配置 OTDS
有关安装和基本配置的详细信息，请参阅 OTDS 文档。
本文档假设您的 OTDS 主机地址为 https://:8080。
您至少需要一个非同步用户分区，其中配置了用户条目以使用密码凭据进行登录。换句话说，如果您有一个用户可以登录到您的 OTDS 登录页面：https://:8080/otdsws/login，那么您就可以开始了（至少，这可以是您的管理员用户 [email protected]）。
启用 HTTP 上的 OAuth 2.0
OAuth 2.0 要求所有 OAuth 2.0 流量都通过 SSL / TLS 安全通道进行。默认情况下，OTDS 会遵守此规则，但出于开发原因，可以配置为允许通过 HTTP 进行 OAuth 2.0 流量。建议您在开发环境中启用此功能以协助调试。
要访问 OTDS 管理 UI，请在浏览器中打开 https://:8080/otds-admin/。
以用户 [email protected] 的身份登录 OTDS Web 管理控制台，找到系统属性页面。单击“添加”，然后添加一个名为 directory.auth.EnforceSSL、值为 false 的系统属性，然后单击“保存”。
创建您的 OTDS OAuth 2.0 客户端分区
目前，注册客户端是一个手动过程。OTDS 将每个 OAuth 2.0 客户端表示为名为 OAuthClients 的特殊用户分区中的一个用户。创建此分区。
您需要查看分区成员才能创建一个代表您的 OAuth 2.0 客户端的用户。
注意：本文档假设正在创建的客户端无法保守 OAuth 2.0 客户端机密（例如，基于浏览器的 Web 应用程序或本地移动客户端），因此我们在此不为“用户”指定密码。给客户端起一个名字，然后单击“保存”。
注意：OTDS 假定所有客户端都创建在 OAuthClients 用户分区的根位置（组织单位）。请在分区的“用户”选项卡上验证这一点。
创建代表您的服务/OAuth 2.0 资源的 OTDS 资源
您的客户端将通过 API 访问您的资源。OTDS 需要了解您的资源，这通过 OTDS 资源对象进行建模。您需要创建一个 OTDS 资源，并将您的用户分配给为该资源创建的访问角色。完成以下步骤。
从“资源”选项卡创建新的 OTDS 资源。
只需为其命名，然后单击“保存”。
您将看到一个屏幕，告知您需要激活新资源。这是一次性操作，通常在您的 OpenText 服务器产品中启用 OTDS 集成时进行。
复制资源标识符并记下资源名称。
为了本文档的目的，我们将使用 OTDS Swagger 页面来激活资源。在浏览器中，访问 https://:8080/otdsws/api/#!resources，然后展开“激活资源”部分。输入上一步中的资源标识符，然后单击“试用”！一切顺利，您将看到响应代码 200。您还将看到响应值 secret_key，出于本教程的目的，您可以忽略它。
接下来，您需要授予某些用户访问新创建的资源的权限。在此示例中，我将授予管理用户分区中的任何用户访问我的资源的权限。
在管理 UI 中，找到为您的资源自动创建的 OTDS 访问角色，然后单击“操作”/“查看访问角色详细信息”。
要确保您希望针对新资源进行身份验证的用户能够访问，请确保他们或他们所属的容器已添加到访问角色中。在此，我添加了整个 otds.admin 分区，因为我将使用 [email protected] 用户进行测试。
关闭对话框，然后单击“保存”。
现在您已准备好使用 OAuth 2.0 进行身份验证。
获取 OAuth 2.0 访问令牌和刷新令牌
OTDS 公开的 OAuth 2.0 token 和 authentication 端点都位于 https://:8080/otdsws/login。要请求访问令牌，您需要将以下参数 POST 到此端点。
+------------+----------------------------+------------------------------------------------------+
| Name | Value | Notes |
+------------+----------------------------+------------------------------------------------------+
| grant_type | "password" | Informs the OAuth server that this request |
| | | is for Resource Owner Password Credentials |
| | | Grant |
+------------+----------------------------+------------------------------------------------------+
| client_id | <client-id> | The name of the client - in this example |
| | | "pete-client-1" |
+------------+----------------------------+------------------------------------------------------+
| username | <user-id> | The user id - in this example |
| | | "otadmin@otds.admin" |
+------------+----------------------------+------------------------------------------------------+
| password | <password> | The password for the user to authenticated |
+------------+----------------------------+------------------------------------------------------+
| scope | "resource:"<resource+name> | The scope is tied to a single resource, and |
| | | is formatted as "resource:<resource+name>", |
| | | where the <resource+name> is the name of |
| | | your resource, but with any spaces replaced with "+" |
+------------+----------------------------+------------------------------------------------------+
重要：如果您的资源名称包含空格，则必须将其替换为“+”字符。例如，scope=resource:My Resource 变为 scope=resource:My+Resource。
以下是一个请求示例。
POST http://otds.myhost.com:8080/otdsws/login HTTP/1.1
Accept: application/x-www-form-urlencoded
Content-Type: application/x-www-form-urlencoded
User-Agent: Jersey/2.19 (HttpUrlConnection 1.8.0_45)
Host: otds.myhost.com:8080
Connection: keep-alive
Content-Length: 133
password=****&grant_type=password&scope=resource%3Apete-test-server-1&client_id=pete-client-1&username=otadmin%40otds.admin
如果请求获得批准，您将看到一个包含以下属性的响应，作为 JSON 对象返回。
+---------------+-------------------------------------------------------------+
| Name | Notes |
+---------------+-------------------------------------------------------------+
| access_token | The OAuth 2.0 Access Token |
+---------------+-------------------------------------------------------------+
| expires_in | The expiry time of the granted token, in seconds |
+---------------+-------------------------------------------------------------+
| refresh_token | Used to request a new access_token (e.g. once the delivered |
| | token has expired or is about to expire) |
+---------------+-------------------------------------------------------------+
| token_type | Always "Bearer" for this flow |
+---------------+-------------------------------------------------------------+
以下是一个响应示例。
HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
Transfer-Encoding: chunked
Date: Fri, 07 Aug 2015 15:43:02 GMT
3ea
{"token_type":"Bearer","expires_in":3600,"refresh_token":"ABQkq...","access_token":"ABSrk..."}
0
使用访问令牌访问资源 API
当客户端调用 REST 端点时，它应将提供的访问令牌包含在标准的 HTTP Authorization 标头中，格式为 Authorization: Bearer <access-token>。以下是一个请求示例。
GET http://poliver-e6520:8080/myresource/webresources/rest HTTP/1.1
Accept: application/json
Authorization: Bearer ABTYWpGvDKHyv5KfC<snip>Gv6wdbDo
User-Agent: Jersey/2.19 (HttpUrlConnection 1.8.0_51)
Host: poliver-e6520:8080
Connection: keep-alive
从资源服务器验证访问令牌
在上述步骤中，您的客户端请求了一个特定资源的访问令牌。当客户端发出 API 请求时，它会在 Authorization 标头中提供访问令牌，如上所示。
当资源在 OTDS 中注册时，它被分配了一个资源标识符。当您的资源服务器希望验证访问令牌时，它必须将授予的访问令牌和资源标识符作为一个 JSON 对象提交给 OTDS 进行验证，提交到 OTDS REST 端点 https://:8080/otdsws/v1/authentication/tokeninfo，如下例所示。
POST https://:8080/otdsws/v1/authentication/oauth/tokeninfo HTTP/1.1
Accept: application/json
Content-Type: application/json
User-Agent: Jersey/2.5.1 (HttpUrlConnection 1.8.0_51)
Cache-Control: no-cache
Pragma: no-cache
Host: localhost:8080
Connection: keep-alive
Content-Length: 505
{"token":"ABTYWpG<snip>6wdbDo","resource_id":"60832916-a568-4980-99da-f0338f899224"}
如果访问令牌有效，OTDS 将响应有关令牌创建的用户帐户的各种详细信息。如果令牌无效、属于不同资源或已过期，OTDS 将相应地响应一条描述性错误消息。
下表列出了预期的 HTTP 状态码和原因。
+-------------+-----------------------------------------------------------------------------+
| HTTP Status | Notes |
+-------------+-----------------------------------------------------------------------------+
| 200 | OK - Token info is returned |
+-------------+-----------------------------------------------------------------------------+
| 401 | User does not have access to the specified resource, or error parsing token |
+-------------+-----------------------------------------------------------------------------+
| 410 | Expired or revoked token |
+-------------+-----------------------------------------------------------------------------+
| 400 | Invalid resource ID |
+-------------+-----------------------------------------------------------------------------+
刷新访问令牌
客户端可以在任何时候通过将刷新令牌与最初指定的客户端 ID 和 refresh_token 的授权类型一起 POST 到 OTDS OAuth 令牌端点 https://:8080/otdsws/login 来请求新的访问令牌。
+---------------+----------------------------+---------------------------------------------------+
| Name | Value | Notes |
+---------------+----------------------------+---------------------------------------------------+
| grant_type | "refresh_token" | Informs the OAuth server that this request |
| | | is for a token refresh |
| | | Grant |
+---------------+----------------------------+---------------------------------------------------+
| client_id | <client-id> | The name of the client - in this example |
| | | "pete-client-1" |
+---------------+----------------------------+---------------------------------------------------+
| refresh_token | <refresh-token> | The refresh token |
+---------------+----------------------------+---------------------------------------------------+
建议您的客户端预emptive执行此操作，而不是在收到资源身份验证错误后执行。事实上，许多客户端 OAuth 框架会自动为您执行此操作。
以下是一个请求示例。
POST https://:8080/otdsws/login HTTP/1.1
Accept: application/x-www-form-urlencoded
Content-Type: application/x-www-form-urlencoded
User-Agent: Jersey/2.19 (HttpUrlConnection 1.8.0_51)
Host: localhost:8080
Connection: keep-alive
Content-Length: 547
refresh_token=ABRT0Eh<snip>PSgZvnGA*&grant_type=refresh_token&client_id=pete-client-1
以下是一个响应示例。
HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
Transfer-Encoding: chunked
Date: Fri, 07 Aug 2015 18:25:07 GMT
21f
{"token_type":"Bearer","expires_in":3600,"access_token":"ABQ96H4xDG<snip>yl1_HKuIM*"}
0
撤销刷新和访问令牌
您可以通过向 OTDS 服务器发出 DELETE 请求来撤销访问令牌，URL 为 https://:8080/otdsws/v1/authentication/oauth/<token>。
以下是一个请求示例。
DELETE https://:8080/otdsws/v1/authentication/oauth/ABTbx9R3<snip>CQUf_79al14N HTTP/1.1
Host: localhost:8080
Connection: keep-alive
Content-Length: 0
Content-Type: application/json
这将产生以下示例响应。
HTTP/1.1 204 No Content
Server: Apache-Coyote/1.1
Access-Control-Allow-Origin: https://:8080
Access-Control-Allow-Methods: DELETE, HEAD, GET, OPTIONS, POST, PUT
Access-Control-Allow-Headers: Content-Type
Access-Control-Max-Age: 1728000
Content-Type: application/json
Date: Fri, 07 Aug 2015 18:36:55 GMT
当 OTDS 收到撤销访问令牌的请求时，任何关联的刷新令牌也将被撤销。