Developer toolchainDeveloper Console基本概念アプリケーションの制限

注: 以下の翻訳の正確性は検証されていません。AIPを利用して英語版の原文から機械的に翻訳されたものです。

アプリケーションの制限

Developer Console の各アプリケーションは、Foundry の認可を処理する OAuth クライアントに対応しています。OAuth 認可時に、サードパーティアプリケーションには、特定の操作とリソースのみを許可するようにスコープで制限されたトークンが付与されます。トークンのスコープは実行時に決まり、次の積集合になります。

Foundry における、特定のアプリケーションユーザー（認可コードグラントの場合）またはサービスユーザー（クライアント資格情報グラントの場合）の権限。詳細は、認証グラントタイプのドキュメントを参照してください。
対象のアプリケーションについて Developer Console で設定された最大の制限。これは、そのアプリケーションが持つことのできる最大のスコープを定義します。アプリケーションを制限なしにしておくこともできます。
サードパーティアプリケーションがトークンリクエストの一部としてコードでリクエストする操作スコープ。このタイミングは「認可時」とも呼ばれます。スコープをリクエストしないトークンリクエストでは、デフォルトで、OAuth クライアントの制限で許可されているユーザーのすべての権限が許可されます。認可時に追加の制限は適用されません。

すべてのトークンは、OAuth クライアントレベル（アプリケーションの制限による）または認可時（トークンリクエストによる）のいずれかでスコープが制限されている必要があります。スコープの制限なしでトークンをリクエストしようとすると、権限のないトークンが生成されます。

アプリケーションの制限を設定する

アプリケーションは、制限ありまたは制限なしに設定できます。

制限ありのアプリケーションがデフォルトで作成されます。この場合、アプリケーションが Foundry で使用できるリソースと操作を Developer Console が制御します。
制限なしのアプリケーションには、許可されるリソースや操作の上限を定める制御がありません。ユーザーの権限と認可時にリクエストされた操作のみを使用してアクセスが決まります。

制限ありまたは制限なしの設定は、アプリケーション作成ウィザードには含まれていません。アプリケーションの作成後に、そのアプリケーションの［OAuth と制限］ページで変更します。

Developer Console でアプリケーションを開きます。
左側のナビゲーションパネルから［OAuth と制限］を選択します。
アプリケーションの制限で、制限ありまたは制限なしを選択します。

OAuth と制限ページのアプリケーションの制限セクションに表示された、制限ありと制限なしの選択肢。

制限なしのアプリケーションに切り替えると、現在のプロジェクトアクセスと操作制限の設定が削除されます。

制限なしから制限ありのアプリケーションに切り替える場合は、プロジェクトアクセスとプラットフォーム API の操作を設定する必要があります。この設定時に追加しなかったリソースをアプリケーションが使用している場合、アプリケーションが動作しなくなる可能性があります。

制限ありのアプリケーション

制限ありのアプリケーションは、アプリケーションの OAuth クライアントがリクエストできるリソースと操作の上限を制御します。たとえば、特定の Foundry データセットを読み取る権限を持つユーザーが、api:use-datasets-read をリクエストする制限ありのサードパーティアプリケーションを通じて、そのデータセットをクエリする場合を考えます。アプリケーションの制限に次の2つが追加されるまで、ユーザーはアクセスできません。

そのデータセットを含むプロジェクトを、アプリケーションのリソース制限に追加します。
api:use-datasets-read を、アプリケーションの操作制限に追加します。

制限ありのアプリケーションでは、ユーザーに代わってアプリケーションが実行できるすべてのことを開発時に定義することで、実行前から動作の範囲を把握しやすくなります。これにより、アプリケーションのコードがユーザーのアクセス権を利用して、アプリケーションの作成者にはアクセス権がなかった操作を実行するような権限昇格のケースを最小限に抑えます。また、制限は、Foundry が特定のデバイスやシステムに送信できるデータの上限を確実に守るためにも役立ちます。たとえば、制限を設けることで、制御室に表示されるアプリケーションに、ログインしているユーザーにかかわらず、機密性の高いコンテンツが決して表示されないことを保証できます。

リソース制限

リソース制限は、アプリケーションがアクセスできる Foundry リソースを定義します。Developer Console の左側のナビゲーションパネルからアクセスできる、次の場所でリソース制限を設定します。

オントロジー SDK タブ： アプリケーションがオントロジーとやり取りする場合（通常はオントロジー SDK を使用）、このタブでオブジェクトタイプ、インターフェース、アクション、および関数をアプリケーションリソースのリストに追加します。オントロジーリソースを追加すると、Developer Console アプリケーションに次の2つの変更が生じます。
1. アプリケーションのリソース制限で、リストに記載されたリソースへのアクセスが許可されます。
2. そのアプリケーション用に生成される新しい SDK に、リストに記載されたリソースが含まれます。

プラットフォーム SDK タブ： アプリケーションがプラットフォーム API とやり取りする場合（通常はプラットフォーム SDK を使用）、このタブで Foundry プロジェクトをリソース制限に追加します。制限ありのアプリケーションは、これらのプロジェクト内のリソースに対してのみ読み取りまたは書き込みができます。プロジェクト内に_ない_ Foundry リソースとアプリケーションがやり取りする必要がある場合は、制限なしのアプリケーションの使用を検討してください。

操作制限

操作制限は、アプリケーションが実行できる API 操作を定義します。リソース制限とは異なり、操作制限はプラットフォーム SDK タブでのみ設定できます。

このタブから、API 名前空間を通じて許可する操作を追加します。選択したプロジェクトリソースとやり取りするためにアプリケーションが使用できるメソッドを選択します。操作は、エンドポイントのパスに対応する API 名前空間でグループ化されています。たとえば、/admin/ API 名前空間には、パスが /api/{version}/admin/ であるすべてのエンドポイントが含まれます。API 名前空間の詳細は、API ドキュメントを参照してください。

クライアントに許可された操作に対する API レベルのセキュリティ

Developer Console アプリケーションは、制限ありのアプリケーションに対して API レベルのセキュリティを適用し、これらのアプリケーションが呼び出すエンドポイントがすべて、プラットフォーム SDK パネルの操作制限リストに明示的に追加されていることを必須とします。制限なしのアプリケーションはこれらの変更の影響を受けず、ユーザーがアクセスに必要な権限を持つエンドポイントを引き続き呼び出すことができます。制限なしのアプリケーションは、通常、プラットフォーム全体を対象とするプログラムによるワークフローにのみ使用するべきです。

制限なしのアプリケーション

_制限なし_のアプリケーションでは、アクセスを事前定義されたリソースに制限するのではなく、アクセスを決める際にアプリケーションユーザーの権限のみを考慮します。

デフォルトでは、より厳格なセキュリティ保証を促すために、カスタムアプリケーションは制限ありになっています。次の状況では、制限なしのアプリケーションを使用します。

デプロイ時にリソースを定義できない場合（たとえば、まだ存在しないプロジェクト）。
アプリケーションが、プロジェクト外の管理プリミティブにアクセスする必要がある場合（たとえば、スペース、組織、エンロールメント）。
プラットフォーム API でまだリリースされていないエンドポイントを使用する必要がある場合。

制限なしのアプリケーションは、アプリケーションユーザーがアクセス権を持つ任意のリソースとやり取りできます。制限なしのアプリケーションは、信頼できるコードでのみ使用してください。

制限なしのアプリケーションを作成する

制限なしのアプリケーションは、作成できなくなったスタンドアロン OAuth クライアントの推奨される代替手段です。作成ウィザードには制限ありまたは制限なしを選ぶ項目がないため、アプリケーションの作成中に選択するものはありません。まずアプリケーションを作成してから、制限を変更します。

新しい Developer Console アプリケーションを作成するに従って Developer Console アプリケーションを作成し、作成ウィザードで次の選択を行います。アプリケーションタイプと権限の選択によって、アプリケーションの認証方法が決まります。両方の詳細については、権限を確認してください。
- アプリケーションタイプページで、クライアント資格情報を安全に保存できるアプリケーションにはバックエンドサービスを、保存できないフロントエンドにはクライアント向けアプリケーションを選択します。
- 権限ページで、生成された専用のサービスユーザーを通じて動作するアプリケーションにはアプリケーションの権限を、ログイン中のユーザーとして動作するアプリケーションにはユーザー権限を選択します。クライアント向けアプリケーションはユーザー権限を使用する必要があります。
- リソースページで、アプリケーションがプラットフォーム API のみを呼び出す場合は、いいえ、オントロジー SDK は使用しませんを選択します。ステップ3でアプリケーションの制限を解除するとその設定が削除されるため、Foundry プロジェクトとプラットフォーム API の操作の追加もスキップできます。
バックエンドサービスを選択した場合は、アプリケーションの作成時に表示されるクライアントシークレットをコピーします。シークレットが表示されるのはこのときだけです。紛失した場合は、シークレットをローテーションする必要があります。クライアント向けアプリケーションとしてのみ設定されたアプリケーションは、パブリック OAuth クライアントを使用し、クライアントシークレットを持ちません。
アプリケーションの制限を設定するの手順に従って、新しいアプリケーションを制限なしに変更します。このステップでアプリケーションの制限が解除されます。この操作は、アプリケーションが作成された後にのみ利用可能です。
認可時にスコープをリクエストするの説明に従って、アプリケーションに必要な操作スコープをアプリケーションコードでリクエストします。認可コードグラントを使用する制限なしのアプリケーションは、スコープをリクエストする必要があります。

認可時にスコープをリクエストする

Developer Console で設定された制限に加えて、サードパーティアプリケーションは認証の一環として操作スコープをリクエストすることもできます。前述のとおり、アクセスを決定する際には、リクエストされたスコープと、アプリケーションの制限およびユーザーが持つ権限との共通部分が適用されます。Foundry のサードパーティアプリケーションが認可時にリクエストできるのは、_操作_のみです。_リソース_へのアクセスは、アプリケーションのリソース制限とユーザー権限のみによって決まり、リクエストは必要ありません。

Foundry のエンドポイントに必要なスコープは、API ドキュメントに記載されています。次の例は、オントロジーデータと Foundry データセットを読み取るための、TypeScript OAuth クライアントによるスコープリクエストを示しています。

Copied!1
2
3
4
5
6
7
8
9
10
11
12
13
const scopes = ["api:use-ontologies-read", "api:use-datasets-read"];

export const auth: PublicOauthClient = createPublicOauthClient(
    clientId,
    foundryUrl,
    redirectUrl,
    { scopes },
);

/**
 * オントロジー SDK およびプラットフォーム SDK と連携するためにクライアントを初期化します
 */
export const client: Client = createClient(foundryUrl, ontologyRid, auth);

リクエストする操作スコープが空（[]）の場合、アプリケーションの操作制限がデフォルトで適用されます。制限なしのアプリケーションには許容される制限の上限がなく、リクエストする認証グラントの種類によって動作が異なります。

クライアント資格情報グラント： スコープのリクエストは必要ありません。スコープをリクエストしないアプリケーションには、サービスユーザーがアクセスできるすべての操作が許可されます。
認可コードグラント： アプリケーションはスコープをリクエストする必要があります。認可コードフローでは、人間のユーザーがリクエストされた操作に同意します。そのため、アプリケーションの作成者は、アプリケーションに必要な操作を定義する必要があります。これにより、権限昇格に関連する攻撃経路を最小限に抑えられます。

API セキュリティに移行する

前述のとおり、2025年6月1日より後に作成された Developer Console アプリケーションでは、API レベルのセキュリティが適用されます。これにより、制限付きサードパーティアプリケーションが呼び出すすべてのエンドポイントを、クライアントに許可された操作のリストに個別に追加する必要があります。2025年6月1日より前に作成されたアプリケーションについては、以下の移行手順に沿って進めてください。

新しいアプリケーションや移行済みのアプリケーションでは、これまで許可されていた2種類のアプリケーションへのアクセスが制限されるようになります。基盤サービスのエンドポイントと暗黙的な操作権限の付与です。

基盤サービスのエンドポイントへのアクセス不可

制限付きアプリケーションは、基盤サービスの API を呼び出すことができません。これらは、ドキュメントに明示的に記載されておらず、ユーザーにも公開されていないエンドポイントです。

Developer Console アプリケーションのクライアントが使用するスコープには、接頭辞 use- が含まれるようになりました。たとえば、api:ontologies-read ではなく api:use-ontologies-read を使用します。これらの新しい権限で呼び出せるのは Foundry のプラットフォーム API のみであり、基盤サービスのエンドポイントの呼び出しはブロックされます。

API セキュリティの重要な例外として、識別、認可、またはアクセスのデバッグを目的として、ユーザーが常にアクセスできるように設計された管理用エンドポイントがあります。これらのエンドポイントは、一般公開して広く利用されることを想定していないため、公開されている Foundry API ドキュメントやプラットフォームSDKリソースパネルには含まれていません。該当するエンドポイントには、以下があります。

OAuth2: /multipass/api/oauth2/...
ユーザー情報: /multipass/api/me/...
リソースアクセス情報: /multipass/api/authz/...
トークン TTL: /multipass/api/token/...
組織: /multipass/api/organizations/...

これらのエンドポイントは、制限付きアプリケーションから常に呼び出すことができます。

暗黙的な操作権限の付与なし

高度な API レベルのセキュリティが追加されたことで、API の名前空間はそれぞれ厳密に分離されます。この変更以前は、API 名前空間のスコープを付与すると、その名前空間内のエンドポイントに加えて、ほかの名前空間内の_依存先エンドポイント_にもアプリケーションがアクセスできました。新しい、より安全な API スコープ（接頭辞 use- を持つスコープ）では、直接付与された API 名前空間にのみアクセスできます。これにより、アプリケーション管理者は、組織内でアプリケーションが実行できる操作を厳密に制御できます。

たとえば、/ontologies/ API 名前空間の権限（api:use-ontologies-read）が付与されたレガシーアプリケーションは、/admin/ 名前空間の /api/v2/admin/users/getCurrent エンドポイントで、ユーザーの基本的な属性情報をクエリできます。これは、いくつかのオントロジーのエンドポイントが、認証のためにこれらの操作を必要とするためです。改善されたセキュリティプロトコルに移行すると、api:use-ontologies-read と api:use-ontologies-write のスコープのみが付与されているアプリケーションは、このユーザー情報にアクセスできなくなり、ApiUsageDenied エラーを受け取ります。

デフォルトでは、セキュリティ更新後に作成された、または高度な API レベルの保護を使用するように移行されたすべての Developer Console アプリケーションに、api:use-ontologies-read と api:use-ontologies-write のスコープが設定されます。

移行手順

高度な API セキュリティを使用するように Developer Console アプリケーションを移行するには、以下の手順に沿って進めてください。

プラットフォームSDKリソースタブに移動し、移行を選択します。

ダイアログの指示に従って、アプリケーションコードを更新します。TypeScript SDK を使用している場合は、リクエストする操作スコープを変更し、アップグレードされたセキュリティモデルに準拠する新しいスコープを使用します。一時的に動作しなくなることを防ぐため、新しいスコープを追加する際に、元の操作スコープを_削除しないでください_。

TypeScript SDK の操作スコープを変更して、セキュリティモードを移行します。

アプリケーションの移行が正常に完了したら、アプリケーションコードから元の古いスコープを削除できます。

スコープの接頭辞

Foundry では、API 権限に2種類のスコープ接頭辞を使用します。

スコープパターン	例	ユースケース
`api:use-*-read/write`	`api:use-ontologies-read`	新しい制限付き Developer Console アプリケーション。公開 API の呼び出しのみを許可します。
`api:*-read/write`	`api:ontologies-read`	スタンドアロン OAuth クライアントと一部の制限なしのアプリケーション。公開 API と内部サービスのエンドポイントの呼び出しを許可します。

使用するスコープを選択する際の指針は以下のとおりです。

制限付きアプリケーションでは、api:use-* スコープ（たとえば、api:use-ontologies-read）を使用してください。
スタンドアロン OAuth クライアント では、前述のとおり Foundry を直接呼び出すため、api:* スコープ（たとえば、api:ontologies-read）を使用してください。注：スタンドアロン OAuth クライアントは、制限なしのアプリケーションへの置き換えが進められているレガシーのプリミティブです。
制限なしのアプリケーションでは、Foundry の基盤サービスのエンドポイントをクエリする場合を除き、api:use-* スコープを使用してください。

このパターンは、admin、ontologies、datasets、streams など、すべての API 名前空間に適用されます。

スタンドアロン OAuth クライアント [レガシー]

レガシー

Developer Console からスタンドアロン OAuth クライアントを作成することはできなくなりました。代わりに、制限なしのアプリケーションを作成する手順に沿って進めてください。

スタンドアロン OAuth クライアントは、カスタムアプリケーションに代わるレガシーの軽量な選択肢です。認証クライアント自体の機能以外に、スタンドアロン OAuth クライアントには、制限、メトリクス、SDK 生成といったアプリケーション構築機能はありません。

制限なしのアプリケーションは、機能が充実したカスタムアプリケーション内で同等の柔軟なアクセスを提供することで、スタンドアロン OAuth クライアントに代わるものとなります。

既存のスタンドアロン OAuth クライアントを Developer Console アプリケーションに移行するには、以下の手順に沿って進めます。

既存のスタンドアロン OAuth クライアントを開きます。
Developer Console アプリケーションに移行を選択します。
移行ウィザードで、場所と、該当する場合は最大機密情報区分を選択します。
Developer Console アプリケーションのユーザー権限を確認します。
確定を選択します。

移行後、新しく作成されたアプリケーションが選択した場所に表示されます。ほかの Developer Console アプリケーションと同様に、そのアプリケーションに対して操作を実行できます。このクライアントを使用する既存のワークフローには影響しません。