トークンAPI

基本認証を必要とせずにアクセスするためのベアラートークンを作成します。

リクエスト

POST /_security/oauth2/token

前提条件

  • このAPIを使用するには、manage_tokenクラスターの権限が必要です。

説明

トークンはElasticsearchトークンサービスによって作成され、HTTPインターフェースでTLSを構成すると自動的に有効になります。詳細はElasticsearchのHTTPクライアント通信を暗号化するを参照してください。あるいは、xpack.security.authc.token.enabled設定を明示的に有効にすることもできます。運用モードで実行している場合、ブートストラップチェックにより、HTTPインターフェースでTLSを有効にしない限り、トークンサービスを有効にすることはできません。

トークン取得APIは、JSONリクエストボディの使用を除いて、典型的なOAuth 2.0トークンAPIと同じパラメータを受け取ります。

成功したトークン取得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グラントタイプを使用してトークンを取得します。

Python

  1. resp = client.security.get_token(
  2.    grant_type="client_credentials",
  3. )
  4. print(resp)

Js

  1. const response = await client.security.getToken({
  2.   grant_type: "client_credentials",
  3. });
  4. console.log(response);

コンソール

  1. POST /_security/oauth2/token
  2. {
  3.   "grant_type" : "client_credentials"
  4. }

以下の例の出力には、アクセストークン、トークンの有効期限（秒）、およびタイプが含まれています：

コンソール-結果

  1. {
  2.   "access_token" : "dGhpcyBpcyBub3QgYSByZWFsIHRva2VuIGJ1dCBpdCBpcyBvbmx5IHRlc3QgZGF0YS4gZG8gbm90IHRyeSB0byByZWFkIHRva2VuIQ==",
  3.   "type" : "Bearer",
  4.   "expires_in" : 1200,
  5.   "authentication" : {
  6.    "username" : "test_admin",
  7.    "roles" : [
  8.    "superuser"
  9.    ],
  10.    "full_name" : null,
  11.    "email" : null,
  12.    "metadata" : { },
  13.    "enabled" : true,
  14.    "authentication_realm" : {
  15.    "name" : "file",
  16.    "type" : "file"
  17.    },
  18.    "lookup_realm" : {
  19.    "name" : "file",
  20.    "type" : "file"
  21.    },
  22.    "authentication_type" : "realm"
  23.   }
  24. }

このAPIによって返されたトークンは、Authorizationヘッダーを持つリクエストを送信することで使用でき、その値は「Bearer 」というプレフィックスに続いてaccess_tokenの値が続きます。

シェル

  1. curl -H "Authorization: Bearer dGhpcyBpcyBub3QgYSByZWFsIHRva2VuIGJ1dCBpdCBpcyBvbmx5IHRlc3QgZGF0YS4gZG8gbm90IHRyeSB0byByZWFkIHRva2VuIQ==" http://localhost:9200/_cluster/health

以下の例は、test_adminユーザーのためにpasswordグラントタイプを使用してトークンを取得します。このリクエストは、usernameパラメータに渡されるユーザー名と同じであるかどうかにかかわらず、十分な権限を持つ認証されたユーザーによって行われる必要があります。

Python

  1. resp = client.security.get_token(
  2.    grant_type="password",
  3.    username="test_admin",
  4.    password="x-pack-test-password",
  5. )
  6. print(resp)

Js

  1. const response = await client.security.getToken({
  2.   grant_type: "password",
  3.   username: "test_admin",
  4.   password: "x-pack-test-password",
  5. });
  6. console.log(response);

コンソール

  1. POST /_security/oauth2/token
  2. {
  3.   "grant_type" : "password",
  4.   "username" : "test_admin",
  5.   "password" : "x-pack-test-password"
  6. }

以下の例の出力には、アクセストークン、トークンの有効期限（秒）、タイプ、およびリフレッシュトークンが含まれています：

コンソール-結果

  1. {
  2.   "access_token" : "dGhpcyBpcyBub3QgYSByZWFsIHRva2VuIGJ1dCBpdCBpcyBvbmx5IHRlc3QgZGF0YS4gZG8gbm90IHRyeSB0byByZWFkIHRva2VuIQ==",
  3.   "type" : "Bearer",
  4.   "expires_in" : 1200,
  5.   "refresh_token": "vLBPvmAB6KvwvJZr27cS",
  6.   "authentication" : {
  7.    "username" : "test_admin",
  8.    "roles" : [
  9.    "superuser"
  10.    ],
  11.    "full_name" : null,
  12.    "email" : null,
  13.    "metadata" : { },
  14.    "enabled" : true,
  15.    "authentication_realm" : {
  16.    "name" : "file",
  17.    "type" : "file"
  18.    },
  19.    "lookup_realm" : {
  20.    "name" : "file",
  21.    "type" : "file"
  22.    },
  23.    "authentication_type" : "realm"
  24.   }
  25. }

passwordグラントタイプを使用して取得した既存のトークンの有効期限を延長するには、トークンの作成から24時間以内にリフレッシュトークンを使用してAPIを再度呼び出すことができます。例えば：

Python

  1. resp = client.security.get_token(
  2.    grant_type="refresh_token",
  3.    refresh_token="vLBPvmAB6KvwvJZr27cS",
  4. )
  5. print(resp)

Js

  1. const response = await client.security.getToken({
  2.   grant_type: "refresh_token",
  3.   refresh_token: "vLBPvmAB6KvwvJZr27cS",
  4. });
  5. console.log(response);

コンソール

  1. POST /_security/oauth2/token
  2. {
  3.   "grant_type": "refresh_token",
  4.   "refresh_token": "vLBPvmAB6KvwvJZr27cS"
  5. }

APIは新しいトークンとリフレッシュトークンを返します。各リフレッシュトークンは一度だけ使用できます。

コンソール-結果

  1. {
  2.   "access_token" : "dGhpcyBpcyBub3QgYSByZWFsIHRva2VuIGJ1dCBpdCBpcyBvbmx5IHRlc3QgZGF0YS4gZG8gbm90IHRyeSB0byByZWFkIHRva2VuIQ==",
  3.   "type" : "Bearer",
  4.   "expires_in" : 1200,
  5.   "refresh_token": "vLBPvmAB6KvwvJZr27cS",
  6.   "authentication" : {
  7.    "username" : "test_admin",
  8.    "roles" : [
  9.    "superuser"
  10.    ],
  11.    "full_name" : null,
  12.    "email" : null,
  13.    "metadata" : { },
  14.    "enabled" : true,
  15.    "authentication_realm" : {
  16.    "name" : "file",
  17.    "type" : "file"
  18.    },
  19.    "lookup_realm" : {
  20.    "name" : "file",
  21.    "type" : "file"
  22.    },
  23.    "authentication_type" : "token"
  24.   }
  25. }

以下の例は、base64エンコードされたKerberosチケットと引き換えにトークンを単純に作成するkerberosグラントタイプを使用してアクセストークンとリフレッシュトークンを取得します。

Js

  1. POST /_security/oauth2/token
  2. {
  3.   "grant_type" : "_kerberos",
  4.   "kerberos_ticket" : "YIIB6wYJKoZIhvcSAQICAQBuggHaMIIB1qADAgEFoQMCAQ6iBtaDcp4cdMODwOsIvmvdX//sye8NDJZ8Gstabor3MOGryBWyaJ1VxI4WBVZaSn1WnzE06Xy2"
  5. }

Kerberos認証が成功した場合、APIは新しいトークンとリフレッシュトークンを返します。各リフレッシュトークンは一度だけ使用できます。相互認証がSpnego GSSコンテキストで要求される場合、サーバーはクライアントが消費し、認証を完了するためにkerberos_authentication_response_tokenでbase64エンコードされたトークンを返します。

Js

  1. {
  2.   "access_token" : "dGhpcyBpcyBub3QgYSByZWFsIHRva2VuIGJ1dCBpdCBpcyBvbmx5IHRlc3QgZGF0YS4gZG8gbm90IHRyeSB0byByZWFkIHRva2VuIQ==",
  3.   "type" : "Bearer",
  4.   "expires_in" : 1200,
  5.   "refresh_token": "vLBPvmAB6KvwvJZr27cS"
  6.   "kerberos_authentication_response_token": "YIIB6wYJKoZIhvcSAQICAQBuggHaMIIB1qADAg",
  7.   "authentication" : {
  8.    "username" : "test_admin",
  9.    "roles" : [
  10.    "superuser"
  11.    ],
  12.    "full_name" : null,
  13.    "email" : null,
  14.    "metadata" : { },
  15.    "enabled" : true,
  16.    "authentication_realm" : {
  17.    "name" : "file",
  18.    "type" : "file"
  19.    },
  20.    "lookup_realm" : {
  21.    "name" : "file",
  22.    "type" : "file"
  23.    },
  24.    "authentication_type" : "realm"
  25.   }
  26. }