New

The executive guide to generative AI

Read more
About usPartnersSupport|Login
« 获取安全索引设置 获取用户权限 API »
Elastic 文档 ›Elasticsearch 指南 [8.17] ›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 授权类型获取令牌，该类型只是作为经过身份验证的用户创建令牌

resp = client.security.get_token(
    grant_type="client_credentials",
)
print(resp)
const response = await client.security.getToken({
  grant_type: "client_credentials",
});
console.log(response);
POST /_security/oauth2/token
{
  "grant_type" : "client_credentials"
}
Copy as curlTry in Elastic 

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

{
  "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 参数中传递的用户名相同，也可能不同

resp = client.security.get_token(
    grant_type="password",
    username="test_admin",
    password="x-pack-test-password",
)
print(resp)
const response = await client.security.getToken({
  grant_type: "password",
  username: "test_admin",
  password: "x-pack-test-password",
});
console.log(response);
POST /_security/oauth2/token
{
  "grant_type" : "password",
  "username" : "test_admin",
  "password" : "x-pack-test-password"
}
Copy as curlTry in Elastic 

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

{
  "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。例如

resp = client.security.get_token(
    grant_type="refresh_token",
    refresh_token="vLBPvmAB6KvwvJZr27cS",
)
print(resp)
const response = await client.security.getToken({
  grant_type: "refresh_token",
  refresh_token: "vLBPvmAB6KvwvJZr27cS",
});
console.log(response);
POST /_security/oauth2/token
{
  "grant_type": "refresh_token",
  "refresh_token": "vLBPvmAB6KvwvJZr27cS"
}
Copy as curlTry in Elastic 

该 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 »

On this page

Was this helpful?
Feedback