トークンと組織を扱う

Auth0の組織機能でトークンがどのように機能するか、また組織に属するユーザーを認証する方法を学びます。

利用可否はAuth0のプランによって異なります

この機能を利用できるかどうかは、Auth0のプランまたはカスタム契約によって異なります。詳しくは、Pricingを参照してください。

Auth0が返すほとんどのID トークンとアクセストークンは、さまざまなクレームを含むJSON Web トークン (JWT) です。クレームとは、主体について表明された情報のことです。たとえば、ID トークン (常にJWTです) には、認証中のユーザーの名前が”John Doe”であることを示すnameというクレームを含めることができます。

JWTクレームには2種類あります。

• Registered: JWT仕様で定義されたクレームで、サードパーティ、つまり外部のアプリケーションとの相互運用性を確保するためのものです。OpenID Connect (OIDC)標準のクレームは予約済みクレームです。
• Custom: 自分で定義するクレームです。これらのクレームには、未登録で衝突耐性のあるパブリッククレームや、衝突が起こりうる未登録のプライベートクレームを含めることができます。予約済みクレームや他のカスタムクレームとの衝突を避けるため、namespacingなどを用いて、これらのクレームには慎重に名前を付けてください。同じ名前で異なる情報を含む2つのクレームを扱うのは難しい場合があります。

クレームの詳細については、JSON Web Token Claimsを参照してください。

​

組織を通じてユーザーを認証する

組織を通じてユーザーを認証するには、/authorize エンドポイントへのリクエストで organization パラメーターを渡します。以下の例は、ユーザーが 組織 を通じてログインしたときに返されるトークンを示しています。

デフォルトでは、ID トークンとアクセストークンには組織IDのみが含まれます。ただし、テナントを設定することで、Authentication API で 組織名を使用できるようになります。この設定を行うと、ID トークンとアクセストークンには org_id と org_name の両方のクレームが含まれます。詳しくは、Authentication API で 組織名を使用するをご覧ください。

サードパーティアプリケーションは ID トークンを受け取りません。アクセストークンには、引き続き以下に示す org_id クレームが含まれます。詳しくは、サードパーティアプリケーションのセキュリティ制御をお読みください。

​

ID トークン

次の例では、https://marketplace/roles と https://namespace.exampleco.com/ はトークンに追加されたカスタムクレームであり、その他の含まれるクレームは標準のものである点に注目してください。

{
  "https://marketplace/roles": [
    "marketplace-administrator"
  ],
  "https://namespace.exampleco.com": "my custom claim",
  "nickname": "firstName.lastName",
  "name": "[e-mail]",
  "picture": "https://s.gravatar.com/avatar/638",
  "updated_at": "2021-03-23T11:34:14.566z",
  "email": "[e-mail]",
  "email_verified": true,
  "sub": "auth0|602c0dcab993d10073daf680",
  "org_id": "org_9ybsU1dN2dKfDkBi"
}

​

アクセストークン

{
  "iss": "https://exampleco.auth0.com/",
  "sub": "auth0|602c0dcab993d10073daf680",
  "aud": [
    "https://example-api/",
    "https://exampleco.auth0.com/userinfo"  
  ],
  "iat": 1616499255,
  "exp": 1616585655,
  "azp": "ENDmmAJsbwI1hOG1KPJddQ8LHjV6kLkV",
  "scope": "openid profile email",
  "org_id": "org_9ybsU1dN2dKfDkBi",
  "permissions": [
    "delete:stuff",
    "read:stuff",
    "write:stuff"  
  ]
}

​

組織ロールの権限

ユーザーが組織を通じて認証され、組織ロールを持っている場合、アクセストークンのpermissionsクレームには、それらの組織ロールに含まれる権限が含まれます。この権限には、そのセッションでアクティブな組織内で付与されているロールのみが反映されます。

認証リクエストに組織コンテキストがない場合、テナントロールは引き続き有効であり、トークンの動作は変わりません。

次の例は、アクティブな組織内でread:reportsおよびwrite:reportsの権限を持つ組織ロールが付与されているユーザーのアクセストークンを示しています。

{
  "iss": "https://exampleco.auth0.com/",
  "sub": "auth0|602c0dcab993d10073daf680",
  "aud": [
    "https://example-api/",
    "https://exampleco.auth0.com/userinfo"
  ],
  "iat": 1616499255,
  "exp": 1616585655,
  "azp": "ENDmmAJsbwI1hOG1KPJddQ8LHjV6kLkV",
  "scope": "openid profile email",
  "org_id": "org_9ybsU1dN2dKfDkBi",
  "permissions": [
    "read:reports",
    "write:reports"
  ]
}

組織ロールの詳細については、組織ロールを参照してください。

​

組織へのマシンツーマシンアクセス

マシンツーマシンのユースケースでは、アプリケーションがユーザーではなく自身のためのアクセストークンを取得できるよう、organization パラメータを /oauth/token エンドポイントへの Client Credentials リクエストに追加します。

デフォルトでは、ID トークンとアクセストークンには組織IDのみが含まれます。ただし、テナントを設定することで、Authentication API で 組織名を使用できるようになります。設定すると、ID トークンとアクセストークンの両方に org_id と org_name のクレームが含まれます。詳しくは、Authentication API で 組織名を使用するを参照してください。

次のコードサンプルは、マシンツーマシンのユースケースで返されるアクセストークンの例です。

{
  "iss": "https://exampleco.auth0.com/",
  "sub": "CS2MNgcX1VZFCJaEzfKw2VPAAS0gzhqP@clients",
  "aud": "https://example-api",
  "iat": 1727782196,
  "exp": 1727868596,
  "scope": "scope1 scope2",
  "org_id": "org_vIK75NKFvaozQsFy",
  "org_name": "acme",
  "gty": "client-credentials",
  "azp": "CS2MNgcX1VZFCJaEzfKw2VPAAS0gzhqP"
}

​

トークンを検証する

organization パラメーターが /authorize エンドポイントまたは /oauth/token エンドポイントの呼び出しに追加されると、Auth0 SDK は、生成されたトークンに含まれて返される org_id クレームを自動的に検証します。ただし、セキュリティ上の理由から、トークンを受け取った際には追加の検証も行うべきです。

Authentication API で 組織名 の使用を許可するようにテナントを設定している場合、ID トークンとアクセストークンには org_id クレームと org_name クレームの両方が含まれます。これらが存在する場合は、受け取った値が信頼できるエンティティに対応していることを確認するため、org_id に加えて org_name クレームも検証してください。

一般に、トークンの検証には組織IDを使用する方法が推奨されます。ただし、ユースケースによっては 組織名 を使用することもできます。組織名 を使用してトークンを検証する場合の影響を理解するには、Authentication API で 組織名 を使用するを参照してください。

Web アプリケーションの場合:

/authorize エンドポイントに organization パラメーターが渡されていないにもかかわらず、ID トークン に org_id クレームが含まれている場合、アプリケーションはそのクレームを検証し、受け取った値が想定どおりまたは既知のものであり、有料顧客など、アプリケーションが信頼するエンティティに対応していることを確認する必要があります。クレームを検証できない場合、アプリケーションはそのトークンを無効と見なす必要があります。

API の場合:

アクセストークンに org_id クレームが含まれている場合、API はそのクレームを検証し、受け取った値が想定どおりまたは既知のものであり、有料顧客など、アプリケーションが信頼するエンティティに対応していることを確認する必要があります。クレームを検証できない場合、API はそのトークンを無効と見なす必要があります。

特に、次の点を確認してください。

• iss (発行者) クレームを確認し、トークンが Auth0 によって発行されたものであることを確かめます。
• org_id クレームを確認し、それがアプリケーションですでに認識されている値であることを確かめます。既知の組織IDの一覧と照合して検証するか、現在のリクエストURLと関連付けて確認します。たとえば、サブドメインから、ID トークンの検証時にどの組織を使用すべきか判断できる場合があります。

通常、発行者だけを検証すれば、そのトークンが Auth0 によって発行されたことを確認するには十分です。ただし、組織 を使用する場合は、Auth0 テナント内のその組織が想定されたものであることを確認するために、追加のチェックを行うべきです。

API サーバーは、org_id に基づいてデータやリソースへのアクセスを適切に分離する必要もあります。これにより、アクセストークンで特定の組織に対応する org_id 値を受け取った場合、その組織に関する情報のみにアクセスまたは変更できるようになります。

​

詳しく見る

• Auth0 Organizations の仕組みを理解する
• 最初の組織を作成する
• Organizations を使ったカスタム開発
• Organizations を設定する