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

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

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

アクセストークンへの移行が完了したら、Dashboardで ［Allow ID Tokens for Management API v2 Authentication（Management API v2認証にIDトークンを許可する）］ を無効にします。

以下のいずれかのエンドポイントを呼び出すために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	さまざまなIDプロバイダーからユーザーアカウントをリンクする
DELETE /api/v2/users//identities//	ユーザーアカウントのリンクを解除する

​

アクション

​

スコープの変更

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アプリ ：トークンエンドポイントを使用する。
• クロス認証 ：異なるドメインから要求が来る場合、ユーザー認証には埋め込みのロックまたはauth0.jsを使用する。

​

認可エンドポイント

このセクションでは、認可エンドポイントでトークンを取得する方法の違いについて例を用いて説明します。どのエンドポイントを移行したいかに関わらず変更点は同じで、唯一異なる点は要求で指定するスコープです。

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

https://{yourDomain}/authorize?
      scope=openid
      &response_type=id_token
      &client_id={yourClientId}
      &redirect_uri=https://{yourApp}/callback
      &nonce={nonce}
      &state={opaqueValue}

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

https://{yourDomain}/authorize?
      audience=https://{yourDomain}/api/v2/
      &scope=read:current_user
      &response_type=token%20id_token
      &client_id={yourClientId}
      &redirect_uri=https://{yourApp}/callback
      &nonce={nonce}
      &state={opaqueValue}

Management APIにアクセスできるアクセストークンを取得するには以下を行います。

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

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

{
      "iss": "https://{yourDomain}/",
      "sub": "auth0|5a620d29a840170a9ef43672",
      "aud": "https://{yourDomain}/api/v2/",
      "iat": 1521031317,
      "exp": 1521038517,
      "azp": "{yourClientId}",
      "scope": "${scope}"
    }

audはテナントのAPI URI、スコープは${scope}、subはログインユーザーのユーザーIDに設定されています。

アクセストークンを取得したら、それを使ってエンドポイントを呼び出します。この部分は同じで、要求のうち、Bearerトークンとして使用する値を除き変更はありません。応答も同じです。

​

トークンエンドポイント

このセクションでは、トークンエンドポイントでトークンを取得する方法の違いについて例を用いて説明します。どのエンドポイントを移行したいかに関わらず変更点は同じで、唯一異なる点は要求で指定するスコープです。

以下の例では、GET User by IDエンドポイントを使用して、ログインユーザーの完全なプロファイル情報を取得します。まず、パスワード交換の付与タイプを使ってユーザーを認証してから、トークンを取得します。以下は、IDトークンを取得する（そして、それを使用してエンドポイントを呼び出す）以前の方法の実装例です。

POST https://{yourDomain}/oauth/token
    Content-Type: application/x-www-form-urlencoded
    {
      "grant_type": "password",
      "username": "{yourUsername}",
      "password": "{yourPassword}",
      "scope": "openid",
      "client_id": "{yourClientId}",
      "client_secret": "{yourClientSecret}",
    }

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

POST https://{yourDomain}/oauth/token
    Content-Type: application/x-www-form-urlencoded
    {
      "grant_type": "password",
      "username": "{yourUsername}",
      "password": "{yourPassword}",
      "audience": "https://{yourDomain}/api/v2/",
      "scope": "read:current_user",
      "client_id": "{yourClientId}",
      "client_secret": "{yourClientSecret}",
    }

Management APIにアクセスできるアクセストークンを取得するには以下を行います。

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

アクセストークンを取得したら、それを使ってエンドポイントを呼び出します。この部分は同じで、要求のうち、Bearerトークンとして使用する値を除き変更はありません。応答も同じです。

​

埋め込みのロックまたはauth0.js

アプリケーションにロックまたはauth0.js v9を埋め込んだ場合、クロスオリジン認証を使用しています。これは、異なるドメインから要求が来る場合、ユーザーの認証に使用します。

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

以下の例は、以前の方法です。

// get an ID Token
    var webAuth = new auth0.WebAuth({
      clientID: '{yourClientId}',
      domain: '{yourDomain}',
      redirectUri: 'https://{yourApp}/callback',
      scope: 'openid',
      responseType: 'id_token'
    });
    // create a new instance
    var auth0Manage = new auth0.Management({
      domain: '{yourDomain}',
      token: '{yourIdToken}'
    });

この例は、新しい方法です。

// get an Access Token
    var webAuth = new auth0.WebAuth({
      clientID: '{yourClientId}',
      domain: '{yourDomain}',
      redirectUri: 'https://{yourApp}/callback',
      audience: 'https://{yourDomain}/api/v2/',
      scope: 'read:current_user',
      responseType: 'token id_token'
    });
    // create a new instance
    var auth0Manage = new auth0.Management({
      domain: '{yourDomain}',
      token: '{yourMgmtApiAccessToken}'
    });

• 応答でIDトークンとアクセストークンの両方を要求する

  responseType:'token id_token'

• Management APIを意図したトークンのオーディエンスとして設定する

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

• 必要なアクセス許可を要求する

  scope:'read:current_user'

• アクセストークンを使ってManagement APIで認証する

​

アカウントリンクの変更

この機能性の変更点は以下の通りです。

• AuthorizationヘッダーにIDトークンを使用することはできなくなりました。

• Authorizationヘッダーでアクセストークンを使用し、付与されたアクセス許可がupdate:usersの場合、要求のボディにはセカンダリアカウントのuser_idまたはIDトークンのいずれかを送信できます。

• Authorizationヘッダーでアクセストークンを使用し、付与されたアクセス許可がupdate:current_user_metadataの場合、要求のボディにはセカンダリアカウントのIDトークンのみ送信できます。次のような条件があります。

  • IDトークンはRS256を使用して署名される必要があります（この値は、［Dashboard］>［Applications（アプリケーション）］>［Application Settings（アプリケーションの設定）］>［Advanced Settings（高度な設定）］>［OAuth］ から設定できます）
  • IDトークンのaudクレームは、アプリケーションを特定し、アクセストークンのazpクレームと同じ値でなければいけません。

​

制限

Management APIにアクセスするために使用されるアクセストークンは、audクレームの値が1つのみである必要があります。トークンに複数の値がある場合、Management APIへの要求はエラーになります。

​

もっと詳しく

• アカウントリンクに向けてアクセストークンに移行する