クライアント資格情報アプリケーション

クライアント資格情報アプリケーションは、認証にクライアント資格情報を使用する、外部でホストされる OAuth またはオントロジー SDK アプリケーションです。これらのアプリケーションは、ユーザー規模を最大化する必要があるプロコードソリューションに最適で、Foundry の外部で顧客が独自の認証および認可ロジックを定義できます。

クライアント資格情報アプリケーションは、次のユースケースに最適です。

• ユーザーログインを必要としないサーバー間の統合。
• Foundry データにプログラムでアクセスする必要がある自動化システム。
• データを処理したり、ワークフローをトリガーしたりするバックエンドサービス。
• 外部プラットフォームとの API 統合。
• ユーザーごとの認証なしで多数のユーザーにサービスを提供する必要がある一般公開アプリケーション。

アーキテクチャ

クライアント資格情報アプリケーションは、クライアントIDとクライアントシークレットを使用して認証します。その後、サービスユーザーに紐付いたアクセストークンを受け取り、そのトークンを使用してサービスユーザーの権限で Foundry への API 呼び出しを行います。

External application → OAuth Client Credentials → Service user → Foundry APIs

前提条件

クライアント資格情報アプリケーションをセットアップする前に、次の条件を満たしていることを確認してください。

• Control Panel で組織に対するサードパーティアプリケーションの管理権限を持っていること。
• アプリケーションをホストする外部環境があること。

セットアップ

ステップ1：クライアント資格情報用の Developer Console アプリケーションをセットアップする

現在、OAuth クライアントは Developer Console アプリケーションとして作成します。新しい Developer Console アプリケーションを作成するに沿って作成ウィザードを進め、クライアント資格情報のセットアップでは次の選択を行います。

1. アプリケーションタイプページで、バックエンドサービスを選択します。
2. 権限ページで、アプリケーションの権限を選択します。この選択により、アプリケーションでクライアント資格情報の付与ワークフローが使用され、サービスユーザーが生成されます。
3. アプリケーションが作成されたら、クライアントIDを控え、クライアントシークレットをコピーします。シークレットが表示されるのはこのときだけです。
4. アプリケーションの作成後、事前に定義されたプロジェクトおよび操作の範囲を超えるアクセスが必要な場合は、［OAuth と制限］ページで制限なしに設定します。この設定は作成時には利用できません。アプリケーションの制限を設定するを参照してください。

ステップ2：サービスユーザーの影響を理解する

クライアント資格情報アプリケーションの場合、Foundry はアプリケーションの代理として動作するサービスユーザーを作成します。これにより、次の利点があります。

• ユーザーログインが不要： アプリケーションが表示する情報は個々のユーザーに限定されないため、サービスユーザーがすべての操作を処理します。
• サービスユーザー権限： デフォルトでは、サービスアカウントはどのリソースにもアクセスできません。クライアントが Foundry でアクションを実行できるようにするには、Foundry 管理者がサービスユーザーアカウントに必要なロールと権限を割り当てる必要があります。
• 認可の責任： ユーザーは個別にログインできないため、アプリケーションに認可ロジックを実装する必要があります。アプリケーションは、すべての操作に使用する単一のトークンを受け取ります。
• 権限管理： アプリケーションに必要な特定のプロジェクト、オブジェクトタイプ、データセットへのアクセスをサービスユーザーに付与します。

ステップ3：サービスユーザーの権限を設定する

アプリケーションの作成後、サービスユーザーに対して次の権限を設定します。

• プロジェクトへのアクセス： 必要なリソースを含むプロジェクトへのアクセスをサービスユーザーに付与します。
• オントロジータイプへのアクセス： 必要なオントロジータイプへのアクセスを付与します。サービスユーザーがアクションを実行できることを確認してください。
• データセットへのアクセス： 必要なデータセットへのアクセスを付与します。
• ロールの割り当て： 必要な API 操作を行える適切なロールを割り当てます。

ステップ4：オントロジー SDK アプリケーションの実装

TypeScript アプリケーションでは、オントロジー SDK を使用して、アプリケーション用のカスタム SDK ライブラリを生成します。詳細については、サーバー側 TypeScript アプリケーションのセットアップガイドを参照してください。

オントロジー SDK のセットアッププロセスは、次のステップで構成されます。

1. オントロジー SDK パッケージを作成する： Developer Console を使用してオントロジー SDK パッケージを生成します。
2. SDK にオントロジーリソースを追加する： アプリケーションがアクセスする必要のあるエンティティを、オントロジー SDK のリソースに追加します。
3. オントロジー SDK をインストールする： 生成されたオントロジー SDK パッケージをアプリケーションにインストールします。
4. 認証を設定する： オントロジー SDK の認証クライアントと OAuth クライアント資格情報を使用して Foundry にアクセスします。
5. データをクエリする： オントロジー SDK クライアントを使用して、サービスユーザーの権限でオントロジーデータをクエリします。

オントロジー SDK クライアントは、生の REST API 呼び出しと比較して、型安全性、自動シリアル化、および簡素化された API インタラクションを提供します。

ステップ5：アプリケーションへのアクセスを確認する

1. 認証を確認する： アプリケーションがアクセストークンを正常に取得できることを確認してください。
2. API 呼び出しをテストする： アプリケーションが必要な Foundry リソースにアクセスできることを確認します。

トラブルシューティング

認証の問題

• 無効なクライアント資格情報： クライアントIDとシークレットが正しいことを確認します。必要に応じて再生成し、シークレットが正しいことを確認します。
• スコープエラー： 要求したスコープがオントロジー SDK クライアントアプリケーションに付与されていることを確認してください。
• ネットワーク接続： ファイアウォールとネットワークポリシーを確認し、リクエストが Foundry に到達していることを確認します。

権限エラー

• 403 Forbidden： Developer Console でアプリケーションの権限を確認します。403 エラーは、ユーザーにアプリケーションを閲覧する権限がないことを意味します。
• リソースが見つかりません： ユーザーが閲覧できるはずのリソースにアクセスできない場合は、アプリケーションのサービスユーザーにそれらのリソースへのアクセス権があり、アプリケーションのオントロジーリソースに追加されていることを確認します。

これで、オントロジーの機能を活用できる、動作するクライアント資格情報アプリケーションができました。外部アプリケーションは、サービスユーザーの権限を通じて Foundry のデータと機能に安全にアクセスできるため、堅牢なバックエンド統合を備えた、スケーラブルな一般ユーザー向けアプリケーションを構築できます。