Zenn
🎃

Auth0向けにSwagger UIのOAuth2 Client Credentialフローで'audience'パラメーターも送信する

2024/10/14に公開
Swagger
OpenAPI
OAuth 2
Auth0
tech

背景

業務でAuth0とOpenAPIやSwagger UIを利用しています。
OpenAPIの定義でOAuth2 Client CredentialでTokenUrlを記述できますが、Auth0ではaudienceパラメーターの指定が必要です。(トークン取得API仕様参照)
現在最新のSwagger UI v5.17.14では任意に指定することが出来ず403エラーになってしまうのでカスタマイズを試みました。
audience指定不能

「Auth0 audience Swagger UI」で検索するとAuth0 Communityで似た報告を閲覧することができますが、ASP.NET CoreやSpring Bootを組み合わせたり、クエリストリングで指定する方法が見られます。いっそのことSwagger UI側を直接改修しました。
個人的な興味本位の調査の一環であり業務で採用するかどうかはわかりません。

動作環境

  • macOS Sequoia
    • Apple Silicon
    • Swagger UI v5.17.14
    • Docker Desktop 4.34.3 (170107)
      image: node:22.9.0-alpine3.20を利用していますが、この記事では触れません。
      Swagger UIの開発環境をホストOSに構築したくなかったため利用しています。

OSSを改修

Swagger UI v5.17.14から改修します。Reactの実務経験はないので詰めが甘いコードだと思いますが、コードを見て頂くのが一番分かり易いと思います。
https://github.com/devnokiyo/swagger-ui/commit/86f3052d8fe87778d2333d73d235b2e1e3eb9e72

デバッグ実行

oauth2 clientCredentialsでOpenAPIを定義します。tokenURLはトークン取得APIです。

yaml
  securitySchemes:
    petstore_auth:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://dev-***************.us.auth0.com/oauth/token

npm run devを実行します。

Swagger UIのページを確認

該当のエンドポイントの🔓マークから認証情報を確認します。audienceパラメーターが増えています。
audienceあり
Client ID / Client Secret / Identifier(audience)を入力してAuthorizeボタンを押します。
認証成功

Auth0 トークン取得APIからトークンが取得できました。

  • レスポンス
    HTTP 200 OK
  • リクエスト audienceが含まれる
    Request
  • トークンのレスポンス値
    Response

もし、CORSのエラーが出る場合はAuth0 Application設定でオリジンを設定します。
Auth0 Dashboard

動作確認できればnpm run buildでビルドして利用すれば良いと思います。

[補足] 独自プロパティで制御する

上記の方法ではaudienceパラメーターが一律表示されるようになります。個別に指定する方法としてx-needAudienceという独自プロパティで制御できそうだと思ったので興味本位でやってみました。
https://github.com/devnokiyo/swagger-ui/commit/2dd7073e78807c313a01fb5104145f9305c4ef9e

OpenAPIを定義でx-needAudience: trueのときのみ、audienceパラメーターのテキストボックスが出現するようになります。

yaml
  securitySchemes:
    petstore_auth:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://dev-***************.us.auth0.com/oauth/token
          x-needAudience: true

余談

時間と理解の関係でテストコードは書いていませんが、書けたらご本家に提案してみるかもしれません。今回はコントリビューションを目的としていないので勝手にForkして改修していますが、ご本家では一度議論してからPRして欲しいと記載がありました。

Discussion