以下の手順は、UiPath 製品と外部アプリケーションの連携を管理する開発者を対象としたものです。

👍

要件

はじめる前に

• Organization Administrator が Automation Cloud への外部アプリケーションの登録を完了している必要があります。
• Organization Administrator から登録の詳細情報を入手する必要があります。

各種の許可を使用する

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

Which authorization grant type to use:

📘

注:

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

The authorization server for accessing UiPath resources is the UiPath Identity Server, which supports the OAuth 2.0 framework.

Fine-grained access

For confidential applications with fine-grained access configured via Orchestrator, you need to request the OR.Default scope, which allows the application to check for assignments made in Orchestrator, at the tenant and folder levels. The application can then access the resources it's been granted access to in those tenants and folders.

For example, you want an external application to view jobs and machines across all tenants in the organization. By leveraging the fine-grained access functionality, you can also configure the application to view queues in one folder.

To get the access token for your external app in this scenario, you should request the following scopes: OR.Jobs.Read OR.Machines.Read OR.Default. This grants your app View permissions on Jobs and Machines across all tenants in the organization, and also View on Queues in the folder, provided that the external app has been assigned to it and granted the required permissions via a role.

認可コード

登録したアプリケーションの種類が機密で、要求のスコープがユーザー の場合、この種類の許可を使用します。

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

1. 外部アプリケーションは認可コードを取得するために、UiPath Identity Server 認可エンドポイントに認可要求を送信します。

https://cloud.uipath.com/identity_/connect/authorize?
response_type=code&
client_id={app_id}&
scope={scopes}&
redirect_uri={redirect_url}

• https://cloud.uipath.com/connect/authorize は、Identity Server の認可エンドポイントです。
• response_type=code は、アプリケーションが認可コードを要求していることを示します。
• client_id には、アプリケーション ID ([外部アプリケーション] ページに表示されます) を含める必要があります。
• scope には、アプリケーションが要求するスコープが空白で区切って列挙されます (例: OR.Machines OR.Robots)。
  Check the endpoint in the API documentation of the resource to get the scope values you need. For example:

• redirect_uri には、認可コードの許可後に UiPath Identity Server が認可要求をリダイレクトする URL が含まれます。

2. 認可要求を認証するには、ユーザーが Automation Cloud にログインする必要があります。
   次のような場合、要求は失敗します。

   • ユーザーが、外部アプリケーションが登録された組織に属していない場合
   • 一部のリソースで、ログインしたユーザーが要求のスコープに対して必要な権限を持っていない場合

3. 外部アプリケーションが認可コードを受信します。
   認可要求リダイレクトの例: {redirect_url}?code={authorization_code}&scope={scopes}
   認可コードは 1 回だけ使用できます。

4. 外部アプリケーションが認可コードと認証の詳細情報 (client_id と client_secret) を使用して、UiPath Identity Server からのアクセス トークンを要求します。これらは、トークン エンドポイント https://cloud.uipath.com/identity_/connect/token への POST 要求の本文に含まれています。
   Postman や同様のツールを使用している場合は、コンテンツの種類 application/x-www-form-urlencoded を使用します。

{
    "grant_type": "authorization_code",
    "code": "{authorization_code}",
    "redirect_uri": "{redirect_url}",
    "client_id": "{app_id}",
    "client_secret": "{app_secret}"
}

📘

注:

Automation Cloud に機密アプリケーションを登録すると、client_secret が返されます。
非機密アプリケーションの場合は、client_secret の代わりに、code_challenge と code_challenge_method を使用します。

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

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

Now the application can use the access token to access user resources until the token expires (one hour). See Using the Access Token and Obtaining a Refresh Token for more information.

PKCE による認可コード

登録したアプリケーションの種類が非機密で、要求のスコープがユーザーの場合、この許可の種類を使用します。

The flow is the same as when using authorization code, except in the authorize request you need to include the following request query parameters:

• code_challenge_method。S256 に設定する必要があります。
• code_challenge。code_verifier から派生した、暗号化されたランダムな文字列で、認可要求をトークン要求に関連付けるために使用します。

You must use a code verifier algorithm to generate the code challenge. You can also create your own, as long as it complies with the rfc7636 standard.

https://cloud.uipath.com/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

https://cloud.uipath.com/identity_/connect/token への POST トークン要求では、要求本文に code_verifier (code_challenge の生成に使用した元の文字列) を含める必要があります。
Postman や同様のツールを使用している場合は、コンテンツの種類 application/x-www-form-urlencoded を使用します。

{ 
    "grant_type": "authorization_code", 
    "code": "{authorization_code}", 
    "redirect_uri": "{redirect_url}", 
    "client_id": "{app_id}", 
    "code_verifier": "{code_verifier}" 
}

The response includes an access token which the application can use to access user resources until the token expires (one hour). See Using the Access Token and Obtaining a Refresh Token for more information.

クライアント資格情報

機密アプリケーションがアプリケーション スコープにアクセスする場合、外部アプリケーションは client_id と client_secret を含む POST 要求を Identity Server のトークン エンドポイント https://cloud.uipath.com/identity_/connect/token に送信することで、アクセス トークンを要求します。
Postman や同様のツールを使用している場合は、コンテンツの種類 application/x-www-form-urlencoded を使用します。

{
    "grant_type": "client_credentials",
    "client_id": "{app_id}",
    "client_secret": "{app_secret}",
    "scope": "{scopes}"
}

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

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

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

curl -X GET "https://cloud.uipath.com/{org_name}/{tenant_name}/orchestrator_/odata/Machines"
  -H "Authorization: Bearer {access_token}" -H  "accept: application/json"l

See the Orchestrator API Swagger at https://cloud.uipath.com/{org_name}/{tenant_name}/orchestrator_/swagger/index.htm for information about the available APIs.

更新トークンを取得する

アクセス トークンは 1 時間で期限が切れます。外部アプリケーションは、更新トークンを交換することで、ユーザーの操作なしで新しいアクセス トークンを取得できます。更新トークンは、機密および非機密のどちらの外部アプリケーションでも要求できます。
更新トークンも 1 回の使用に対してのみ有効で、60 日後に期限が切れます。

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

更新トークンを取得する

認可コードを含む POST 要求を以下のトークン エンドポイントに送信します。
https://cloud.uipath.com/identity_/connect/token です。
If you are using Postman or a similar tool, use the content type 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://cloud.uipath.com/identity_/connect/token に送信します。
If you are using Postman or a similar tool, use the content type 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 を使用します。プログラムを使用して要求を行う場合は、これは必要ありません。

ディスカバリ:
https://cloud.uipath.com/identity_/.well-known/openid-configuration

認可
https://cloud.uipath.com/identity_/connect/authorize

トークン:
https://cloud.uipath.com/identity_/connect/token