アクセストークンを使用する Management API エンドポイントへの移行

Management API の資格情報として ID トークンを使用することの非推奨化と、アクセストークンを使用するように設定を移行する方法について説明します。

ID トークンを使用してManagement APIのエンドポイントを呼び出すことは、非推奨となります。アクセストークンを使用する必要があります。この移行の猶予期間は2018年3月31日に開始されました。

アクセストークンへの移行が完了したら、Auth0 Dashboard で Allow ID Tokens for Management API v2 Authentication トグルをオフにしてください。

次のいずれかのエンドポイントの呼び出しに ID トークンを使用している場合は、この移行の対象となります。これらのエンドポイントでは現在、通常のアクセストークンを受け付けます。エンドポイントの動作にそれ以外の変更はありません。リクエストとレスポンスのスキーマはこれまでと同じで、認可に使用するトークンを更新するだけで済みます。

​

影響を受けるエンドポイント

エンドポイント	ユースケース
GET /api/v2/users/	ユーザー情報を取得
GET /api/v2/users//enrollments	ユーザーの Guardian MFA 登録情報をすべて取得
PATCH /api/v2/users/	ユーザー情報を更新
DELETE /api/v2/users//multifactor/	ユーザーの MFA プロバイダー設定を削除
POST /api/v2/device-credentials	デバイスの公開鍵を作成
DELETE /api/v2/device-credentials/	デバイス資格情報を削除
POST/api/v2/users//identities	さまざまなアイデンティティプロバイダーのユーザーアカウントをリンク
DELETE /api/v2/users//identities//	ユーザーアカウントのリンク解除

​

Actions

​

スコープの変更

Management API で実行できる操作は、アクセストークンに含まれるスコープによって異なります。この移行により、現在ログイン中のユーザーのデータのみを更新できる制限付きのアクセストークン、または任意のユーザーのデータを更新できるアクセストークンのいずれかを取得できます。次の表では、ケースごと、エンドポイントごとに、トークンに必要なスコープを確認できます。

たとえば、read:users スコープを含むアクセストークンを取得した場合、GET /api/v2/users/{id} エンドポイントを使って任意のユーザーのデータを取得できます。一方、トークンに read:current_user スコープが含まれている場合は、現在ログイン中のユーザー (そのトークンの発行対象ユーザー) の情報のみを取得できます。

エンドポイント	現在のユーザー用スコープ	任意のユーザー用スコープ
GET /api/v2/users/	read:current_user	read:users
GET /api/v2/users//enrollments	read:current_user	read:users
POST/api/v2/users//identities	update:current_user_identities	update:users
DELETE /api/v2/users//identities//	update:current_user_identities	update:users
PATCH /api/v2/users/	update:current_user_metadata	update:users
PATCH /api/v2/users/	create:current_user_metadata	update:users
DELETE /api/v2/users//multifactor/	delete:current_user_metadata	update:users
POST /api/v2/device-credentials	create:current_user_device_credentials	create:device_credentials
DELETE /api/v2/device-credentials/	delete:current_user_device_credentials	delete:device_credentials

​

アクセストークンを取得する

Auth0では、前述のエンドポイント向けにトークンを取得する方法が変更されました。ユーザーを認証してトークンを取得する方法は、使用する技術や、認証に用いるOAuth 2.0のフローによって、いくつかのバリエーションがあります。

• ブラウザーで実行されるSPA: 認可エンドポイントを使用します。
• サーバー上で実行されるWebアプリ、モバイルアプリ、サーバープロセス、または高い信頼性を持つアプリ: トークンエンドポイントを使用します。
• クロス認証: リクエストが異なるドメインから送信される場合は、embedded Lock または auth0.js を使用してユーザーを認証します。

​

認可エンドポイント

このセクションでは、認可エンドポイントでトークンを取得する方法の違いを、例を使って説明します。移行するエンドポイントがどれであっても変更内容は同じで、異なるのはリクエストで指定するスコープだけであることに注意してください。

以下の例では、GET User by ID エンドポイントを使用して、ログイン中のユーザーの完全なプロファイル情報を取得します。そのために、まず Implicit グラントを使用してユーザーを認証し、トークンを取得します。以下は、ID トークンを取得してそれを使ってエンドポイントを呼び出す、従来の方法の実装例です。

以下の例では、アクセストークンを取得する新しい方法を確認できます。

Management API にアクセスできるアクセストークンを取得するには:

• audience を https://{yourDomain}/api/v2/ に設定します
• scope として ${scope} を要求します
• Auth0 が ID トークンとアクセストークンの両方を返すように、response_type を id_token token に設定します

受け取ったアクセストークンをデコードして内容を確認すると、次のようになります:

aud には tenant の API URI、scope には ${scope}、sub にはログイン中のユーザー ID が設定されていることに注目してください。

アクセストークン を取得したら、それを使ってエンドポイント を呼び出せます。この部分は変わらず、request で変わるのは Bearer token として使用する値だけです。response も同じです。

​

トークンエンドポイント

このセクションでは、トークンエンドポイントを使ってトークンを取得する際の違いを、例を用いて説明します。ただし、どのエンドポイントを移行する場合でも変更内容は同じで、異なるのはリクエストで指定するスコープだけであることに注意してください。

以下の例では、ログイン中のユーザーの完全なプロファイル情報を取得するために、GET User by ID エンドポイントを使用します。まず、Password Exchange グラントを使ってユーザーを認証し、その後トークンを取得します。以下は、ID トークンを取得し (その後、それを使ってエンドポイントを呼び出す) 従来のアプローチの実装例です。

以下の例では、アクセストークンも取得する新しい方法を確認できます。

Management API にアクセスできるアクセストークンを取得するには、次のようにします。

• aud を https://{yourDomain}/api/v2/ に設定します
• スコープ read:current_user を要求します

アクセストークンを取得したら、それを使ってエンドポイントを呼び出せます。ここは変わらず、リクエストで変わるのは Bearer トークンとして使う値だけです。レスポンスも同じです。

​

埋め込み Lock または auth0.js

アプリケーションに Lock または auth0.js v9 のいずれかを埋め込んでいる場合は、クロスオリジン認証を使用しています。これは、異なるドメインからリクエストが送信される際にユーザーを認証するために使用されます。

auth0.js を使用して Management API にアクセスし、ユーザーを管理している場合は、スクリプトを更新する必要があります。

以下の例では、従来の方法を確認できます。

この例では、新しい方法を確認できます。

• レスポンスで ID トークン とアクセストークンの両方を要求します

  responseType: 'token id_token'

• トークンのaudienceとして Management API を設定します

  audience: 'https://YOUR_DOMAIN/api/v2/'

• 必要な権限を要求します

  scope: 'read:current_user'

• アクセストークンを使用して Management API で認証します

​

アカウントリンクの変更点

この機能に関する変更点は次のとおりです。

• Authorization header で ID トークンは使用できなくなりました

• Authorization header でアクセストークンを使用し、付与された権限が update:users の場合は、リクエスト本文でセカンダリアカウントの user_id または ID トークンのいずれかを送信できます

• Authorization header でアクセストークンを使用し、付与された権限が update:current_user_metadata の場合は、リクエスト本文でセカンダリアカウントの ID トークンのみを送信できます。この場合、次の条件を満たす必要があります。

  • ID トークンは RS256 で署名されている必要があります (この値は Auth0 Dashboard > アプリケーション > アプリケーション設定 > 詳細設定 > OAuth で設定できます)
  • ID トークンの aud クレームはアプリケーションを識別するものであり、アクセストークンの azp クレームと同じ値である必要があります

​

制限

Management API へのアクセスに使用するアクセストークンでは、aud クレームに設定できる値は 1 つのみです。トークンに複数の値が含まれている場合、Management API へのリクエストはエラーになります。

​

詳しくはこちら

• アカウントリンク 用アクセストークンへの移行