外部アプリケーションで認証する

外部アプリケーションは、UiPath Cloud の [管理] > [外部 Apps ] で構成され、認証に OAuth 2.0 を使用します。複数の認証シナリオがサポートされています。

• ユーザー ログイン不要の無人または自動アクセス (クライアント資格情報の付与)
• Copilot Studio や ChatGPT (認可コードの付与) など、独自の OAuth フローを実行するサードパーティの連携
• クライアント シークレットを安全に保存できないデスクトップ アプリまたはモバイル アプリ (PKCE による認可コードの付与)

外部アプリケーションの種類を理解する

外部アプリケーションを作成するときは、認証の仕組みを決定する 2 つの選択を行います。

• アプリが 機密 か 非機密か。
• アプリケーション スコープとユーザー スコープのどちらを使用するか。

機密アプリと非機密アプリ

	機密	非機密
クライアント シークレット	作成時に生成されます。安全に保管する必要があります。	未生成
認証者	アプリ自体 (ユーザー不要)、またはアプリを介したユーザー	アプリ経由でユーザーのみ
UI のスコープ タブ	アプリケーション スコープ と ユーザー スコープ	ユーザー スコープ のみ

機密アプリは、バックエンド、サーバー、CI/CD パイプライン用にシークレットを安全に保存できる場合に使用します。

デスクトップ アプリ、モバイル アプリ、またはシークレットを安全に保つことができないブラウザーベースのシングルページ アプリには、 非機密 アプリを使用します。非機密アプリには PKCE が必要です。

アプリケーション スコープとユーザー スコープ

The two tabs in the External Apps UI map to fundamentally different OAuth flows:

	アプリケーション スコープ	ユーザー - スコープ
OAuth grant type	クライアント資格情報 (client_credentials)	認証コード (authorization_code)
Identity	アプリ自体	アプリを介してログインする人間のユーザー
トークン sub 要求	アプリの client_id	ユーザーの ID
トークン sub_type 要求	service.external	user
MCP サーバーの見方	UserType.ExternalApp	UserType.User
ユーザー ログインが必要	いいえ	はい、ブラウザーは UiPath のログインにリダイレクトします。
Integration Service アクティビティ	サポート対象外 (ユーザー コンテキストなし)	サポート済み (ユーザー コンテキストの存在)
フォルダーのアクセス	アプリはフォルダーに明示的に割り当てられる必要がある	ユーザーは、フォルダーで適切なロールを持っている必要があります。アプリは、アプリケーション スコープも持っている場合にのみフォルダーに割り当てることができます。ユーザー スコープのみのアプリはフォルダー割り当てできません
利用可能	機密アプリのみ	機密と非機密の両方

外部アプリケーションを保存すると、Identity Server は、設定したスコープの種類に基づいて、クライアントが使用できる許可の種類を設定します。

• アプリケーション スコープ → client_credentials のみ許可されます
• ユーザー スコープ → authorization_code のみが許可されます
• 両方→両方が許可されます

https://cloud.uipath.com/identity_/connect/tokenにトークンを手動で要求する場合は、すべてのトークン要求でgrant_typeを明示的に指定する必要があります。省略するとエラーが返されます。クライアントに許可されていない許可タイプの送信も失敗します。

アプリケーション スコープの認証を設定する

アプリケーション スコープでは、クライアント資格情報の付与を使用します。これは、ユーザーの操作なしで機能する唯一の認証方法です。

重要:

Integration Service のコネクタを公開する UiPath MCP サーバーにクライアント資格情報でアクセスすると、サーバーが失敗します。Integration Service でサポートされるツールの場合は、代わりに ユーザー スコープ認証 を使用します。

前提条件

• UiPath では、[ 管理] > [外部 Apps ] にアクセスできます。
• フォルダーへのアクセス権は Orchestrator で管理できます。

外部アプリケーションを作成する

1. UiPath に移動し、[ 管理]、[ External Apps] の順に選択します。

2. [アプリケーションを追加] を選択します。

3. アプリの名前を入力し、アプリの種類は [機密 ] のままにします。

4. [ アプリケーション スコープ] タブを選択します。

   重要:

   スコープを [ユーザー スコープ] タブではなく [アプリケーション スコープ] タブに追加します。

5. 次のスコープを追加します。

   • OR.Execution: ツールを一覧表示するために必要です。MCP サーバーは、 Orchestrator ListReleases API を呼び出して、 tools/listを処理するときにプロセスのメタデータを取得し、そのエンドポイントは OR.Executionで承認されます。
   • OR.Jobs: ツールの実行に必要です。プロセスをツール (UiPath、Coded、Command) として実行するすべての種類の MCP サーバーは、OR.Jobsで認可された Orchestrator StartJobs API を呼び出します。

6. [ 追加] を選択し、[ クライアント ID ] と [ クライアント シークレット] をコピーします。

外部アプリをフォルダーに割り当てます

1. Orchestrator で、[ テナント] > [アクセス権を管理] に移動するか、特定のフォルダーのアクセス権設定に移動します。

2. 外部アプリを Automation User ロールで追加します。

   このロールには、MCP サーバーにアクセスするために必要な MCPServers.View 権限が含まれます。

外部アプリを使用して認証する

Orchestrator での権限の解決方法に応じて、以下のいずれかのオプションを選択します。

オプション A: OR.Default のみ (分かりやすくするために推奨)

トークンには、明示的な API レベルのスコープはありません。Orchestrator は、各フォルダー内で外部アプリに割り当てられたロールを通じて権限を解決します。クロスフォルダー API 呼び出しは、フォルダー キーのヘッダーなしで機能します。このオプションを使用するには、外部アプリが対象のフォルダーで Automation User ロールを持っている必要があります。

uipath auth --client-id "<your-client-id>" \
  --client-secret "<your-client-secret>" \
  --base-url "https://cloud.uipath.com/{org}/{tenant}" \
  --scope "OR.Default"

オプション B: 明示的なスコープ

トークンは、明示的な OR.Execution と OR.Jobs 範囲の要求を保持します。Orchestrator は、これらのスコープを各 API 呼び出しで直接検証します。このオプションには X-UIPATH-FolderKey ヘッダーが必要ですが、MCP サーバーはこれを自動的に処理します。

uipath auth --client-id "<your-client-id>" \
  --client-secret "<your-client-secret>" \
  --base-url "https://cloud.uipath.com/{org}/{tenant}" \
  --scope "OR.Default OR.Execution OR.Jobs"

結果

CLI は、MCP サーバー要求の Authorization ヘッダーで使用できるアクセス トークンを取得します。

範囲の組み合わせを理解する

OR.Default 、外部 Apps の UI で設定するスコープではありません。これは、トークンを要求するときに --scope パラメーターに含める特別なスコープです。要求するスコープによって、Orchestrator が権限を解決する方法と、MCP サーバーが API 呼び出しをルーティングする方法が決まります。

MCP フローには、異なるスコープを必要とする 2 つの Orchestrator API 呼び出しが含まれます。

• tools/list:MCP サーバーは odata/Releases/ListReleases を呼び出してプロセスメタデータを取得します。Releases コントローラーには OR.Executionが必要です。
• tools/call:MCPサーバーは odata/Jobs/StartJobs を呼び出してプロセスを実行します。ジョブ コントローラーには OR.Jobsが必要です。

以下の表は、さまざまなスコープの組み合わせがどのように動作するかをまとめたものです。

トークン要求時のスコープ	Orchestrator の権限の解決	X-UIPATH-FolderKey ヘッダー	MCP サーバーの動作
OR.Default だけ	フォルダー レベルのロールの割り当て (例: ターゲット フォルダーの Automation User)	必須ではない	単一のフォルダー間 API 呼び出し
特定の範囲のみ (例: OR.Execution OR.Jobs	トークン内の明示的なスコープ要求	すべての API 呼び出しで必要です	フォルダーごとの API 呼び出し (フォルダーごとにグループ化)
OR.Default さらに特定の範囲	明示的な範囲の主張 (特定の範囲が優先)	すべての API 呼び出しで必要です	フォルダーごとの API 呼び出し (フォルダーごとにグループ化)

動作に関する注意事項:

• OR.Defaultのみをリクエストするのが最も簡単な設定です。Orchestrator は、各フォルダーで外部アプリが割り当てられているロールを確認します。Automation User ロールは、リリースとジョブの両方のアクセス権をカバーします。
• OR.Execution や OR.Jobs などの特定の範囲 (OR.Defaultの有無を問わない) を追加すると、フォルダーの解決の仕組みが変わります。Orchestrator はスコープ要求とフォルダー ロールの権限の両方を確認し、いずれかに合格するとアクセス権が付与されます。そのためには、すべての API 呼び出しに X-UIPATH-FolderKey ヘッダーが必要です。MCP サーバーは、トークンの範囲を検出し、必要に応じてフォルダーごとに呼び出しを行うことで、これを自動的に処理します。
• OR.Defaultを使用しない場合、特定のOR.* スコープによってフォルダー レベルのロール解決がバイパスされ、テナント内のすべてのフォルダーにアクセス許可が付与されます。X-UIPATH-FolderKey ヘッダーは API ルーティングに引き続き必要です。

既知の制限事項: GetFoldersForCurrentUser

クライアント資格情報 (uipath run) を使用して MCP サーバーをローカルで実行する場合、Python SDK は orchestrator_/api/FoldersNavigation/GetFoldersForCurrentUser を呼び出してフォルダー パスをフォルダー キーに解決します。この API はクライアント資格情報の認証をサポートしていないため、対話型のユーザー トークンが必要です。

これを回避するには、 UIPATH_FOLDER_KEY 環境変数を直接設定します。この変数を設定すると、SDK は GetFoldersForCurrentUser 呼び出しを完全にスキップします。

export UIPATH_FOLDER_KEY="<folder-guid>"
uipath run mcp-server

フォルダー GUID は、Orchestrator API またはフォルダー URL で確認できます。

よくある間違い: マシンの資格情報と外部アプリ

外部アプリケーションの資格情報の代わりに ( Orchestrator の> マシンの) マシン資格情報を使用すると、 invalid_scope エラーが返されます。マシンの資格情報はロボット認証用であり、API アクセス用ではありません。

表示される場合:

{"error":"invalid_scope","error_description":"..."}

Orchestrator > マシンの資格情報ではなく、Admin > External Appsの資格情報を使用していることを確認します。

ユーザー スコープの認証を設定する

ユーザー スコープでは、認可コードの付与を使用します。ユーザーは外部アプリを通じてログインする必要があり、トークンはアプリの ID ではなくユーザーの ID を運びます。

ユーザー スコープの認証は、以下の場合に使用します。

• MCP サーバーは、Integration Service アクティビティ (コネクタ) によってサポートされるツールを公開します。
• 独自の OAuth フローを実行するサードパーティ クライアント (Copilot、Studio、ChatGPT) と連携している。
• ユーザーごとの ID が必要であり、どのアプリが呼び出しているかではなく、ログインしたユーザーに基づくアクセス制御が必要です。

前提条件

• UiPath では、[ 管理] > [外部 Apps ] にアクセスできます。
• フォルダーへのアクセス権は Orchestrator で管理できます。
• クライアント アプリケーションのリダイレクト URL がわかっている。

外部アプリケーションを作成する

1. UiPath に移動し、[ 管理]、[ External Apps] の順に選択します。

2. [アプリケーションを追加] を選択します。

3. アプリの名前を入力し、アプリの種類は [機密 ] のままにします。

4. [ ユーザー スコープ] タブを選択します。

   重要:

   スコープを [アプリケーション スコープ] タブではなく [ユーザー スコープ] タブに追加します。

5. 次のスコープを追加します。

   • OR.Execution: ツールを一覧表示するために必要です。
   • OR.Jobs: ツール (コード化されたサーバーまたはコマンド サーバー) を実行するために必要です。

6. リダイレクト URL を追加します。これは、ログイン後にユーザーのブラウザーが送信されるアドレスです。クライアント アプリケーションから提供されたコールバック URL を使用します。

   Copilot Studio では、最初にダミーの URL を使用し、コネクションが作成された後に更新します。

7. [ 追加] を選択し、[ クライアント ID ] と [ クライアント シークレット] をコピーします。

フォルダーへのアクセス権を設定する

上記で作成した外部アプリにはユーザー スコープしかないため、[ アクセス権を管理] のフォルダーに割り当てることはできません。フォルダーへのアクセス権は、ユーザーのロールによって付与されます。トークンは、アプリではなくユーザーの権限を継承します。

1. Orchestrator で、[ テナント] > [アクセス権を管理] に移動するか、特定のフォルダーのアクセス権設定に移動します。

2. ログインするユーザーに Automation User、 Automation Developer、または Folder Administrator のロールを割り当てます。

   このロールは、ユーザーがフォルダーで実行できる操作を決定し、MCP サーバーにアクセスするために必要な MCPServers.View 権限を含める必要があります。

外部アプリにもアプリケーション スコープが定義されている場合は、アプリ自体を Automation User ロールでフォルダーに追加で割り当てることができます。これは、ユーザー ログインを伴わないクライアント資格情報フローでのみ必要です。

認可コード フローを実行します

クライアント アプリケーションがフローを開始します。

1. ユーザーを認可エンドポイントにリダイレクトします。

   GET https://cloud.uipath.com/identity_/connect/authorize
     ?client_id=<your-client-id>
     &response_type=code
     &redirect_uri=<your-callback-url>
     &scope=OR.Default
   

2. ユーザーはブラウザーからログインし、 code パラメーターを指定してコールバック URL にリダイレクトされます。

3. サーバー側アプリケーションからトークンの認可コードを交換します。

   POST https://cloud.uipath.com/identity_/connect/token
     Content-Type: application/x-www-form-urlencoded
   
     client_id=<your-client-id>
     &client_secret=<your-client-secret>
     &grant_type=authorization_code
     &code=<authorization-code>
     &redirect_uri=<your-callback-url>
   

結果の

トークンエンドポイントは、MCP サーバー要求の Authorization ヘッダーで使用できるアクセストークンを返します。

バリアント: PKCE を使用する非機密アプリ

同じフローは、非機密の外部アプリでも機能します。相違点の概要を以下に示します。

	機密	非機密
クライアント シークレット	トークン交換に含まれるもの	使用しない (シークレットが存在しない)
PKCE	任意です。	必須です。
フォルダーの割り当て	アプリは、アプリケーション スコープも定義されている場合にのみフォルダーに割り当てることができます。ユーザー スコープのみの場合、アプリは [ アクセス権を管理 ] に表示されず、ユーザーのフォルダー ロールのみが適用されます	アプリにアプリケーション スコープを設定することはできず、[ アクセス権を管理] には表示されません。ユーザーのフォルダー ロールのみが適用されます
UI で作成	[機密] を選択します	[非機密] を選択します

このバリアントを使用するには、以下の手順を実行します。

1. 外部アプリケーションを作成する際は、[機密] ではなく [非機密] を選択します。[ ユーザー スコープ] タブのみを使用できます。OR.Executionを追加し、コード化されたサーバーまたはコマンド サーバーのOR.Jobsを追加し、リダイレクト URL を追加します。

2. 適切なロールを持つフォルダーには、アプリではないユーザーのみを割り当てます。

3. 次の PKCE ベースの認可フローを使用します。

   # 1. Generate PKCE code verifier and challenge
   code_verifier = <random 64-byte base64url string>
   code_challenge = BASE64URL(SHA256(code_verifier))
   
   # 2. Redirect user to authorize (with PKCE challenge)
   GET https://cloud.uipath.com/identity_/connect/authorize
     ?client_id=<your-client-id>
     &response_type=code
     &redirect_uri=<your-callback-url>
     &scope=OR.Default
     &code_challenge=<code_challenge>
     &code_challenge_method=S256
   
   # 3. Exchange the code for a token (no client_secret; include code_verifier)
   POST https://cloud.uipath.com/identity_/connect/token
     Content-Type: application/x-www-form-urlencoded
   
     client_id=<your-client-id>
     &grant_type=authorization_code
     &code=<authorization-code>
     &redirect_uri=<your-callback-url>
     &code_verifier=<code_verifier>
   

生成されるトークンは、機密ユーザー スコープ トークンと同じです。 sub がユーザー GUID、 sub_type が user、対象ユーザーが UiPath.Orchestratorです。MCP サーバーは、機密バリアントと同じように扱います。

トークンの特性 (ユーザー スコープ)

これらの特性は、認可コード フローを使用する機密アプリと非機密アプリの両方に適用されます。

• sub がユーザーの GUID に設定され、sub_type が userに設定された JWT 。
• 聴衆: UiPath.Orchestrator。
• MCPサーバーはトークンをユーザーIDとして解決します—MCPサーバーレイヤーでは、トークンは対話型ログインと同じコードパスに従います。
• フォルダー キーのルーティングは適用されません (フォルダー間の単一の Orchestrator 呼び出し)。
• Integration Service アクティビティは動作します (ユーザー コンテキストが存在します)。
• 更新トークン: scope パラメーターに offline_access が含まれている場合に返されます。それなしでは戻ってきません。更新トークンの有効期間は 60 日です。

Copilot Studio を UiPath MCP サーバーに接続する

OAuth 2.0 の手動認証を使用して Microsoft Copilot Studio エージェントを UiPath MCP サーバーに接続するには、以下の手順を使用します。

前提条件

• 外部アプリケーションを管理できます。
• フォルダーへのアクセス権は Orchestrator で管理できます。
• コネクションは Copilot Studio で設定できます。

手順

1. UiPath で、[ 管理] > [外部 Apps ] に移動し、[ アプリケーションを追加] を選択します。

2. アプリの種類を [機密] に設定します。

3. [リソース] で、OR.Execution スコープを設定した Orchestrator API アクセスを追加し、アプリケーション スコープとユーザー スコープの両方として追加します。

   MCP サーバーがコード化またはコマンド タイプの場合は、両方のスコープの下に OR.Jobs も追加します。

   [ アプリケーション スコープ ] タブにスコープを追加すると、手順 6 が機能します。ユーザー スコープのみを持つアプリを [アクセス権を管理] のフォルダーに割り当てることはできません。

4. ここでは、ダミーのリダイレクト URL を入力します (例: https://cloud.uipath.com)。

5. アプリケーションを保存し、[ クライアント ID ] と [ クライアント シークレット] をコピーします。

6. Orchestrator で、 Automation User ロールを持つ MCP サーバーを含むフォルダーに外部アプリを割り当てます。これは、手順 3 でアプリにアプリケーション スコープが与えられているためです。ユーザー スコープのみのアプリをフォルダーに割り当てることはできません。また、テナント ロール Allow to be Automation User を割り当てます。

7. Copilot Studio で、以下の値を使用して、 OAuth 2.0 手動 認証で MCP サーバーの URL を追加します。

   • クライアント ID: 手順 5 でコピーした値。
   • クライアント シークレット: 手順 5 でコピーした値
   • 認可 URL: https://cloud.uipath.com/identity_/connect/authorize
   • トークン URL: https://cloud.uipath.com/identity_/connect/token
   • 更新 URL: https://cloud.uipath.com/identity_/connect/token
   • 範囲: OR.Default

8. Copilot Studio で [ 作成 ] を選択します。Copilot Studio によってリダイレクト URL が生成されます。作成前はフィールドは灰色表示されます。

9. 生成されたリダイレクト URL をコピーして、[UiPath 管理] > [外部 Apps] の外部アプリのリダイレクト URL に追加します。

10. Copilot Studio に戻り、[ 接続] を選択します。

結果

Copilot Studio が UiPath MCP サーバーに接続されます。エージェントが MCP ツールにアクセスすると、ユーザーは OAuth フローを介してログインします。

ChatGPT を UiPath MCP サーバーに接続する

この手順は、動的クライアント登録 (DCR) が機能しない新規または未公開の ChatGPT アプリに使用します。

ChatGPT は、リダイレクト URI を /connector_platform_oauth_redirect から /connector/oauth/{callback_id}に変更しました。既に公開されているアプリは、引き続き DCR で動作します。新規または未公開のアプリでは、OAuth を手動で設定する必要があります。

前提条件

• 外部アプリケーションを管理できます。
• ChatGPT でアプリを作成できます。

ChatGPT からコールバック URL を取得します

1. ChatGPT に移動し、プロフィールを選択してから、[ Apps]、[ アプリの作成] の順に選択します。
2. UiPath のアプリ名、説明、MCP サーバー URL を入力します。
3. [ 詳細設定] を選択します。
4. [登録方法] で、[DCR] から [ユーザー定義の OAuth クライアント] に変更します。
5. コールバック URL (https://chatgpt.com/connector/oauth/{callback_id}) をコピーします。
6. このブラウザー タブは開いたままにします。

UiPath で外部アプリケーションを作成します

1. [管理] > [外部Apps] に移動し、[アプリケーションを追加] を選択します。

2. アプリの種類として [ 機密 ] を選択します。

3. [アプリケーション スコープ] タブと [ユーザー スコープ] タブの両方に [OR.Execution]、[OR.Jobs]、[OR.Folders] を追加します。

   [ アプリケーション スコープ ] タブにスコープを追加すると、次の手順 (フォルダーの割り当て) が機能します。ユーザー スコープのみを持つアプリを [アクセス権を管理] のフォルダーに割り当てることはできません。

4. [リダイレクト URL] フィールドに、ChatGPT からコピーしたコールバック URL を貼り付けます。

5. アプリケーションを保存し、[ クライアント ID ] と [ クライアント シークレット] をコピーします。

外部アプリをフォルダーに割り当てます

1. Orchestrator で、MCP サーバーを含むフォルダーを開きます。
2. [ アクセス権を管理] > [割り当て] に移動します。
3. 外部アプリを Automation User ロールで追加します。

ChatGPT を構成する

1. ChatGPT ブラウザー タブに戻ります。
2. 外部アプリからコピーした OAuth クライアント ID と クライアント シークレット を入力します。
3. [クライアント登録] > [トークン エンドポイントの認証方法] で [認証client_secret_basic] を選択します。
4. [ スコープ] > [既定のスコープ] で、既存の既定のスコープを非アクティブ化します。
5. [ スコープ] > [ベース スコープ] で、 OR.Defaultを追加します。
6. [作成] を選択します。

結果

ChatGPT が UiPath MCP サーバーに接続されている。ユーザーは、アプリが MCP ツールにアクセスするときに、手動 OAuth フローを介して認証します。

ORの動作。既定

OR.Default はアプリケーション スコープ フローとユーザー スコープ フローの両方で参照されますが、各コンテキストで動作が異なります。

Context	動作
アプリケーション スコープ (トークン要求時の --scope パラメーター)	Orchestrator が権限を解決する方法を制御します。OR.Defaultが唯一のスコープである場合、Orchestrator では明示的なスコープ要求の代わりにフォルダー ロールの割り当てが使用されます。「 範囲の組み合わせを理解する」をご覧ください。
認可要求の scope パラメーターのユーザー スコープ	認可要求のスコープ パラメーターとして使用されます。Orchestrator レベルでは、権限の少ない認証モードが有効化され、スコープ チェックまたはユーザーのフォルダー ロールの権限のいずれかに合格した場合にアクセス権が付与されます。MCP サーバーは、ユーザースコープのトークンに OR.Default を使用せず、トークンが保持するスコープに関係なく、常に単一のクロスフォルダー呼び出しを行います。

どちらの場合も OR.Default 外部Appsの UI で設定する範囲ではありません。トークン要求時または認可要求時にのみスコープ パラメーターに表示されます。