トークンとOrganizations（組織）を使用する

Auth0から返されるIDトークンとアクセストークンのほとんどはJSON Web Tokens（JWT）で、さまざまなクレームを含んでいます。クレームとは、対象について主張された（つまり、立証はされていない）こまごまとした情報のことです。たとえば、IDトークン（必ずJWT）には、認証しようとしているユーザーの名前が「John Doe」であると主張するnameクレームが含まれています。

JWTクレームには以下の2種類があります。

• 登録済み：サードパーティまたは外部のアプリケーションとの相互運用性を確保するためにJWT仕様で定義されたクレーム。OpenID Connect（OIDC）標準クレームは予約済みクレームです。

• カスタム：独自に定義したクレーム。未登録で衝突耐性のあるパブリッククレームか、または衝突の可能性がある未登録で非公開のプライベートクレームである可能性があります。予約済みクレームや他のカスタムクレームとの衝突を避けるため、名前空間などを使用してこれらのクレームに慎重に名前を付けてください。同じ名前で異なる情報のある2つのクレームを扱うことは困難な場合があります。

クレームの詳細については、「JSON Web Tokenクレーム」をお読みください。

組織を通じてユーザーを認証するには、/authorizeエンドポイントへの呼び出しにorganizationパラメーターが追加されます。以下は、ユーザーが組織を通してログインした際に返されるトークンの例です。

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

{
  "https://marketplace/roles": [
    "marketplace-administrator"
  ],
  "https://namespace.exampleco.com": "my custom claim",
  "nickname": "firstName.lastName",
  "name": "firstName.lastName@email.com",
  "picture": "https://s.gravatar.com/avatar/638",
  "updated_at": "2021-03-23T11:34:14.566z",
  "email": "username@exampleco.com",
  "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"  
  ]
}

マシンツーマシンのユースケースでは、/oauth/tokenエンドポイントへのクライアント資格情報要求にorganizationパラメーターが追加され、アプリケーションはユーザーではなく自分自身のアクセストークンを取得できます。

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

{
  "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"
}

/authorizeエンドポイントまたは/oauth/tokenエンドポイントへの呼び出しにorganizationパラメーターが追加されると、Auth0 SDKはorg_idクレームを自動的に検証し、生成されたトークンの一部として返します。ただし、セキュリティを保護するために、追加の検証はトークンを受け取ったときに行います。

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の構成