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

👍

要件

はじめる前に

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

Using the different grant types

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

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.

認可コード

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

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

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.

Authorization code with PCKE

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

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}"
}

Using the access token

アクセス トークンを取得したアプリケーションは、期限が切れるまで (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.

Obtaining a refresh token

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

To request a refresh token, you must include offline_access in the scope parameter of the authorize request so that the authorization code can be used in a token request to get a 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.

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

{ 
    "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 endpoints

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