外部アプリケーション (OAuth)

UiPath 製品と外部アプリケーションとの連携に取り組む開発者は、スコープの変更管理、アクセス トークンと更新トークンの管理、外部アプリと UiPath リソースとの連携の維持などの作業を担当します。このガイドの以降では、これらの操作について説明します。

OAuth には、認証、認可、委任、および API 呼び出しのセキュリティ保護を簡素化するために利用できるライブラリの選択肢が用意されています。これらのリソースには、OAuth の公式 Web サイトから直接アクセスできます。

前提条件

開発者は、組織管理者が外部アプリケーションを UiPath に登録した後、UiPath リソースで外部アプリを認証するための、登録の詳細を取得する必要があります。

• アプリの種類とアプリ ID。機密アプリケーションを使用している場合は、アプリ シークレットも必要になります。これらを使用して、UiPath の Identity Server でアプリを認証します。Identity Server は OAuth 2.0 フレームワークに対応している、UiPath リソースにアクセスするための認可サーバーです。

• さらに、外部アプリの範囲も知っておく必要があります。範囲は、外部アプリがアクセスできる UiPath のリソースを定義するものです。これには、リソースの仕様 (アセット、プロセスなど) とアクセス許可レベル (読み取り、書き込み、編集など) の両方が含まれます。

外部アプリを認証および認可する

外部アプリケーションの登録後、適切な許可の種類を使用して、外部アプリケーションに対する適切な認可メカニズムを実装する必要があります。これによって外部アプリケーションはアクセス トークンを取得できるようになります。

このプロセスでは、外部アプリの範囲と登録済みアプリの資格情報、すなわちアプリ ID (機密アプリケーションの場合は、アプリ シークレット) を Identity Server に提供して、アクセス トークンを要求します。資格情報が有効な場合、Identity Server はアクセス トークンの生成に使用される認可コードを発行して応答します。

認可に使用する許可の種類

アプリケーションの種類	スコープ	必要な許可の種類
機密	アプリケーション	クライアント資格情報
機密	ユーザー	認可コード
機密	アプリケーションとユーザー	クライアント資格情報と認証コード
非機密	ユーザー	PKCE による認可コード

注:

Orchestrator のように、ユーザーとアプリケーションの両方のスコープが同名の場合、リソースがユーザー スコープまたはアプリケーション スコープのどちらで呼び出されるかは、使用する許可の種類によって決まります。

範囲の宣言

管理者がアプリケーションに対して定義した範囲によって、アプリケーションが得られる最大レベルのアクセス権が決まります。開発者がこの定義済みのスコープを超えるアクセス権を要求した場合、要求は失敗します。したがって、管理者が定義したスコープで要求することが重要です。

管理者レベルでは、アプリケーションのアクセス許可は以下のとおりです。

• 組織を対象範囲としたアクセス許可: 既定では、外部アプリケーションが登録されると、そのアプリケーションは範囲セットに従って組織全体のリソースにアクセスできます。

• きめ細かいアクセス許可: より詳細にアクセス許可を設定する場合は、組織管理者が Orchestrator 内のテナント レベルまたはフォルダー レベルで外部アプリにロールを割り当てることができます。ただし、それが可能なのは、機密アプリケーションの場合のみです。

開発者レベルでは、スコープの宣言は次のように行われます。

• 組織を対象範囲としたアクセス許可: トークン要求で OR.Machines.View のように範囲を明示的に指定して宣言すると、アプリケーションが組織全体のリソースへのアクセス許可を要求していることになります。
• きめ細かいアクセス許可: アプリケーションにきめ細かいアクセス権を付与するには、トークン要求で OR.Default を宣言する必要があります。OR.Default はワイルドカード範囲のように機能し、特定のテナントまたはフォルダーで割り当てられたロールに応じて、きめ細かいアクセス権をアプリケーションに付与します。

たとえば、アプリケーションに、すべてのマシンを表示するための組織全体のアクセス権と、定義済みのテナントおよびフォルダー内のより詳細なレベルでの排他的アクセス許可を付与するとします。その場合は、範囲を OR.Machines.View かつ OR.Default として宣言できます。この結合された宣言により、外部アプリケーションは、組織全体と、特定の Orchestrator テナントまたはフォルダーの両方で動作することができます。

必要なスコープの値を取得するには、リソースの API ドキュメントのエンドポイントを確認します。以下に例を示します。

アプリの範囲が指定された機密アプリ (クライアント資格情報フロー)

アプリケーションの範囲が指定された機密アプリケーションは、UiPath Identity Server に対してクライアント資格情報フローを実行します。

図は、OAuth のクライアント資格情報フローを示しています。クライアントが Identity Server に資格情報を送信し、アクセス トークンを受信します。クライアントは検証済みトークンを使用して API リソースにアクセスできます。

クライアントの資格情報を利用した OAuth フローについて詳しくは、RFC 6749 のドキュメントをご覧ください。

この種類の許可の場合、フローは次のようになります。

1. 外部アプリケーションは、client_id とclient_secret を含む POST 要求を Identity Server のトークン エンドポイント https://{yourDomain}/identity/connect/token に送信することで、アクセス トークンを要求します。

   grant_type=client_credentials&client_id={app_id}&client_secret={app_secret}&scope={scopes}

   フィールド	説明
   client_id	登録時にアプリケーションに割り当てられた一意の識別子を指定します。 アプリ ID (管理者から提供されたもの) を含む必要があります。
   client_secret	機密アプリケーションの登録時に提供される機密情報 (パスワードなど) を指定します。このフィールドは、Identity Server への要求が発行される際、client_id と共に、アプリケーションを認証するために使用されます。 アプリ シークレット (管理者から提供されたもの) を含む必要があります。
   scope	アプリケーションが要求する範囲を空白で区切って指定します (例: OR.Machines.View OR.Default)。 OR.Default を使用すると、特定のテナントまたはフォルダー内で、制御およびカスタマイズされたアクセス権を付与できます。アプリケーションが実際に得るアクセス許可は、管理者がアプリケーションを割り当てたテナントまたはフォルダーに基づいて決定されます。 特定のリソースに対する組織全体の広範なアクセス権を付与するには、OR.Machines.View のような明示的な範囲を使用します。

2. 外部アプリケーションが、下記のようなアクセス トークンを含む応答を受信します。

   {
       "access_token":"{access_token}",
       "expires_in":3600,
       "token_type":"Bearer",
       "scope":"{scopes}"
   }

   アプリケーションはアクセス トークンを使用して、その期限が切れるまで (1 時間) ユーザー リソースにアクセスできます。

ユーザーの範囲が指定された機密アプリ (認可コード フロー)

ユーザーの範囲が指定された機密外部アプリの場合は、Identity Server に対して認可コード フローを実行します。

図は、OAuth の認可コード フローを示しています。クライアントが Identity Server に認可を要求します。その後、ユーザーはログインを求められます。成功すると、Identity Server は認可コードを提供します。クライアントは、このコードとクライアント シークレットを使用してアクセス トークンを取得します。検証済みトークンを使用すると、API リソースにアクセスできるようになります。

認可コードを利用した OAuth フローについて詳しくは、RFC 6749 のドキュメントをご覧ください。

注: Postman や同様のツールを使用している場合は、コンテンツ タイプとして application/x-www-form-urlencoded を使用します。

1. 外部アプリケーションは、認可コードを取得するための認可要求を Identity Server の認可エンドポイント https://{yourDomain}/identity/connect/authorize? に送信します。

   response_type=code&acr_values={value}&client_id={app_id}&scope={scopes}&redirect_uri={redirect_url}

   オプション	説明
   acr_values	Identity Server に、ユーザーが属する組織に基づいた認証ポリシーを適用できるようにします。以下のさまざまな値を取ることができます。 acr_values=tenant:{target organization GlobalId} - 組織 ID は ACR 値として機能します。 acr_values=tenantName:{ターゲット組織名} - 組織名は ACR の値として機能します。
   client_id	登録時にアプリケーションに割り当てられた一意の識別子を指定します。 アプリ ID (管理者から提供されたもの) を含む必要があります。
   client_secret	機密アプリケーションの登録時に提供する機密情報 (パスワードなど) を指定します。このフィールドは、Identity Server への要求が発行される際に、client_id と共にアプリケーションを認証するために使用されます。 アプリ シークレット (管理者から提供されたもの) を含む必要があります。
   scope	アプリケーションが要求する範囲をスペースで区切って指定します (例: OR.Machines.View OR.Default)。 OR.Default を使用すると、特定のテナントまたはフォルダー内で、制御およびカスタマイズされたアクセス権を付与できます。アプリケーションが得るアクセス許可は、管理者がアプリケーションを割り当てたテナントまたはフォルダーに基づいて決定されます。 特定のリソースに対する組織全体の広範なアクセス権を付与するには、OR.Machines.View のような明示的な範囲を使用します。
   redirect_uri	認可コードの許可後に Identity Server が認可要求をリダイレクトする URL を指定します。

2. 認可要求を認証するには、ユーザーがログインする必要があります。

   次のような場合、要求は失敗します。

   • ユーザーが、外部アプリケーションが登録された組織に属していない場合
   • 一部のリソースで、ログインしたユーザーが要求のスコープに対して必要な権限を持っていない場合
3. 外部アプリケーションが認可コードを受信します。 認可コードは 1 回だけ使用できます。
   認可要求リダイレクトの例: {redirect_url}?code={authorization_code}&scope={scopes}
4. 外部アプリケーションが認可コードと認証の詳細情報 (client_id と client_secret) を使用して、UiPath® Identity Server からのアクセス トークンを要求します。これらは、トークン エンドポイント https://{yourDomain}/identity/connect/token への POST 要求の本文に含まれています。

   grant_type=authorization_code&code={authorization_code}&redirect_uri={redirect_url}&client_id={app_id}&client_secret={app_secret}

5. 外部アプリケーションが、下記のようなアクセス トークンを含む応答を受信します。

   {
       "access_token":"{access_token}",
       "expires_in":3600,
       "token_type":"Bearer",
       "scope":"{scopes}"
   }

アプリケーションはアクセス トークンを使用して、その期限が切れるまで (1 時間) ユーザー リソースにアクセスできます。

ユーザー スコープを持つ非機密アプリ (PKCE フローを使用した認可コード)

ユーザー スコープを持つ非機密アプリケーションの場合は、PKCE フローを使用して認可コードを実行します。PKCE の認可コードを利用する OAuth フローについて詳しくは、RFC 7636 のドキュメントをご覧ください。

この種類の許可の場合、フローは次のようになります。

1. 外部アプリケーションは認可リクエストを送信して、 https://{yourDomain}/identity/connect/authorize? エンドポイントへの認可コードを取得します。

   response_type=code&client_id={app_id}&scope={scopes}&redirect_uri={redirect_url}&code_challenge={cryptographically-random string from code_verifier}&code_challenge_method=S256

   オプション	説明
   client_id	登録時にアプリケーションに割り当てられた一意の識別子を指定します。 アプリ ID (管理者から提供されたもの) を含む必要があります。
   scope	アプリケーションが要求するスコープを空白で区切って指定します (例: OR.Machines.View)。
   redirect_uri	認可コードの許可後に UiPath Identity Server が認可要求をリダイレクトする URL を指定します。
   code_challenge_method	code_challenge の code_verifier のエンコードに使用するメソッドを指定します。このフィールドの値は S256 である必要があります。つまり、SHA256 を使用して code_verifier をハッシュし、base64url でエンコードして code_challenge を作成する必要があります。
   code_challenge	code_verifier から派生した、暗号化されたランダムな文字列で、認可要求をトークン要求に関連付けるために使用します。 code_challenge を生成するには、code_verifier のアルゴリズムを使用する必要があります。rfc7636 規格に準拠していれば、独自に作成することも可能です。

2. https://{identity_baseURL}/connect/token への POST トークン要求では、要求本文に code_verifier (code_challenge の生成に使用した元の文字列) を含める必要があります。

   grant_type=authorization_code&code={authorization_code}&redirect_uri={redirect_url}&client_id={app_id}&code_verifier={code_verifier}

   応答には、アプリケーションがユーザー リソースにアクセスするために使用できるアクセス トークンが含まれます。このトークンは期限が切れるまで (1 時間) 使用できます。

アクセス トークンを使用する

アクセス トークンを取得したアプリケーションは、期限が切れるまで (1 時間) そのトークンを使用して、選択されたスコープ内に限り、許可されたリソースにアクセスできます。

以下に、認可ヘッダーにアクセス トークンを使用した、odata/Machines API に対する要求の例を示します。アクセス トークンのスコープ要求には OR.Machines スコープが含まれます。

curl -X GET "https://{yourDomain}/odata/Machines"
  -H "Authorization: Bearer {access_token}" -H  "accept: application/json"

更新トークンを取得する

アクセス トークンの有効期限は 1 時間です。 外部アプリケーションは、更新トークンを交換することで、ユーザーの操作なしで新しいアクセス トークンを取得できます。 機密外部アプリケーションと非機密外部アプリケーションの両方が更新トークンを要求できます。 ただし、クライアント資格情報フローでは更新トークンはサポートされていません。 クライアント資格情報フローでは、アクセス トークンは更新トークンなしで直接付与されます。 クライアントが新しいトークンを必要とする場合は、資格情報を使用して再認証する必要があります。

更新トークンも 1 回の使用に対してのみ有効で、60 日後に期限が切れます。

トークンの更新を要求するには、認可要求のscope パラメーターにoffline_access を含めて、更新トークンを取得するためのトークン要求内で認可コードを使用できるようにする必要があります。

更新トークンを取得する

認可コードを含む POST 要求を以下のトークン エンドポイントに送信します。

https://{yourDomain}/identity/connect/token です。

注: Postman や同様のツールを使用している場合は、コンテンツ タイプとして application/x-www-form-urlencoded を使用します。

要求により、次のような新しいアクセス トークンと更新トークンが返されます。

{ 
    "access_token": "{access_token}", 
    "expires_in": 3600, 
    "token_type": "Bearer", 
    "refresh_token": "{refresh_token}", 
    "scope": "OR.Machines OR.Robots offline_access" 
}

新しい更新トークンと新しいアクセス トークンを取得する

付与タイプ refresh_token を使用して、POST 要求をトークン エンドポイント https://{yourDomain}/identity/connect/token に送信します。

注: Postman や同様のツールを使用している場合は、コンテンツ タイプとして application/x-www-form-urlencoded を使用します。

{
    "grant_type": "refresh_token",
    "client_id": "{app_id}",
    "client_secret": "{app_secret}",
    "refresh_token": "{existing_refresh_token}"
}

注: 外部アプリケーションが非機密でなおかつ PKCE による許可コードを使用している場合、要求本文から client_secret パラメーターを削除します。

要求により、新しいアクセス トークンと新しい更新トークンが返されます。

既存の更新トークンは使用後に無効になるため、受信した新しい更新トークンを使用していることを確認してください。

UiPath® Identity Server エンドポイント

Postman や同様のツールを使用している場合は、Identity Server エンドポイントへの要求にはすべて、コンテンツの種類 application/x-www-form-urlencoded を使用します。プログラムを使用して要求を行う場合は、これは必要ありません。

Identity Server レイヤー	エンドポイント	説明
Discovery	https://{yourDomain}/identity/.well-known/openid-configuration	このエンドポイントを使用すると、Identity Server インスタンスに関するメタデータが取得されます。
認可	https://{yourDomain}/identity/connect/authorize	このエンドポイントを使用すると、ブラウザーを介してトークンまたは認可コードが要求されます。このプロセスには、エンドユーザーの認証と、任意の同意が含まれます。
トークン	https://{yourDomain}/identity/connect/token	このエンドポイントを使用すると、プログラムを使ってトークンが要求されます。 このエンドポイントでは、コンテンツの種類を application/x-www-form-urlencoded にする必要がありますのでご注意ください。