Authentication APIでorganization名を使用する

Authentication APIでorganization名を使用する際の設定、セキュリティ上の考慮事項、ベストプラクティス。

デフォルトでは、Authentication API は特定の組織を識別するために組織IDを使用します。必要に応じて、テナントを設定し、識別子として organization名 も使用できるようにすることができます。ただし、この機能を有効にする前に、ユーザビリティやセキュリティへの影響を考慮する必要があります。想定される影響をよりよく理解するには、考慮事項と推奨事項 セクションを確認してください。

​

仕組み

テナントを設定して Authentication API で organization名をサポートすると、次のようになります。

• /authorize エンドポイントと SAML エンドポイントの organization パラメータで、organization名と ID の両方を指定できるようになります。
• アクセストークンと ID トークン には、自動的に org_name と org_id の両方のクレームが含まれます。

• Organizations には 2 つの名前を設定できます。1 つは一意の論理識別子として機能する必須の Name 値で、もう 1 つは任意のわかりやすい Display Name です。org_name パラメータで受け付けられるのは必須の Name 値のみで、Display Name 値には対応していません。
• この機能はテナントレベルで管理されます。特定の組織ごとに個別に有効化することはできません。

この機能は、Auth0 Dashboard または Management API から有効にできます。

• Auth0 Dashboard: 左側のメニューから 設定 を選択し、Advanced タブを開きます。設定 セクションで、Allow Organization Names in Authentication API トグルを有効にします。
• Management API: PATCH /api/v2/tenants/settings エンドポイントを使用して、allow_organization_name_in_authentication_api を true に設定します。詳しくは、Management API のドキュメントを参照してください。

​

フローの例

以下の例では、organization名を使用する認可コードフローを示します。

1. organization パラメータに organization名を渡して、/authorize エンドポイントを呼び出します。

2. 認可コードを取得したら、アクセストークンと ID トークンを取得するために POST /oauth/token エンドポイントを呼び出します。

3. 返されたデコード済みトークンには、org_id と org_name の両方のクレームが含まれています。

{
    "sub": "google-oauth2|10...17",
    "aud": [
        "https://yourApp"
    ],
    "iat": 1686840988,
    "exp": 1686927388,
    "azp": "Suo...qTd",
    "scope": "openid profile",
    "org_id": "{yourOrganizationId}",
    "org_name": "{yourOrganizationName}"
}

​

考慮事項と推奨事項

Authentication APIでorganization名を使用する前に、organization名と組織IDの主な違いを理解しておくことが重要です。

組織IDは変わりませんが、organizationの名前は初回作成後であればいつでも変更できます。さらに、単一のテナント内では、同じ時点で正確に1つのorganizationにのみ割り当てられている限り、organization名を再利用できます。つまり、あるorganizationの名前を変更し、その元の名前をテナント内の別のorganizationで再利用できます。organization名が一意なのは単一のテナント内に限られ、複数のテナントにまたがる場合は、2つ以上のorganizationで同じ名前を使用できます。

一般に、トークンを検証する際は組織IDを使用することをお勧めします。ただし、利用ケースによってはorganization名のほうが適している場合もあるため、この機能を実装する際は以下の点を考慮してください。

​

ユーザビリティとセキュリティに関する考慮事項

organization名を使用してトークンをリクエストおよび検証する際は、以下のような潜在的影響を考慮してください。

• organization名は再利用される可能性があります: 有効期間の長いトークンは、organizationが名前を変更しても失効せず、それらのトークン内の org_name クレームには元の値が保持されます。元の名前が後で別のorganizationによって再利用されると、そのようなトークンによって、ユーザーに新しいorganizationが管理するデータやリソースへの不正なアクセスが許可される可能性があります。
• organization名が一意なのは単一の テナント 内だけです: APIがトークン内の iss (発行者) クレームを検証しない場合、別の テナント に同じ名前のorganizationがあると、そのorganizationが生成したトークンをAPIが誤って受け入れてしまう可能性があります。
• organization名は変更できます: organizationの名前を変更した場合、アプリケーションは Authentication API リクエストで新しいorganization名を指定する必要があります。トークンは長期間有効である場合があるため、トークン内の org_name クレームが現在のorganization名と一致しなくなり、その結果、アプリケーションが適切なorganizationへのアクセスを許可できなくなる可能性があります。

​

推奨されるベストプラクティス

セキュリティや使い勝手への影響を考慮すると、組織を扱う際にトークンを検証するには、名前ではなく ID を使用することを推奨します。organization名を使用する場合は、最適な利用体験のために以下のベストプラクティスに従ってください。

• トークンが Auth0 テナントによって発行されたことを確認するため、必ず iss クレームを検証してください。
• テナント内で以前使用されていた organization名を再利用しないでください。再利用を防ぎ、過去に発行されたトークンが別の組織へのアクセスに使われないようにするため、過去の organization名の正確かつ最新の記録を維持してください。
• 組織で使用を開始した後は、どうしても必要な場合を除き、organization名を変更しないでください。organization名を変更する場合は、既存のアクセストークンや ID トークンに新しいorganization名が自動的に含まれるわけではないことに注意してください。organization名を変更した後は、ユーザーに再度ログインするよう求めてください。