My Organization API と埋め込み可能な UI コンポーネント

My Organization API を使用して、Auth0 組織 の管理者がアプリケーション内から自身のアイデンティティプロバイダーと検証済みドメインを管理できるようにします。

My Organization API と埋め込み可能な UI コンポーネントは現在、すべてのお客様に 早期アクセス として提供されています。この機能を使用することにより、Okta’s Master Subscription Agreement に記載された該当する Free Trial 条項に同意したものとみなされます。Auth0 の製品リリースサイクルの詳細については、Product Release Stages をご覧ください。

お客様は、My Organization API と埋め込み可能な UI コンポーネントの利用が、お客様のセキュリティポリシーおよび適用される法令 (エンドユーザーに付与するあらゆる権限を含む) に準拠していることを確保する責任を負います。

Auth0 My Organization API は、安全で組織ごとにスコープが設定されたインターフェースを提供し、ビジネス顧客が Auth0 テナント内で自身の組織 を管理できるようにします。この API は、埋め込み型の委任管理や API-first の連携を支える技術基盤として機能します。

​

主な機能

現在、この API では以下を管理できます。

• Auth0 組織 の詳細 (名前、ブランディング、表示名)
• 組織ごとの設定、所有権、関係性
• IDプロバイダー (IdPs) と SCIM のプロビジョニング
• ドメインとホームレルムディスカバリー (HRD) の設定

My Organization API を使用すると、連携を技術的にきめ細かく制御できます。最短でデプロイするには、埋め込み可能な UI コンポーネント、SDK、サンプルアプリケーションから始めることを強くお勧めします。埋め込み可能な UI コンポーネントとサンプルアプリケーションを使用すると、顧客やエンドユーザーにセルフサービス体験を提供するまでの時間と労力を大幅に削減できます。

​

My Organization API を設定する

​

Auth0 Dashboard で My Organization API を有効化する

1. Auth0 Dashboard > アプリケーション > APIs に移動します。
2. My Organization API のバナーを見つけます。
3. 有効化 を選択します。
   
4. My Organization API が、アプリケーション > APIs の一覧に表示されます。

My Organization API を有効化すると、次のようになります。

• Auth0 では、デフォルトですべてのクライアントアプリケーションでこの API が無効になります。
• クライアントグラント または RBAC ポリシーを使用して、アプリケーションとロールにアクセス権を付与する必要があります。
• 顧客企業は、自社の組織 に代わって、組織 の詳細を取得したり IdPs を設定したりできます。

​

デフォルト設定

Auth0 ドメインとカスタムドメイン

My Organization API では、標準の Auth0 ドメインまたはカスタムドメインを使用できますが、次の各操作を含む一連のプロセス全体で、必ず同じドメインを使用する必要があります。

• アクセストークンをリクエストする
• audience または aud の値を設定する
• My Organization API エンドポイントを呼び出す

Auth0 でカスタムドメインを使用する方法の詳細については、Custom Domains をご覧ください。

アクセスポリシー

デフォルトでは、My Organization API は次のアプリケーション API アクセスポリシーで有効になります。

• ユーザーフローでは require_client_grant
• machine-to-machine フローでは deny-all

アプリケーションがユーザーに代わって My Organization API にアクセスするには、そのアプリケーション用のクライアントグラントを作成し、アプリケーションがリクエストできるスコープの上限を定義します。あるいは、ユーザーアクセスフローを allow_all に変更すると、テナント内の任意のアプリケーションが任意のスコープをリクエストできるようになります。

My Organization API は機密性の高い情報や操作を公開するため、Auth0 ではユーザーアクセスフローに allow_all を使用することを推奨していません。アプリケーションには本当に必要なアクセス権だけを付与するよう、最小権限の原則に従い、潜在的なセキュリティリスクを最小限に抑えてください。

アプリケーションに最終的に付与される権限は、アプリケーション API アクセスポリシーで許可されるスコープ、エンドユーザーに割り当てられたロールベースのアクセス制御 (RBAC) の権限、およびユーザーが付与した同意 (該当する場合) の積集合によって決まります。

アプリケーション API アクセスポリシーと、それに関連付けられたクライアントグラントの管理方法の詳細については、Application Access to APIs: Client Grants をご覧ください。

トークンの有効期間

My Organization API は、有効期間が 600 秒 (10 分) に固定されたアクセストークンを発行します。この短い有効期間は、テナントとそのリソースを保護するための意図的なセキュリティ対策です。

My Organization API は、セキュリティ上の理由から常にオプトイン方式です。API を無効にすると、再度有効化するまで、接続されているすべてのアプリケーションからアクセスできなくなります。

​

クライアントアプリケーションの属性を設定する

My Organization API で使用するアプリケーションを作成します。作成後、Auth0 Dashboard > アプリケーション > APIs に移動し、アプリケーションに実行を許可するスコープを含めて My Organization API を認可します。

アプリケーションでは my_organization_configuration オブジェクトを指定する必要があります。指定しない場合、My Organization API はエラーを返してリクエストを拒否します。my_organization_configuration オブジェクトでは、次のプロパティを使用できます。

Property	Description
connection_profile_id	Connection Profile ID. My Organization API の利用時にアプリケーションで使用される Connection Profile の ID です。指定しない場合、Connection Profile の存在を必要とする My Organization API の機能は動作しません。この ID は、同じテナント内の有効な Connection Profile を参照している必要があります。
user_attribute_profile_id	User Attribute Profile ID。My Organization API の利用時にアプリケーションで使用される User Attribute Profile の ID です。指定しない場合、User Attribute Profile の存在を必要とする My Organization API の機能は動作しません。この ID は、同じテナント内の有効な User Attribute Profile を参照している必要があります。
allowed_strategies	Array of strings. 各文字列は一意で、サポート対象の strategy を示します。サポート対象の strategy (enum の値) は次のとおりです: pingfederate, ad, adfs, waad, google-apps, okta, oidc, samlp。
connection_deletion_behavior	Enum (allow, allow_if_empty). このアプリケーションから My Organization API 経由でエンドユーザーが接続の削除を試みたときに、My Organization API がどのように動作するかを示します。enum の値と説明は次のとおりです: 1. allow: ユーザーが適切な scope を持っている場合、接続を削除できます。その結果、その接続に由来するすべてのユーザーも削除されます。 2.allow_if_empty: ユーザーが適切な scope を持っている場合、接続内にユーザーが存在しないときに限り、接続を削除できます。ユーザーが存在する場合、My Organization API はエラーを返し、削除は実行されません。

​

クライアントアプリケーション属性を設定する

Auth0 Dashboard

My Organization API の必須属性を設定するには、次の手順に従います。

1. Dashboard > アプリケーション > APIs に移動し、My Organization API を選択します。

2. Application Access タブを選択します。

3. 設定するアプリケーションを選択し、Edit を選択します。

4. 次の設定を行います。
   A. 任意。Connection Profile を設定します。
   

   1. 既存の Connection Profile を選択するか、新しく作成します。新しい Connection Profile の場合:
      a. 名前を追加します。
      b. 新しい接続に対して意図した設定が接続属性に反映されていることを確認するため、マッピングを確認します。
      

   B. 任意。User Attribute Profile を設定します。
   

   1. 名前を追加します。
      
   2. プロファイル属性が希望する Auth0 の属性にマッピングされていることを確認するため、マッピングを確認します。
      

   C. サポート対象の IDプロバイダー を設定します。
   

   1. 1 つ以上の IDプロバイダー を有効にします。顧客管理者は、有効化されたプロバイダーの一覧から希望するオプションを選択できます。
      

   D. 接続削除時の動作を Allow または Allow if Empty に設定します。
   

   1. Allow: ユーザーが適切なスコープを持っている場合、接続を削除できます。その結果、その接続に由来するすべての Users も削除されます。
      
   2. Allow if Empty: ユーザーが適切なスコープを持っている場合、接続内に Users が存在しないときにのみ接続を削除できます。Users が存在する場合、My Organization API はエラーを返し、削除は実行されません。
      

   E. ユーザーアクセスの認可を Unauthorized、Authorized、または All に設定します。
   

   1. Unauthorized。権限は付与されません。
      
   2. Authorized。必要な権限を選択します。
      
   3. All。既存および今後追加されるすべての権限が含まれます。
      

   F. クライアント認証情報アクセスの認可を Unauthorized、Authorized、または All に設定します。
   

   1. Unauthorized。権限は付与されません。
      
   2. Authorized。必要な権限を選択します。
      
   3. All。既存および今後追加されるすべての権限が含まれます。
      

5. Save を選択します。

Management API

Auth0 Dashboard を使用せずにクライアントアプリケーション属性をプログラムで設定するには、利用可能な Management API エンドポイントを使用します。Management API を使用するには、Management API access token を取得する必要があります。

• GET /api/v2/clients
• POST /api/v2/clients
• GET /api/v2/clients/{id}
• PATCH /api/v2/clients/{id}

​

アクセストークンを生成する

My Organization API は、サポートされている OAuth 2.0フロー のいずれかを通じて取得した、ユーザーに紐付けられたアクセストークンでのみ呼び出せます。

My Organization API で機密性の高い操作を許可する場合は、多要素認証 (MFA) によって追加のセキュリティポリシーを適用するために、ステップアップ認証 を使用することを強くお勧めします。

​

認可コードフローの例

Client Secret を持つ confidential な Web アプリケーションでは、認可コードフロー を使用します。

curl --request POST \
--url 'https://YOUR_DOMAIN/oauth/token' \
--header 'content-type: application/x-www-form-urlencoded' \
--data 'grant_type=authorization_code' \
--data 'client_id=YOUR_CLIENT_ID' \
--data 'client_secret=YOUR_CLIENT_SECRET' \
--data 'code=AUTH_CODE' \
--data 'redirect_uri=https://yourapp/callback' \
--data 'audience=https://YOUR_DOMAIN/my-org/'

レスポンス例

{
  "access_token": "eyJz93a...k4laUWw",
  "token_type": "Bearer",
  "expires_in": 600,
  "scope": "read:my_org:details update:my_org:identity_providers"
}

​

PKCE を使用した Authorization Code フローの例

Client Secret を持たないパブリックアプリケーション、シングルページアプリケーション、モバイルまたはネイティブアプリケーション、CLI ツールには、PKCE を使用した Authorization Code フローを使用します。

curl --request POST \
--url 'https://YOUR_DOMAIN/oauth/token' \
--header 'content-type: application/x-www-form-urlencoded' \
--data 'grant_type=authorization_code' \
--data 'client_id=YOUR_CLIENT_ID' \
--data 'code=AUTH_CODE' \
--data 'code_verifier=CODE_VERIFIER' \
--data 'redirect_uri=https://yourapp/callback' \
--data 'audience=https://YOUR_DOMAIN/my-org/'

​

Audience

My Organization API の audience とベース URL は https://{yourDomain}/my-org/ です。トークンには https://YOUR_DOMAIN/my-org/ という audience を含める必要があります。ほかの API (/me や /api/v2/ など) 用のトークンは使用できません。

​

スコープ

スコープ	説明
read:my_org:configuration	クライアントのorganization設定を参照する
read:my_org:details	クライアントのorganization詳細を参照する
update:my_org:details	クライアントのorganization詳細を更新する
create:my_org:identity_providers	organizationのアイデンティティプロバイダーを作成する
read:my_org:identity_providers	organizationのアイデンティティプロバイダーを参照する
update:my_org:identity_providers	organizationのアイデンティティプロバイダーを更新する
delete:my_org:identity_providers	organizationのアイデンティティプロバイダーを削除する
update:my_org:identity_providers_detach	organizationからアイデンティティプロバイダーを切り離す
create:my_org:identity_providers_domains	organizationドメインをアイデンティティプロバイダーに関連付ける
delete:my_org:identity_providers_domains	アイデンティティプロバイダーからorganizationドメインを削除する
read:my_org:identity_providers_scim_tokens	このアイデンティティプロバイダーのプロビジョニングSCIMトークンを一覧表示する
create:my_org:identity_providers_scim_tokens	このアイデンティティプロバイダーのプロビジョニングSCIMトークンを作成する
delete:my_org:identity_providers_scim_tokens	アイデンティティプロバイダーのプロビジョニングSCIMトークン設定を削除する
create:my_org:identity_providers_provisioning	アイデンティティプロバイダーのプロビジョニング設定を作成する
read:my_org:identity_providers_provisioning	アイデンティティプロバイダーのプロビジョニング設定を参照する
update:my_org:identity_providers_provisioning	アイデンティティプロバイダーのプロビジョニング設定を更新する
delete:my_org:identity_providers_provisioning	アイデンティティプロバイダーのプロビジョニング設定を削除する
read:my_org:domains	organizationのドメインを参照する
delete:my_org:domains	organizationのドメインを削除する
create:my_org:domains	organizationのドメインを作成する
update:my_org:domains	organizationのドメインを更新する

​

エンドポイントリファレンス

My Organization API は、Configuration、組織の詳細、アイデンティティプロバイダー、ドメイン、プロビジョニング設定、SCIM トークンに関するエンドポイントをサポートしています。スキーマやエラーコードなどを含むエンドポイントの完全なリファレンスについては、API Explorerを参照してください。

​

SDK リファレンス

API は、TypeScript、Java、.NET、Go、Python 向けの SDK として提供されています。各 SDK 実装の詳細や SDK の活用例については、SDK ドキュメントを参照してください。

​

ユーザープロファイル

My Organization API は、Connection Profiles と User Attribute Profiles を使用して、サードパーティの顧客が作成する設定の構造、制限、ルールを定義します。

​

Connection Profile (CP)

Connection Profile を使用すると、サードパーティが Auth0 接続を作成する際に、その非公開設定をどのように構成するかを Auth0 開発者が指定できます。Connection Profile の仕組み、属性マッピングと上書き設定、例、設定方法について詳しくは、Connection Profiles を参照してください。

​

User Attribute Profile (UAP)

User Attribute Profile (UAP) は、SCIM、SAML、OIDC などのプロトコル全体でユーザー属性を一貫して定義、管理、マッピングするための仕組みを提供します。UAP の動作の仕組み、属性マッピングと overrides、例、設定方法の詳細については、User Attribute Profiles をご覧ください。

​

レート制限

レート制限は、サービスティアに応じて適用されます。

ティア	読み取り (RPS)	書き込み (RPS)
Free	4	2
Public Self-Service	8	4
Public Enterprise	40	20
Private Basic	40	20
Private Performance	160	80

​

Organization ごとのレート制限

サービスティアのレート制限に加えて、My Organization API では Organization ごとのレート制限も適用されます。これらの制限は、リソースの公平な割り当てを確保し、単一の Organization がテナント全体のパフォーマンスに影響を及ぼすのを防ぐために設けられています。こうした上限を設けることで、「ノイジーネイバー」問題を軽減し、1 つの Organization でアクティビティが急増しても、共有リソースが消費されたり、同じ環境内の別の Organization に影響が及んだりしないようにしています。各 Organization には、読み取り操作と書き込み操作の両方について、1 秒あたりのリクエスト数 (RPS) が個別に割り当てられます。

Tier	Organization ごとの読み取り (RPS)	Organization ごとの書き込み (RPS)
Free	4	2
Public Self-Service	4	2
Public Enterprise	8	4
Private Basic	8	4
Private Performance	16	8

​

クロスオリジン リクエスト

Auth0 テナントとは異なるドメインで動作するブラウザベースのアプリケーション (Single Page Application など) から My Organization API を直接呼び出す場合は、クロスオリジン リソース共有 (CORS) と呼ばれるブラウザのセキュリティポリシーの影響を受けます。既定では、ブラウザはこのようなクロスオリジン リクエストをブロックします。

アプリケーションから API に正常にリクエストを送信できるようにするには、アプリケーションのドメイン (「オリジン」) をクライアントの設定に追加する必要があります。

1. Auth0 Dashboard > アプリケーション に移動し、対象のアプリケーションを選択します。
2. Cross-Origin Authentication で、Allow Cross-Origin Authentication をオンにします。
3. Allowed Origins (CORS) を見つけて、アプリケーションのオリジン URL を入力します。
4. Save を選択します。

アプリケーションで CORS を使用する必要がない場合は、Allow Cross-Origin Authentication がオフになっていることを確認してください。アプリケーションの URL をこのリストに追加すると、Auth0 はそのオリジンからのリクエストを信頼し、クライアントサイドのアプリケーションが API にアクセスできるようになります。

​

ログイベント

きめ細かな監査と監視を可能にするため、My Organization API は、この API 固有のログイベント一式を生成します。テナントは引き続き標準のシステムログを出力しますが、以下の表には、My Organization API のアクティビティによって特にトリガーされるイベントタイプの完全な一覧を示しています。

これらのイベントコードを使用すると、API で管理されるすべてのリソース、具体的には設定、組織の詳細、IdP、ドメインにわたるアクティビティを追跡できます。ログイベントのスキーマの詳細については、GitHubリポジトリを参照してください。

イベントコード	イベント	イベントの説明
my_organization_api_config_failed	My Organization API Config Failed	My Organization API サービスの設定リソースに対する API 呼び出しが失敗したことを示します
my_organization_api_org_details_succeeded	My Organization API Org Details Succeeded	My Organization API サービスの組織詳細リソースに対する API 呼び出しが成功したことを示します
my_organization_api_org_details_failed	My Organization API Org Details Failed	My Organization API サービスの組織詳細リソースに対する API 呼び出しが失敗したことを示します
my_organization_api_idp_succeeded	My Organization API Identity Provider Succeeded	My Organization API サービスのアイデンティティプロバイダーリソースに対する API 呼び出しが成功したことを示します
my_organization_api_idp_failed	My Organization API Identity Provider Failed	My Organization API サービスのアイデンティティプロバイダーリソースに対する API 呼び出しが失敗したことを示します
my_organization_api_domain_succeeded	My Organization API Domain Succeeded	My Organization API サービスのドメインリソースに対する API 呼び出しが成功したことを示します
my_organization_api_domain_failed	My Organization API Domain Failed	My Organization API サービスのドメインリソースに対する API 呼び出しが失敗したことを示します

​

組織の接続の所有権

この API では、Tenant Admin によって管理される接続と、組織が自ら管理する接続を区別するために、所有権モデルが導入されています。これは organization_access_level プロパティで制御されます。

主要プロパティ: organization_access_level

Enum Value	Description
none	Tenant Administrator によって割り当てられた関連付けです。この接続は My Organization API 経由では表示も編集もできません。
readonly	Tenant Administrator によって割り当てられた関連付けです。表示はできますが、My Organization API 経由で編集することはできません。
limited	Tenant Administrator によって割り当てられた関連付けです。My Organization API 経由で限定的な情報の参照と変更が可能で、具体的には show_as_button と is_enabled 属性です。
full	Tenant Administrator によって割り当てられた関連付けです。My Organization API の利用者は、追加の制限なしで、組織固有の接続属性、具体的には show_as_button、is_enabled、options、display_name、domains を変更できます。

接続用の Management API エンドポイント:

• GET /api/v2/organizations/{id}/connections
• POST /api/v2/organizations/{id}/connections
• PATCH /api/v2/organizations/{id}/connections/{id}
• DELETE /api/v2/organizations/{id}/connections/{id}

/connections エンドポイントを呼び出す際は、/enabled_connections エンドポイントと同じスコープを使用します。

• create:organization_connections
• read:organization_connections
• delete:organization_connections
• update:organization_connections

追加のスキーマ属性を確認してください。

Property	Description
is_enabled	Boolean。組織に対する接続の有効／無効を切り替えます。接続を無効にしても、接続 Object の値は保持されたままになります。
organization_access_level	Enum (null, none, readonly, limited, full)。My Organization API の利用時にユーザーが持つアクセスの種類を決定します: 1. null 2. none - Tenant Administrator によって割り当てられた関連付けです。この接続は My Organization API 経由では表示も編集もできません。 3. readonly - Tenant Administrator によって割り当てられた関連付けです。この接続は表示できますが、My Organization API 経由で編集することはできません。 4. limited - Tenant Administrator によって割り当てられた関連付けです。My Organization API 経由で限定的な情報の参照と変更が可能です。 5. full - Tenant Administrator によって割り当てられた関連付けです。My Organization API の利用者は、My Organization API の利用時に追加の制限なく接続を変更できます。注: organization_access_level にかかわらず、My Organization API による変更には常に Connection Profile による制限が適用されます。
organization_connection_name	String。接続の作成時に指定された名前を保存します。このフィールドは、Connection Profile の connection_name_prefix_template を評価することで My Organization API により算出されます。このフィールドを表示または変更できるのは Management API 経由のみです。

注記:

• これらのエンドポイントは、任意のクエリパラメータ is_enabled=true/false を受け付けます。指定した場合は、指定された is_enabled 値を持つ接続のみが表示されます。
• organization_access_level は Management API 経由でのみ変更できます。
• name 属性が設定されていない場合は、organization_access_level を none から他の値に変更する前に、Management API 経由で設定しておく必要があります。

​

Auth0 Universal Components

API-first の連携を利用するのではなく、埋め込み可能な UI コンポーネントである Auth0 Universal Components から始めることを強くお勧めします。これらのリソースを活用することで、開発時間を大幅に短縮し、顧客にセルフサービス体験をすばやく提供できます。