10. 使用 API 的身份验证方法

本章介绍基本身份验证和会话身份验证方法、每种方法的最佳用例以及示例。

AWX 旨在帮助组织使用可视化仪表板集中控制和管理其自动化，同时提供 REST API 以更深入地与其他工具集成。AWX 支持多种身份验证方法，以便轻松地将 AWX 集成到现有工具和流程中，从而确保合适的人员可以访问 AWX 资源。

10.1. 会话身份验证

当直接登录到 AWX 的 API 或 UI 以手动创建资源（清单、项目、作业模板）并在浏览器中启动作业时，使用会话身份验证。使用此方法，您可以长时间保持登录状态，而不仅仅是针对该 HTTP 请求，例如，在浏览器（如 Chrome 或 Firefox）中浏览 UI 或 API 时。当用户登录时，会创建一个会话 cookie，这使得用户在导航到 AWX 中的不同页面时可以保持登录状态。以下是客户端和服务器之间在会话中发生的通信。

../_images/session-auth-architecture.png

使用 curl 工具，您可以查看登录 AWX 时发生的活动。

  1. GET 到 /api/login/ 端点以获取 csrftoken cookie。

curl -k -c - https://<awx-host>/api/login/

localhost       FALSE   /       FALSE   0   csrftoken
AswSFn5p1qQvaX4KoRZN6A5yer0Pq0VG2cXMTzZnzuhaY0L4tiidYqwf5PXZckuj

  1. POST 到 /api/login/ 端点，其中包含用户名、密码和 X-CSRFToken=<token-value>。

curl -X POST -H 'Content-Type: application/x-www-form-urlencoded' \
--referer https://<awx-host>/api/login/ \
-H 'X-CSRFToken: K580zVVm0rWX8pmNylz5ygTPamgUJxifrdJY0UDtMMoOis5Q1UOxRmV9918BUBIN' \
--data 'username=root&password=reverse' \
--cookie 'csrftoken=K580zVVm0rWX8pmNylz5ygTPamgUJxifrdJY0UDtMMoOis5Q1UOxRmV9918BUBIN' \
https://<awx-host>/api/login/ -k -D - -o /dev/null

所有这些操作都在您在浏览器中登录到 UI 或 API 时由 AWX 完成，并且仅应在浏览器中进行身份验证时使用。

典型的响应可能如下所示

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.1.1. 使用会话限制

设置会话限制允许管理员限制每个用户或每个 IP 地址的同时会话数。

为用户用来登录的每个浏览器创建一个会话，这会强制用户在超过管理员定义的最大值后注销任何额外的会话。

根据您的特定设置，会话限制可能很重要。例如，您可能只想让系统上的单个用户每个设备只有一个登录（用户可以在其工作笔记本电脑、手机或家用电脑上登录）。在这种情况下，您需要创建一个等于 1（一个）的会话限制。例如，如果用户在其笔记本电脑上登录，然后使用其手机登录，则其笔记本电脑会话将过期（超时），并且只有手机上的登录仍然有效。主动会话限制将在会话空闲时将用户踢出。默认值为 **-1**，这完全禁用允许的最大会话数，这意味着您可以拥有任意数量的会话，而没有施加限制。

虽然会话计数可以非常有限，但它们也可以扩展到涵盖组织所需的任意数量的会话登录。

当用户登录并且其登录导致其他用户注销时，表示已达到会话限制，并且注销的用户会收到有关注销原因的通知。

注意

为了最好地利用会话限制，请通过将值更改为 False 来禁用 AUTH_BASIC_ENABLED，因为它超出了会话限制执行的范围。

10.2. 基本身份验证

基本身份验证（基本身份验证）是无状态的，因此必须通过授权标头将 base64 编码的 username 和 password 与每个请求一起发送。这可用于来自 curl 请求、python 脚本或对 API 的单个请求的 API 调用。curl 示例

# the --user flag adds this Authorization header for us
curl -X GET --user 'user:password' https://<awx-host>/api/v2/credentials -k -L

有关基本 HTTP 身份验证方案的更多信息，请参阅 RFC 7617。