My Organization API リファレンス

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

バージョン: 1.0 (現行)

Early Access

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

Auth0 My Organization API は、ビジネス顧客が Auth0 テナント内で自社の組織を管理できるようにする、安全な組織スコープのインターフェースを提供します。この API は、埋め込み型 Delegated Administration と API ファーストの統合を支える技術的基盤です。

My Organization API のドキュメントは、My Organization API OpenAPI v3.1 schema に従っています。OpenAPI v3.1 スキーマのサポートは現在 Beta であることに注意してください。

Auth0 ドメインとカスタムドメインの使い分け

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

• アクセストークンの取得
• audience 値の設定
• My Organization API エンドポイントの呼び出し

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

​

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

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

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

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

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

require_client_grant はユーザーフロー用 deny-all はクライアント (マシンツーマシン) フロー用

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

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

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

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

​

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

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

​

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

My Organization API のアクセストークンは、独自の API 用のアクセストークンを取得する場合と同じ方法で取得できます。

機微な操作

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

​

例

​

Authorization Code Flow の例

クライアントシークレットを使用する機密性の高い Web アプリケーションでは、Authorization Code Flow を使用します。

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 Flow の例

クライアントシークレットを持たないパブリックアプリケーション、シングルページアプリケーション、モバイルアプリケーションまたはネイティブアプリケーション、CLI ツールには、Proof Key for Code Exchange (PKCE) を使用した Authorization Code Flow を使用します。

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 では、サードパーティの顧客が作成する構成の構造、制限、ルールを定義するために、接続プロファイル と ユーザー属性プロファイル を使用します。

​

接続プロファイル (CP)

接続プロファイルを使用すると、Auth0 開発者は、サードパーティが Auth0 の接続を作成する際に、そのプライベート設定をどのように構成するかを指定できます。接続プロファイルの仕組み、属性マッピングとオーバーライド、例、構成方法の詳細については、Connection Profiles を参照してください。

​

ユーザー属性プロファイル (UAP)

ユーザー属性プロファイル (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 つの組織がテナント全体のパフォーマンスに影響を及ぼすことを防ぐために設けられています。こうした上限を設けることで、「ノイジーネイバー」問題を緩和し、ある組織でアクティビティが急増しても、共有リソースが消費されたり、同じ環境内の別の組織に影響が及んだりしないようにしています。各組織には、読み取り操作と書き込み操作のそれぞれについて、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 認証スキーム:	bearer