« 获取安全索引设置 获取用户权限 API »
Elastic 文档 ›Elasticsearch 指南 [8.14] ›REST API ›安全 API

获取令牌 API

编辑

获取令牌 API编辑

创建无需基本身份验证即可访问的持有者令牌。

请求编辑

POST /_security/oauth2/token

先决条件编辑

  • 要使用此 API，您必须具有 manage_token 集群权限。

描述编辑

令牌由 Elasticsearch 令牌服务创建，当您在 HTTP 接口上配置 TLS 时，该服务会自动启用。请参阅为 Elasticsearch 加密 HTTP 客户端通信。或者，您可以显式启用 xpack.security.authc.token.enabled 设置。当您在生产模式下运行时，引导检查会阻止您启用令牌服务，除非您还在 HTTP 接口上启用了 TLS。

获取令牌 API 采用与典型的 OAuth 2.0 令牌 API 相同的参数，但使用 JSON 请求正文。

成功的获取令牌 API 调用会返回一个 JSON 结构，其中包含访问令牌、令牌的过期时间（秒）、类型以及范围（如果可用）。

获取令牌 API 返回的令牌的有效期是有限的，超过该时间段后，它们将无法再使用。该时间段由 xpack.security.authc.token.timeout 设置定义。有关更多信息，请参阅令牌服务设置。

如果您想立即使令牌失效，可以使用使令牌失效 API。

请求正文编辑

以下参数可以在 POST 请求的正文中指定，并与创建令牌有关

grant_type

（必填，字符串）授权类型。支持的授权类型有：password、_kerberos、client_credentials 和 refresh_token。

client_credentials
此授权类型实现了 OAuth2 的客户端凭据授权。它适用于机器间通信，不适合或设计用于自助用户创建令牌。它仅生成无法刷新的访问令牌。前提是使用 client_credentials 的实体可以持续访问一组（客户端，而不是最终用户）凭据，并且可以随意进行身份验证。
_kerberos
此授权类型在内部受支持，并实现了基于 SPNEGO 的 Kerberos 支持。_kerberos 授权类型可能会因版本而异。
password
此授权类型实现了 OAuth2 的资源所有者密码凭据授权。在此授权中，受信任的客户端使用最终用户的凭据交换访问令牌和（可能）刷新令牌。请求需要由经过身份验证的用户发出，但代表另一个经过身份验证的用户（其凭据作为请求参数传递）进行。此授权类型不适合或设计用于自助用户创建令牌。
refresh_token
此授权类型实现了 OAuth2 的刷新令牌授权。在此授权中，用户使用先前颁发的刷新令牌交换新的访问令牌和新的刷新令牌。
password
（可选*，字符串）用户的密码。如果指定 password 授权类型，则此参数是必需的。此参数对任何其他受支持的授权类型无效。
kerberos_ticket
（可选*，字符串）base64 编码的 kerberos 令牌。如果指定 _kerberos 授权类型，则此参数是必需的。此参数对任何其他受支持的授权类型无效。
refresh_token
（可选*，字符串）创建令牌时返回的字符串，用于延长其寿命。如果指定 refresh_token 授权类型，则此参数是必需的。此参数对任何其他受支持的授权类型无效。
scope
（可选，字符串）令牌的范围。目前，无论请求中发送的值是什么，令牌都只针对 FULL 范围颁发。
username
（可选*，字符串）标识用户的用户名。如果指定 password 授权类型，则此参数是必需的。此参数对任何其他受支持的授权类型无效。

示例编辑

以下示例使用 client_credentials 授权类型获取令牌，该类型只是以经过身份验证的用户身份创建令牌

POST /_security/oauth2/token
{
  "grant_type" : "client_credentials"
}

以下示例输出包含访问令牌、令牌的过期时间（以秒为单位）以及类型

{
  "access_token" : "dGhpcyBpcyBub3QgYSByZWFsIHRva2VuIGJ1dCBpdCBpcyBvbmx5IHRlc3QgZGF0YS4gZG8gbm90IHRyeSB0byByZWFkIHRva2VuIQ==",
  "type" : "Bearer",
  "expires_in" : 1200,
  "authentication" : {
    "username" : "test_admin",
    "roles" : [
      "superuser"
    ],
    "full_name" : null,
    "email" : null,
    "metadata" : { },
    "enabled" : true,
    "authentication_realm" : {
      "name" : "file",
      "type" : "file"
    },
    "lookup_realm" : {
      "name" : "file",
      "type" : "file"
    },
    "authentication_type" : "realm"
  }
}

此 API 返回的令牌可以通过发送带有 Authorization 标头的请求来使用，该标头的值以“Bearer”开头，后跟 access_token 的值。

curl -H "Authorization: Bearer dGhpcyBpcyBub3QgYSByZWFsIHRva2VuIGJ1dCBpdCBpcyBvbmx5IHRlc3QgZGF0YS4gZG8gbm90IHRyeSB0byByZWFkIHRva2VuIQ==" https://127.0.0.1:9200/_cluster/health

以下示例使用 password 授权类型获取 test_admin 用户的令牌。此请求需要由具有足够权限的经过身份验证的用户发出，该用户可能与 username 参数中传递的用户名相同，也可能不同

POST /_security/oauth2/token
{
  "grant_type" : "password",
  "username" : "test_admin",
  "password" : "x-pack-test-password"
}

以下示例输出包含访问令牌、令牌的过期时间（以秒为单位）、类型和刷新令牌

{
  "access_token" : "dGhpcyBpcyBub3QgYSByZWFsIHRva2VuIGJ1dCBpdCBpcyBvbmx5IHRlc3QgZGF0YS4gZG8gbm90IHRyeSB0byByZWFkIHRva2VuIQ==",
  "type" : "Bearer",
  "expires_in" : 1200,
  "refresh_token": "vLBPvmAB6KvwvJZr27cS",
  "authentication" : {
    "username" : "test_admin",
    "roles" : [
      "superuser"
    ],
    "full_name" : null,
    "email" : null,
    "metadata" : { },
    "enabled" : true,
    "authentication_realm" : {
      "name" : "file",
      "type" : "file"
    },
    "lookup_realm" : {
      "name" : "file",
      "type" : "file"
    },
    "authentication_type" : "realm"
  }
}

要延长使用 password 授权类型获取的现有令牌的寿命，您可以在令牌创建后的 24 小时内使用刷新令牌再次调用 API。例如

POST /_security/oauth2/token
{
  "grant_type": "refresh_token",
  "refresh_token": "vLBPvmAB6KvwvJZr27cS"
}

API 将返回新的令牌和刷新令牌。每个刷新令牌只能使用一次。

{
  "access_token" : "dGhpcyBpcyBub3QgYSByZWFsIHRva2VuIGJ1dCBpdCBpcyBvbmx5IHRlc3QgZGF0YS4gZG8gbm90IHRyeSB0byByZWFkIHRva2VuIQ==",
  "type" : "Bearer",
  "expires_in" : 1200,
  "refresh_token": "vLBPvmAB6KvwvJZr27cS",
  "authentication" : {
    "username" : "test_admin",
    "roles" : [
      "superuser"
    ],
    "full_name" : null,
    "email" : null,
    "metadata" : { },
    "enabled" : true,
    "authentication_realm" : {
      "name" : "file",
      "type" : "file"
    },
    "lookup_realm" : {
      "name" : "file",
      "type" : "file"
    },
    "authentication_type" : "token"
  }
}

以下示例使用 kerberos 授权类型获取访问令牌和刷新令牌，该类型只是为了交换 base64 编码的 kerberos 令牌而创建令牌

POST /_security/oauth2/token
{
  "grant_type" : "_kerberos",
  "kerberos_ticket" : "YIIB6wYJKoZIhvcSAQICAQBuggHaMIIB1qADAgEFoQMCAQ6iBtaDcp4cdMODwOsIvmvdX//sye8NDJZ8Gstabor3MOGryBWyaJ1VxI4WBVZaSn1WnzE06Xy2"
}

如果 kerberos 身份验证成功，API 将返回新的令牌和刷新令牌。每个刷新令牌只能使用一次。当在 Spnego GSS 上下文中请求相互身份验证时，服务器将在 kerberos_authentication_response_token 中返回一个 base64 编码的令牌，供客户端使用并完成身份验证。

{
  "access_token" : "dGhpcyBpcyBub3QgYSByZWFsIHRva2VuIGJ1dCBpdCBpcyBvbmx5IHRlc3QgZGF0YS4gZG8gbm90IHRyeSB0byByZWFkIHRva2VuIQ==",
  "type" : "Bearer",
  "expires_in" : 1200,
  "refresh_token": "vLBPvmAB6KvwvJZr27cS"
  "kerberos_authentication_response_token": "YIIB6wYJKoZIhvcSAQICAQBuggHaMIIB1qADAg",
  "authentication" : {
    "username" : "test_admin",
    "roles" : [
      "superuser"
    ],
    "full_name" : null,
    "email" : null,
    "metadata" : { },
    "enabled" : true,
    "authentication_realm" : {
      "name" : "file",
      "type" : "file"
    },
    "lookup_realm" : {
      "name" : "file",
      "type" : "file"
    },
    "authentication_type" : "realm"
  }
}
« 获取安全索引设置 获取用户权限 API »