使用 OAuth 2 进行基于令牌的身份验证。您可以管理 OAuth 令牌以及应用,即用于生成令牌的 API 客户端的服务器端系统。通过将 OAuth 令牌作为 HTTP 验证标头的一部分,您可以自行验证身份,并调整除了基本 RBAC 权限外的限制性权限的程度。如需 OAuth 2 规格的详情,请参阅 RFC 6749。
如需有关使用 manage
实用程序创建令牌的详情,请参考 令牌和会话管理 部分。
应用和令牌可以作为 /api/<version>/applications
和 /api/<version>/tokens
的顶层资源进行管理。这些资源也可以由 /api/<version>/users/N/<resource>
的用户相应地访问。可以通过对 api/<version>/applications
或 /api/<version>/users/N/applications
发出 POST 来创建应用。
每个 OAuth 2 应用都代表了服务器端的一个特定的 API 客户端。对于 API 客户端,要通过应用令牌使用 API,它必须首先具有一个应用并签发了一个访问令牌。每个应用都可通过主键:/api/<version>/applications/<pk>/
访问。这里是一个典型的应用:
{
"id": 1,
"type": "o_auth2_application",
"url": "/api/v2/applications/2/",
"related": {
"tokens": "/api/v2/applications/2/tokens/"
},
"summary_fields": {
"organization": {
"id": 1,
"name": "Default",
"description": ""
},
"user_capabilities": {
"edit": true,
"delete": true
},
"tokens": {
"count": 0,
"results": []
}
},
"created": "2018-07-02T21:16:45.824400Z",
"modified": "2018-07-02T21:16:45.824514Z",
"name": "My Application",
"description": "",
"client_id": "Ecmc6RjjhKUOWJzDYEP8TZ35P3dvsKt0AKdIjgHV",
"client_secret": "7Ft7ym8MpE54yWGUNvxxg6KqGwPFsyhYn9QQfYHlgBxai74Qp1GE4zsvJduOfSFkTfWFnPzYpxqcRsy1KacD0HH0vOAQUDJDCidByMiUIH4YQKtGFM1zE1dACYbpN44E",
"client_type": "confidential",
"redirect_uris": "",
"authorization_grant_type": "password",
"skip_authorization": false,
"organization": 1
}
如上例所示,name
是应用的人类可读标识符。其它字段(如 client_id
和 redirect_uris
)主要用于 OAuth2 授权,它在后面的:ref:ag_use_oauth_pat 中介绍。
client_id
和 client_secret
字段的值在创建过程中生成 ,它们是应用的不可编辑标识符,而在创建时还需要 organization
和 authorization_grant_type
,并变为不可编辑。
应用的访问规则如下:
系统管理员可以查看并操作系统中的所有应用
机构管理员可以查看和操作属于机构成员的所有应用
其他用户只能查看、更新和删除自己的应用,但无法创建新应用
另一方面,令牌是用于实际身份验证传入请求和屏蔽底层用户权限的资源。令牌可以通过两个方法创建:
使用 application
和 scope
字段发布到 /api/v2/tokens/
端点,以指向相关应用并指定令牌范围
使用 scope
字段发布到 /api/v2/applications/<pk>/tokens/
端点(父应用会自动链接)
单独的令牌可以通过它们的主键:/api/<version>/tokens/<pk>/
访问。这里是一个典型令牌的示例:
{
"id": 4,
"type": "o_auth2_access_token",
"url": "/api/v2/tokens/4/",
"related": {
"user": "/api/v2/users/1/",
"application": "/api/v2/applications/1/",
"activity_stream": "/api/v2/tokens/4/activity_stream/"
},
"summary_fields": {
"application": {
"id": 1,
"name": "Default application for root",
"client_id": "mcU5J5uGQcEQMgAZyr5JUnM3BqBJpgbgL9fLOVch"
},
"user": {
"id": 1,
"username": "root",
"first_name": "",
"last_name": ""
}
},
"created": "2018-02-23T14:39:32.618932Z",
"modified": "2018-02-23T14:39:32.643626Z",
"description": "App Token Test",
"user": 1,
"token": "*************",
"refresh_token": "*************",
"application": 1,
"expires": "2018-02-24T00:39:32.618279Z",
"scope": "read"
},
对于 OAuth 2 令牌,唯一完全可编辑的字段是 scope
和 description
。application
字段在更新时不可编辑,且所有其他字段完全不可编辑,并在创建过程中自动填充,如下所示:
user
字段与为其创建令牌的用户对应,在本例中,也是创建令牌的用户
expires
根据控制器配置设置生成 OAUTH2_PROVIDER
token
和 refresh_token
是自动生成的、没有冲突的随机字符串
应用令牌和个人访问令牌都显示在 /api/v2/tokens/
端点中。个人访问令牌中的 application
字段始终为 null。这是区分两种令牌的好方法。
令牌的访问规则如下:
如果用户能够查看相关应用,则可以创建令牌;并且用户也可以为自己创建个人令牌。
系统管理员可以查看并操作系统中的每个令牌
机构管理员可以查看和操作属于机构成员的所有令牌
系统审核员(Auditor)可查看所有令牌和应用
其他普通用户只能查看和操作自己的令牌
注解
用户只能在创建时查看令牌或刷新令牌值。
获取 OAuth 2 令牌的最简单和最常见的方法是在 /api/v2/users/<userid>/personal_tokens/
端点上创建个人访问令牌,如下例所示:
curl -XPOST -k -H "Content-type: application/json" -d '{"description":"Personal controller CLI token", "application":null, "scope":"write"}' https://<USERNAME>:<PASSWORD>@<CONTROLLER_SERVER>/api/v2/users/<USER_ID>/personal_tokens/ | python -m json.tool
如果已安装,您还可以通过 jq
对 JSON 输出进行 pipe 操作。
以下是使用个人令牌访问使用 curl 的 API 端点的示例:
curl -k -H "Authorization: Bearer <token>" -H "Content-Type: application/json" -X POST -d '{}' https://controller/api/v2/job_templates/5/launch/
在 automation controller 中,OAuth 2 系统构建在 Django Oauth Toolkit 上,为授权、撤销和刷新令牌提供专用端点。这些端点可以在 /api/v2/users/<USER_ID>/personal_tokens/
端点下找到,它还提供了这些端点的一些用法的详细示例。这些特殊 OAuth 2 端点仅支持使用 x-www-form-urlencoded
Content-type,因此没有 api/o/*
端点接受 application/json
。
注解
您还可以通过为应用程序类型指定 null
,使用 /api/o/token
端点来请求令牌。
或者,您可以通过控制器用户界面为用户 add tokens,并配置访问令牌的过期时间及其关联的刷新令牌(如果适用)。
OAuth 2 令牌的范围是一个由空格分隔的、包括有效范围关键字(’read’ 和 ’write’)的字符串。这些关键字可以被配置,用来指定经过身份验证的 API 客户端的权限级别。通过使用 read 和 write 范围,可以在 automation controller 的基于角色的访问控制 (RBAC) 权限系统上提供一个掩码层。”write” 范围为经过身份验证的用户提供了 RBAC 系统的完整权限,而“read”范围则仅为经过身份验证的用户提供读取权限。请注意,“write”包括了“read”的权限。
例如,如果您对作业模板有管理权限,则当通过会话或基本身份验证进行了身份验证后,可以查看、修改、启动和删除作业模板。相反,如果您使用 OAuth 2 令牌进行身份验证,而相关的令牌范围为“read”,您只能查看,但不能操作或启动作业模板,即使管理员也是如此。如果令牌范围是“write”或“read write”,则可以作为管理员充分利用作业模板。
要获取和使用令牌,首先请创建一个应用令牌:
创建一个应用,authorization_grant_type
设置为 password
。HTTP 将以下内容 POST 到 /api/v2/applications/
端点(提供您自己的机构 ID):
{
"name": "Admin Internal Application",
"description": "For use by secure services & clients. ",
"client_type": "confidential",
"redirect_uris": "",
"authorization_grant_type": "password",
"skip_authorization": false,
"organization": <organization-id>
}
创建一个端点并 POST 到 /api/v2/tokens/
:
{
"description": "My Access Token",
"application": <application-id>,
"scope": "write"
}
这会返回 <token-value>,可以用来为将来的请求进行身份验证(这不会再次显示)。
使用令牌访问资源。以下使用 curl 作为示例:
curl -H "Authorization: Bearer <token-value>" -H "Content-Type: application/json" -X GET https://<controller>/api/v2/users/
如果您还没有设置 CA 且正在使用 SSL,则可能需要 -k
标志。
要撤销令牌,您可以使用该令牌的 ID 在该令牌的详情页面上进行 DELETE。例如:
curl -ku <user>:<password> -X DELETE https://<controller>/api/v2/tokens/<pk>/
同样,使用令牌:
curl -H "Authorization: Bearer <token-value>" -X DELETE https://<controller>/api/v2/tokens/<pk>/ -k
本页列出了用于授权、令牌刷新和撤销的 OAuth 2 实用程序端点。/api/o/
端点不会在浏览器中使用,且不支持 HTTP GET。这里介绍的端点严格遵循 OAuth 2 的 RFC 规格,因此使用它进行详细参考。以下示例是控制器中这些端点的典型用法,特别是在使用各种授权类型创建应用时:
授权代码
Password
注解
您可以使用控制器用户界面执行此处所述的全部应用功能。如需更多详情,请参阅 Automation Controller User Guide 的 Applications 部分。