My Organization API リファレンス

Auth0 の My Organization API に関するドキュメント

バージョン: 1.0 (現行)

早期アクセス

My Organization API と埋め込み可能な UI コンポーネントは現在、すべてのお客様向けに早期アクセスとして提供されています。この機能を使用することで、Okta の Master Subscription Agreement に記載されている該当の Free Trial 条項に同意したものとみなされます。Auth0 の製品リリースサイクルの詳細については、Product Release Stages を参照してください。お客様は、My Organization API と埋め込み可能な UI コンポーネントの利用が、お客様のセキュリティポリシーおよび適用法令 (エンドユーザーに付与されるあらゆる権限を含む) に準拠していることを確保する責任を負います。

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

My Organization API のドキュメントは、My Organization API OpenAPI v3.1 schema に準拠しています。OpenAPI v3.1 schema のサポートは現在 Beta である点にご注意ください。

Auth0 ドメインとカスタムドメインの使用

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

• アクセストークンを取得する
• audience の値を設定する
• My Organization API endpoint を呼び出す

詳細については、Custom Domains を参照してください。

​

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

1. Auth0 Dashboard > Applications > APIs に移動します。
2. My Organization API のバナーを探します。
3. Activate を選択します。
4. Applications > API の一覧に、My Organization API が表示されます。

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

• この API は、デフォルトですべてのクライアントアプリケーションに対して無効になります。
• クライアントグラント または ロールベースのアクセス制御 ポリシーを使って、アプリケーションとロールにアクセス権を付与する必要があります。
• ビジネス顧客は、自身の Organizations に代わって、組織の詳細を取得したり、IDプロバイダー (IdPs) を設定したりできます。

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

require_client_grant (ユーザーフロー向け) deny-all (クライアント (machine-to-machine) フロー向け)

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

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

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

アプリケーションの API アクセスポリシーと、それに関連付けられたクライアントグラントの管理方法について詳しくは、API へのアプリケーションアクセス: クライアントグラント を参照してください。

​

クライアントアプリケーションの属性

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

クライアントアプリケーションは、以下のプロパティを含む特定の設定オブジェクト (my_organization_configuration) を指定する必要があります。

プロパティ	説明
my_organization_configuration	オブジェクト。 アプリケーションは、My Organization API が使用する設定を含むこのオブジェクトを指定する必要があります。アプリケーションでこのオブジェクトが定義されていない場合、My Organization API はエラーを返し、リクエストを拒否します。
my_organization_configuration.connection_profile_id	Connection Profile ID。 My Organization API の利用時にアプリケーションで使用される Connection Profile の ID です。指定しない場合、Connection Profile が必要な My Organization API の機能は動作しません。この ID は、同じテナント内の有効な Connection Profile を参照している必要があります。
my_organization_configuration.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 を参照している必要があります。
my_organization_configuration.allowed_strategies	文字列の配列。 各文字列は一意で、サポート対象の strategy を参照します。サポート対象の strategy (enum の値) は次のとおりです: pingfederate, ad, adfs, waad, google-apps, okta, oidc, samlp。
my_organization_configuration.connection_deletion_behavior	Enum (allow, allow_if_empty)。 このアプリケーションから My Organization API 経由でエンドユーザーが接続の削除を試みた場合に、My Organization API がどのように動作するかを示します。enum の値とその説明は次のとおりです: 1. allow: ユーザーが適切なスコープを持っている場合、接続を削除できます。削除すると、その接続に由来するすべてのユーザーも削除されます。 2.allow_if_empty: ユーザーが適切なスコープを持っている場合でも、接続内にユーザーが存在しない場合にのみ接続を削除できます。ユーザーが存在する場合、My Organization API はエラーを返し、削除は実行されません。

​

アクセストークンを取得する

My Organization API のアクセストークンは、自身の API のいずれかに対するアクセストークンを取得する場合と同じ方法で取得できます。

機密性の高い操作

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

​

使用例

​

認可コードフローの例

Client Secret を持つコンフィデンシャルな 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": 900,
  "scope": "read:my_org:details update:my_org:identity_providers"
}

​

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

Client Secret を持たないパブリックアプリケーション、シングルページアプリケーション、モバイルまたはネイティブアプリケーション、CLI ツールでは、PKCE (Proof Key for Code Exchange) を使用した 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/'

​

プロファイル

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 の仕組み、属性マッピングとオーバーライド、使用例、設定方法の詳細については、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

​

組織ごとのレート制限

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

ティア	組織ごとの読み取り (RPS)	組織ごとの書き込み (RPS)
Free	4	2
Public Self-Service	4	2
Public Enterprise	8	4
Private Basic	8	4
Private Performance	16	8

​

認証

HTTP: Bearer 認証

API の設定に応じて、Bearer トークンと DPoP トークンがサポートされます

セキュリティスキームの種類:	http
HTTP Authorization スキーム:	bearer