orchestrator

2022.10

false

重要 :

このコンテンツの一部は機械翻訳によって処理されており、完全な翻訳を保証するものではありません。新しいコンテンツの翻訳は、およそ 1 ～ 2 週間で公開されます。

Orchestrator API ガイド

デリバリー:

最終更新日時 2025年2月13日

外部アプリケーション (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 リソースにアクセスできます。 docs image

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

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

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

 grant_type=client_credentials&client_id={app_id}&client_secret={app_secret}&scope={scopes}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` のような明示的な範囲を使用します。

外部アプリケーションが、下記のようなアクセストークンを含む応答を受信します。
```
 {
    "access_token":"{access_token}",
    "expires_in":3600,
    "token_type":"Bearer",
    "scope":"{scopes}"
}{
    "access_token":"{access_token}",
    "expires_in":3600,
    "token_type":"Bearer",
    "scope":"{scopes}"
}
```
アプリケーションはアクセストークンを使用して、その期限が切れるまで (1 時間) ユーザーリソースにアクセスできます。

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

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

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

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

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

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

 response_type=code&acr_values={value}&client_id={app_id}&scope={scopes}&redirect_uri={redirect_url}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 を指定します。

認可要求を認証するには、ユーザーがログインする必要があります。
次のような場合、要求は失敗します。
- ユーザーが、外部アプリケーションが登録された組織に属していない場合
- 一部のリソースで、ログインしたユーザーが要求のスコープに対して必要な権限を持っていない場合
外部アプリケーションが認可コードを受信します。認可コードは 1 回だけ使用できます。

認可要求リダイレクトの例: {redirect_url}?code={authorization_code}&scope={scopes}
外部アプリケーションが認可コードと認証の詳細情報 (client_id と client_secret) を使用して、UiPath® Identity Server からのアクセストークンを要求します。これらは、トークンエンドポイント https://{yourDomain}/{organizationName}/identity/connect/token への POST 要求の本文に含まれています。
```
 grant_type=authorization_code&code={authorization_code}&redirect_uri={redirect_url}&client_id={app_id}&client_secret={app_secret}grant_type=authorization_code&code={authorization_code}&redirect_uri={redirect_url}&client_id={app_id}&client_secret={app_secret}
```

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

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

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

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

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

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

外部アプリケーションは認可リクエストを送信して、 https://{yourDomain}/{organizationName}/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=S256response_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 規格に準拠していれば、独自に作成することも可能です。

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}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"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}/{organizationName}/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" 
}{ 
    "access_token": "{access_token}", 
    "expires_in": 3600, 
    "token_type": "Bearer", 
    "refresh_token": "{refresh_token}", 
    "scope": "OR.Machines OR.Robots offline_access" 
}

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

refresh_token 許可の種類を使用して、 https://{yourDomain}/{organizationName}/identity/connect/tokenトークンエンドポイントにPOST要求を送信します。

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

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