Orchestrator
v2023.4
偽
バナーの背景画像
Orchestrator API ガイド
最終更新日 2023年11月10日

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

以下の手順は、OAuth フレームワークに基づいて UiPath の機能を使用し、UiPath 製品と外部アプリケーションとの連携を管理する開発者を対象としています。

ヒント:

はじめる前に

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

各種の許可を使用する

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

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

アプリケーションの種類

スコープ

必要な許可の種類

機密

ユーザー

認可コード

機密

アプリケーション

クライアント資格情報

非機密

ユーザー

PKCE による認可コード

注:

機密アプリケーションをユーザーとアプリケーションの両方のスコープに対して許可した場合、両方の種類の許可を実装する必要があります。

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

UiPath リソースにアクセスするための認可サーバーは UiPath Identity Server であり、OAuth 2.0 フレームワークに対応しています。

きめ細かいアクセス権

Orchestrator を使用してきめ細かいアクセス権が設定された機密アプリケーションの場合は、OR.Default スコープを要求する必要があります。これにより、アプリケーションは Orchestrator で行われた割り当てをテナント レベルおよびフォルダー レベルで確認できます。その後、アプリケーションは、そのテナントおよびフォルダー内の、アクセス権が付与されているリソースにアクセスできます。

たとえば、外部アプリケーションで組織内のすべてのテナントのジョブとマシンを表示するとします。この場合、きめ細かいアクセス権機能を利用すると、キューを 1 つのフォルダー内に表示するようにアプリケーションを設定することもできます。

このシナリオで外部アプリのアクセス トークンを取得するには、スコープ OR.Jobs.Read, OR.Machines.Read, OR.Default を要求する必要があります。これにより、組織内のすべてのテナントのジョブとマシンに対する表示権限に加え、フォルダー内のキューに対する表示権限もアプリに付与されます。ただし、外部アプリにそのフォルダーが割り当てられていて、ロールによって必要な権限が付与されていることが条件です。

認可コード

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

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

  1. 外部アプリケーションは認可コードを取得するために、UiPath Identity Server 認可エンドポイントに認可要求を送信します。
    https://{yourDomain}/identity/connect/authorize?
response_type=code&
acr_values={value}&
client_id={app_id}&
scope={scopes}&
redirect_uri={redirect_url}https://{yourDomain}/identity/connect/authorize?
response_type=code&
acr_values={value}&
client_id={app_id}&
scope={scopes}&
redirect_uri={redirect_url}
    オプション説明
    https://{yourDomain}/identity/connect/authorizeIdentity Server の認可エンドポイントです。
    response_type=codeアプリケーションが認可コードを要求していることを示します。
    acr_valuesIdentity Server に、ユーザーが属する組織に基づいた認証ポリシーを適用できるようにします。以下のさまざまな値を取ることができます。
    • acr_values=tenant:{target organization GlobalId} - ACR 値として機能する組織 ID です。
    • acr_values=tenantName:{target organization name} - ACR 値として機能する組織名です。
    client_idアプリケーション ID ([外部アプリケーション] ページに表示されます) を含める必要があります。
    scopeアプリケーションが要求する範囲が空白で区切って列挙されます (例: OR.Machines OR.Robots)。
    注: 必要なスコープの値を取得するには、リソースの API ドキュメントのエンドポイントを確認します。たとえば、次のとおりです。


    redirect_uri認可コードの許可後に UiPath Identity Server が認可要求をリダイレクトする URL が含まれます。
  2. 認可要求を認証するには、ユーザーがログインする必要があります。

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

    • ユーザーが、外部アプリケーションが登録された組織に属していない場合
    • 一部のリソースで、ログインしたユーザーが要求のスコープに対して必要な権限を持っていない場合
  3. 外部アプリケーションが認可コードを受信します。
    認可要求のリダイレクトの例: {redirect_url}?code={authorization_code}&scope={scopes} 認可コードは 1 回だけ使用できます。
  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}"
}{
    "grant_type": "authorization_code",
    "code": "{authorization_code}",
    "redirect_uri": "{redirect_url}",
    "client_id": "{app_id}",
    "client_secret": "{app_secret}"
}
    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}grant_type=authorization_code&code={authorization_code}&redirect_uri={redirect_url}&client_id={app_id}&client_secret={app_secret}
    注:
    [外部アプリケーション] に機密アプリケーションを登録すると、client_secret が返されます。
    非機密アプリケーションの場合は、client_secret の代わりに、code_challenge と code_challenge_method を使用します。
  5. 外部アプリケーションが、下記のようなアクセス トークンを含む応答を受信します。
    {
    "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 による認可コード

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

フローは認可コードを使用する場合と同じですが、認可要求に以下の要求クエリ パラメーターを含める必要があります。

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

code_challenge を生成するには、code_verifier のアルゴリズムを使用する必要があります。rfc7636 規格に準拠していれば、独自に作成することも可能です。 

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
			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
https://{yourDomain}/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}" 
}{ 
    "grant_type": "authorization_code", 
    "code": "{authorization_code}", 
    "redirect_uri": "{redirect_url}", 
    "client_id": "{app_id}", 
    "code_verifier": "{code_verifier}" 
}

応答には、アプリケーションがユーザー リソースにアクセスするために使用できるアクセス トークンが含まれます。このトークンは期限が切れるまで (1 時間) 使用できます。詳細については、「アクセス トークンを使用する」と「更新トークンを取得する」をご覧ください。

クライアント資格情報

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

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

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

以下に、認可ヘッダーにアクセス トークンを使用した、OData/マシン 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"
注: 使用可能な API については、 https://{yourDomain}/swagger/index.html の Orchestrator API Swagger をご覧ください。

更新トークンを取得する

アクセス トークンは 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" 
}{ 
    "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}"
}{
    "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 にする必要がありますのでご注意ください。

Was this page helpful?

サポートとサービス
サポートを受ける
UiPath アカデミー
RPA について学ぶ - オートメーション コース
UiPath フォーラム
UiPath コミュニティ フォーラム
UiPath ロゴ (白)
信頼とセキュリティ
利用規約
プライバシー ポリシー
Cookie ポリシー
© 2005-2024 UiPath. All rights reserved.