10. 使用 API 的验证方法¶
本章论述了多个企业级身份验证方法，每个方法的最佳用例和示例：
Automation controller 为机构提供了使用一个仪表板来以中央化的方式控制自动化的功能。处理开箱即用的控制功能还，它同时提供了一个 REST API 用于与您的其他工具进行深层次的集成。Automation controller 支持通过多种身份验证方法轻松将控制器嵌入到现有工具和进程中，以帮助适当的人员访问控制器资源。
10.1. 会话身份验证¶
当登录到 automation controller 的 API 或 UI 时，使用会话身份验证来手动创建资源（清单、项目、作业模板）并在浏览器中启动作业。 使用此方法，您可以在一段时间内保持登录的状态（不仅仅在该 HTTP 请求中，对于使用 UI 进行浏览或在如 Chrome 或 Firefox 等浏览器中使用 API 时也时如此）。 当用户登录时，会创建一个会话 Cookie，当用户访问 automation controller 中的不同页面时也让用户保持登录状态。 以下显示了客户端和服务器间的通信。
使用 curl 工具，您可以看到登录到控制器时发生的活动。
GET 到
/api/login/端点以获取csrftokenCookie。
curl -k -c - https://<controller-host>/api/login/
localhost FALSE / FALSE 0 csrftoken
AswSFn5p1qQvaX4KoRZN6A5yer0Pq0VG2cXMTzZnzuhaY0L4tiidYqwf5PXZckuj
POST 到<token-value> 端点，使用用户名、密码和 X-CSRFToken=``/api/login/``。
curl -X POST -H 'Content-Type: application/x-www-form-urlencoded' \
--referer https://<controller-host>/api/login/ \
-H 'X-CSRFToken: K580zVVm0rWX8pmNylz5ygTPamgUJxifrdJY0UDtMMoOis5Q1UOxRmV9918BUBIN' \
--data 'username=root&password=reverse' \
--cookie 'csrftoken=K580zVVm0rWX8pmNylz5ygTPamgUJxifrdJY0UDtMMoOis5Q1UOxRmV9918BUBIN' \
https://<controller-host>/api/login/ -k -D - -o /dev/null
当您登陆到 UI 或在浏览器中使用 API时，所有这一切都由 automation controller 完成，这只在浏览器中进行身份验证时才应使用。有关在程序中集成 automation controller 的信息，请参阅 OAuth 2 令牌身份验证。
一个典型的响应可能类似如下：
Server: nginx
Date: <current date>
Content-Type: text/html; charset=utf-8
Content-Length: 0
Connection: keep-alive
Location: /accounts/profile/
X-API-Session-Cookie-Name: awx_sessionid
Expires: <date>
Cache-Control: max-age=0, no-cache, no-store, must-revalidate, private
Vary: Cookie, Accept-Language, Origin
Session-Timeout: 1800
Content-Language: en
X-API-Total-Time: 0.377s
X-API-Request-Id: 700826696425433fb0c8807cd40c00a0
Access-Control-Expose-Headers: X-API-Request-Id
Set-Cookie: userLoggedIn=true; Path=/
Set-Cookie: current_user=<user cookie data>; Path=/
Set-Cookie: csrftoken=<csrftoken>; Path=/; SameSite=Lax
Set-Cookie: awx_sessionid=<your session id>; expires=<date>; HttpOnly; Max-Age=1800; Path=/; SameSite=Lax
Strict-Transport-Security: max-age=15768000
当使用此方法成功验证用户后，服务器将生成一个名为 X-API-Session-Cookie-Name 的标头，指示会话 Cookie 的配置名称。默认值为 awx_session_id，稍后您可以在 Set-Cookie 标头中看到。
注解
可以通过在 SESSION_COOKIE_AGE 参数中指定会话过期时间来更改会话过期时间。如需更多详情，请参阅 使用会话限制。
10.2. 基本身份验证¶
基本身份验证(Basic Auth)是无状态的，因此，base64 编码的 username 和 password 必须通过授权标头与每个请求一起发送。这可用于来自 curl 请求、python 脚本的 API 调用，或单独的对 API 的请求。如果可能，建议使用 OAuth 2 令牌身份验证 访问 API。
使用 curl 的示例：
curl -X GET -H 'Authorization: Basic dXNlcjpwYXNzd29yZA==’ https://<controller-host>/api/v2/credentials -k -L
# the --user flag adds this Authorization header for us
curl -X GET --user 'user:password' https://<controller-host>/api/v2/credentials -k -L
有关基本 HTTP 验证方案的详情，请参考 RFC 7617。
注解
您可以从控制器 UI 设置菜单的 Miscellaneous Authentication 设置中禁用 Basic Auth：
10.3. OAuth 2 令牌身份验证¶
OAuth（Open Authorization）是基于令牌的身份验证和授权的开放标准。 在以编程方式与控制器 API 交互时，通常使用 OAuth 2 身份验证。 与 Basic Auth 一样，通过 Authorization 标头向每个 API 请求提供一个 OAuth 2 令牌。 与 Basic Auth 不同的是，OAuth 2 令牌带有一个可配置的超时，并可以被限制。 令牌具有可配置的过期时间，管理员可以根据需要，为某个用户或整个 automation controller 系统撤销。 这可以通过 revoke_oauth2_tokens 管理命令完成（在 Automation Controller Administration Guide 中进行了详细介绍），或者使用 API（如 撤销访问令牌 所示）。
注解
出于安全目的，在默认情况下，不允许 SSO 创建的外部用户生成 OAuth 令牌。这可以通过在控制器 UI 设置菜单的 Miscellaneous Authentication 设置中进行更改：
在 automation controller 中获取 OAuth 2 访问令牌的不同方法是：
个人访问令牌(PAT)
应用程序令牌：密码授权类型
应用程序令牌：隐性授权类型
应用程序令牌：授权代码授权类型
有关以上方法的更多信息，请参阅 Automation Controller Administration Guide 中的 基于令牌的验证。
首先，用户需要在 API 中创建 OAuth 2 访问令牌，或在 UI 中的用户 Tokens 标签页中创建 OAuth 2 访问令牌。有关通过 UI 创建它们的详情，请参阅 Users - Tokens。有关本例中的 PAT 方法，使用 PAT 方法在 API 中创建令牌。令牌创建后，用户可以设置范围。
注解
可以在系统范围内配置令牌的过期时间。如需更多详情，请参阅 将 OAuth 2 令牌系统用于个人访问令牌 (PAT)。
令牌身份验证最适合用于任何 automation controller API 的编程使用，如 Python 脚本或 curl 等工具，如创建 PAT（不带关联应用程序）的示例。
curl 示例
curl -u user:password -k -X POST https://<controller-host>/api/v2/tokens/
此调用将返回 JSON 数据，如下所示：
token 属性的值现在是您可以用来为 automation controller 资源执行 GET 请求（如 Hosts）的值。
curl -k -X POST \
-H “Content-Type: application/json”
-H “Authorization: Bearer <oauth2-token-value>” \
https://<controller-host>/api/v2/hosts/
同样，您可以通过向要启动的作业模板发出 POST 来启动作业。
curl -k -X POST \
-H "Authorization: Bearer <oauth2-token-value>" \
-H "Content-Type: application/json" \
--data '{"limit" : "ansible"}' \
https://<controller-host>/api/v2/job_templates/14/launch/
Python 示例
awxkit 是一个开源工具，它可让您轻松使用 HTTP 请求来访问 automation controller API。您可以使用 awxkit login 命令通过 awxkit 代表您 获取 PAT。如需更多详情，请参阅 AWX Command Line Interface。
有关如何在集成外部应用程序的 automation controller 中使用 OAuth 2 的更多信息，请参阅 Automation Controller Administration Guide 中的 基于令牌的验证。
如果您需要编写自定义请求，您可以使用 Python library requests 编写 Python 脚本，如下例所示：
import requests
oauth2_token_value = 'y1Q8ye4hPvT61aQq63Da6N1C25jiA' # your token value from controller
url = 'https://<controller-host>/api/v2/users/'
payload = {}
headers = {'Authorization': 'Bearer ' + oauth2_token_value,}
# makes request to controller user endpoint
response = requests.request('GET', url, headers=headers, data=payload,
allow_redirects=False, verify=False)
# prints json returned from controller with formatting
print(json.dumps(response.json(), indent=4, sort_keys=True))
10.4. SSO 身份验证¶
单点登录(SSO)身份验证方法与其它方法不同，因为用户的身份验证发生在 automation controller 的外部，如 Google SSO、Azure SSO、SAML 或 GitHub。例如，GitHub SSO，GitHub 是真实的来源，它根据您发送了控制器的用户名和密码来验证您的身份。
您可以使用带有中央身份提供程序的大型机构中的 automation controller 配置 SSO 身份验证。当您在控制器中配置了 SSO 方法后，该 SSO 的按钮将出现在登录屏幕中。如果您点击该按钮，它将把您重定向到身份提供程序，在 GitHub 中，您将会显示您的凭证。如果该身份提供程序成功验证了您的凭证，则控制器将会产生一个用户。
有关各种支持的 SSO 验证方法，请参阅 Automation Controller Administration Guide 中的 设置社交身份认证 和 设置企业级身份验证。