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

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

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

以下のいずれかのエンドポイントを呼び出すためにIDトークンを使用する場合、この移行による影響を受けます。これらのエンドポイントは、通常のアクセストークンを受け入れられるようになりました。エンドポイントの動作にその他の変更はありません。要求と応答のスキーマは同じままで、認可に使用するトークンの更新だけが必要です。

Management APIで実行できるアクションは、アクセストークンに含まれるスコープに依存します。この移行により、ログインしているユーザーのデータのみを更新できる制限付きアクセストークン、または任意のユーザーのデータを更新できるアクセストークンを取得できます。以下の表で、トークンに必要なスコープをケースとエンドポイントごとに確認してください。

例えば、read:usersというスコープを含むアクセストークンを取得した場合、GET /api/v2/users/{id}エンドポイントを使用して任意のユーザーデータを取得することができます。しかし、トークンにread:current_userスコープが含まれる場合、現在ログインしているユーザー（トークンが発行されたユーザー）の情報のみ取得することができます。

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 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への要求はエラーになります。

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