Auth0 Management API v2の一部がページ分割された結果を返すようになるとのこと

2020.07.27

Auth0ダッシュボードのnotificationsに、INFORMATIONAL: Change to Management API v2 Unpaginated Requestsという題名の通知がきていました。

内容は、

2021年1月26日以降、API v2へのリクエストは最大50アイテムを返します。50を超えるアイテムを取得するには、これらの7つのエンドポイントへのリクエストをper_pageおよびpageパラメータを使用して更新する必要がある

というものです。

影響を受けるテナントは、

  • Auth0パブリッククラウド(現在)
  • 2020年7月21日より前に作成
  • per_page複数の結果を返す可能性のあるクエリのパラメーターを渡さずに、影響を受けるエンドポイントを積極的に呼び出している

7つのエンドポイントは、

  • GET /api/v2/clients
    • 提供されたフィルターに一致するクライアント(アプリケーションおよびSSO統合)を取得
  • GET /api/v2/client-grants
    • クライアントの付与された権限を取得
  • GET /api/v2/grants
    • アカウントに関連付けられている付与された権限を取得
  • GET /api/v2/connections
    • すべてのコネクション(Database, Social, Enterprise, Passwordless)を取得
  • GET /api/v2/device-credentials(注:typeが提供されていない場合、ページ付けは強制されません)
    • 特定のuser_idのデバイス資格情報の詳細を取得
  • GET /api/v2/resource-servers
    • 承認済みアプリケーションから使用できるAPI(リソースサーバーとも呼ばれます)を取得
  • GET /api/v2/rules
    • ルールを取得

現在、Auth0は移行のために

  • 異なるクライアントおよびエンドポイントごとに、1時間に1回以上、複数のアイテムを返すページネーションオプションのないすべてのリクエストのテナントログの出力

  • Management APIのページ付けされていないリクエストを有効にするかしないか(デフォルト有効)の設定

を用意しています。

この変更に対応するには、

pageおよびper_pageパラメータを指定して、影響を受けるエンドポイントへのすべての呼び出しをするようにアプリケーションのソースコードを置き換える必要があります。

現在のpageおよびper_pageパラメータの説明

  • page: 返す結果のページインデックス(デフォルト0)
  • per_page: ページあたりの結果の数。パラメータが送信されない場合、ページングは​​無効

では実際に、50以上の結果を返す時の挙動を確認してみます。

今回はRuleを50個以上ある状態にしました。

ページ付けされていないリクエストを有効の状態でアクセスすると

curl -H "Authorization: Bearer <YOUR API TOKEN>" https://classmethod-partner-jp.auth0.com/api/v2/rules | jq ".|length"
58

58件返ってきました。

この時のDeprecation Noticeとなっているログは、

size_exceededtrueとなっており、result_lengthは58です。

次は、pageとper_pageを指定してリクエストしてみます。

per_pageは50

$ curl -H "Authorization: Bearer <YOUR API TOKEN>" ”https://classmethod-partner-jp.auth0.com/api/v2/rules?page=0&per_page=50” | jq ".|length"
50

$ curl -H "Authorization: Bearer <YOUR API TOKEN>" ”https://classmethod-partner-jp.auth0.com/api/v2/rules?page=1&per_page=50” | jq ".|length"
8

$ curl -H "Authorization: Bearer <YOUR API TOKEN>" ”https://classmethod-partner-jp.auth0.com/api/v2/rules?page=2&per_page=50” | jq ".|length"
0

1ページ目から50件で分割して、きっちり最大件数分が返ってきます。

ページ付けされていないリクエストを無効の状態でアクセスしてみます。

curl -H "Authorization: Bearer <YOUR API TOKEN>" https://classmethod-partner-jp.auth0.com/api/v2/rules | jq ".|length"
50

有効の時は58件表示されますが、無効にすると最大値である50件に制限されます。 これが2021年1月26日以降の状況をシミュレートした形になります。

Auth0のダッシュボードに届く通知は、テナントにとって重要なものが含まれているので必ず確認しないといけませんね。

アプリケーションによってはエラーを返してユーザー影響が出てしまう可能性があるような変更の場合は事前に挙動を確認しましょう。 今回の変更に関してはAuth0がシミュレーションを行えるようにしてくれているので助かりました。

また、自身のアプリケーションだけでなく、Extensionsを使っている場合も注意しましょう。 Extensionsが今回のような重要な変更の影響を受けていることもあります。 インストールしているExtensionsを確認し、アップデートが出ていれば更新します。

参考

Migrate to Management API v2 Endpoint Paginated Queries