Automation Cloudの外部アプリケーションとは？

外部アプリケーションを登録することにより、Automation Cloud上で利用しているUiPathのサービスとサードパーティのアプリケーションを連携することができます。外部アプリケーションにはスコープと許可の種類を設定でき、それに対応したアクセストークンを取得することができます。許可の種類として、"認可コード"、"クライアント資格情報"、"PKCEによる認可コード"があります。その他の情報と基本的な設定方法については以下のガイドを参照してください。

参考：外部アプリケーションを使用して UiPath のリソースにアクセスする

きめ細かいアクセス権管理

組織レベルのアプリケーションでは、組織の全てのリソースに対してアクセス権が付与されます。組織の中でアクセスを許可するリソースを細かく制御したい場合、例えばあるテナントのOrchestratorにおいて「フォルダAにはアクセスさせたいが、フォルダBにはアクセスさせたくない」といったような場合、上記の認可の方法では権限を過剰に付与してしまう問題があります。

外部アプリケーションのきめ細かいアクセス権管理を使用することで、アクセス権を付与するフォルダ、テナント等のリソースを細かく設定できます。

参考：外部アプリのきめ細かいアクセス権を設定する

設定手順

きめ細かいアクセス権管理で必要な手順は以下です。

外部アプリケーションの追加
サービス側のロール設定
リクエスト送信の実装

ここではOrchestratorのフォルダアクセス（ジョブ情報の取得）を例に説明します。以下のように、FolderAとFolderBを用意し、FolderAとFolderBで実行された"LogHello"というジョブの情報を/odata/Jobsのエンドポイントを使用して取得する場合を考えます。

外部アプリケーションの追加

Automation Cloudの管理ページより、外部アプリケーションを追加します。手順は以下の通りです。

Automation Cloudの　管理 > 外部アプリケーション　を開きます。
"+アプリケーションを追加"を選択します。
任意の"アプリケーション名"を設定し、リソースとスコープの設定をせず"追加"をクリックします。ここでは機密アプリケーションを選択します。

表示されるアプリケーションIDとアプリケーションシークレットをメモします。外部アプリケーションの追加作業は以上です。

サービス側のロール設定

Orchestratorのページにアクセスし、対象のテナント、フォルダのページを開きます。ここではFolderAに対してジョブを表示するロールを割り当てます。比較のため、FolderBにはロールを割り当てない設定とします。
ユーザー > "アカウント/グループを割り当て"を開きます。
"アカウント、グループ、または外部アプリ"の欄で追加した外部アプリケーションを選択します。ここでは"+新しいロール"よりジョブ:表示を許可した"JobsRead"というロールを作成して割り当てます。
ユーザー一覧に表示されていれば、ロール設定は完了です。

リクエスト送信の実装

UiPath Studioの実装例

『HTTP要求』アクティビティを使用してAPIリクエストを送信し、アクセストークンとフォルダのジョブ情報取得する実装例をご紹介します。アクセストークン取得のワークフローの一例は以下の通りです。

『HTTP要求』アクティビティの最低限必要な設定項目は以下です。

項目	値
要求URL	"https://cloud.uipath.com/identity_/connect/token"
応答コンテンツ	authResponse（String型の変数）
パラメータ	下のテーブルに記載します

『HTTP要求』アクティビティで設定しているパラメータのコレクションは以下の通りです。

名前	方向	型	値
client_id	入力	String	{アプリケーションID}
client_secret	入力	String	{アプリケーションシークレット}
grant_type	入力	String	"client_credentials"
scope	入力	String	"OR.Default"

返ったレスポンスをString型の"authResponse"で受け取り、『JSONを逆シリアル化』アクティビティでJsonObject型の"authResponseobj"に変換しています。正しくアクセストークンを取得できている場合、
authReponseobj("access_token").ToString としてアクセストークンを取得できます。

『HTTP要求』、『JSONを逆シリアル化』アクティビティを使用するためにはUiPath.WebAPI.Activitiesパッケージをインストールする必要があります。

ここで指定するscopeにOR.Jobs.Read等の操作に必要なスコープを直接指定しないようにします。指定した場合、{"error":"invalid_scope"}のエラーが返り、アクセストークンを取得できません。
また、OR.Defaultの大文字小文字に注意してください。"D"が大文字である必要があります。OR.defaultとしてもアクセストークンを取得できますが、取得したトークンでAPIコールすると権限不足のエラーが返ります。

次にジョブ情報の取得部分です。
フォルダで実行されたジョブを取得するにはフォルダの情報をX-UIPATH-OrganizationUnitIdとして指定する必要があります。フォルダのページを開いた時にアドレスバーに表示されるfid=の箇所を確認するか、/odata/Foldersのエンドポイントを使用して対象のフォルダのIDを取得しておくとよいと思います。Swaggerで簡単に確認できます。Swaggerの使い方については UiPath OrchestratorのAPIをSwaggerで簡単に試してみるを参考にしてください。

ジョブを取得するワークフローの一例は以下の通りです。
『HTTP要求』アクティビティを使用して/odata/Jobsのエンドポイントにリクエストを送信します。リクエストの際に上で取得したアクセストークンをヘッダーに追加します。

『HTTP要求』アクティビティの設定項目は以下です。

項目	値
要求URL	"https://cloud.uipath.com/{組織名}/{テナント名}/odata/Jobs"
応答コンテンツ	jobsResponse（String型の変数）
ヘッダー	下のテーブルに記載します

『HTTP要求』アクティビティで設定しているヘッダーのコレクションは以下の通りです。（パラメータには何も指定しません）

名前	方向	型	値
Authorization	入力	String	"Bearer " + {上で取得したアクセストークン}
X-UIPATH-OrganizationUnitId	入力	String	{対象フォルダのフォルダID}

実行すると、FolderAのジョブ実行情報がJSON形式のレスポンスとして返ります。

FolderBに対して同様のリクエストを送信した場合、ロールを設定していない為"You are not authorized!"のエラーが返ります。このように、きめ細かいアクセス権を使用することで適切なアクセス権を付与できることが確認できました。

参考：
Orchestrator Automation Cloud API Guide > ジョブの要求
 UiPath OrchestratorのAPIをSwaggerで簡単に試してみる

PowerShellの実装例

もう一つ例を挙げるとして、Powershellスクリプトによりアクセストークン取得とジョブ情報取得をする実装例を掲載しておきます。Invoke-RestMethodを使用してリクエストを送信しています。最後に取得したレスポンスをjobs.jsonのファイルに書き出しています。

getJobsAPI.ps1

param (
  [string] $automationCloudUrl = "https://cloud.uipath.com/",
  [string] $organizationId = "{組織名}",
  [string] $tenantName = "{テナント名}",
  [string] $clientId = "{アプリケーションID}",
  [string] $clientSecret = "{アプリケーションシークレット}",
  [string] $scopes = "OR.Default"
)

# Get Access Token Function
function Get-BearerToken {
    $Body = @{
       "client_id" = $clientId
       "client_secret" = $clientSecret
       "scope" = $scopes
       "grant_type" = "client_credentials"
    }
    $tokenEndpoint = "$automationCloudUrl/identity_/connect/token"
    $response = Invoke-RestMethod -Uri $tokenEndpoint -Method Post -Body $Body -ContentType "application/x-www-form-urlencoded"
    return $response.access_token
}

# Call token request
$bearerToken = Get-BearerToken

# Get Jobs Function
function Invoke-GetOCJobsAPI {
    param (
        [string] $bearerToken,
        [string] $folderId
    )
    $jobsEndpoint = "$automationCloudUrl/$organizationId/$tenantName/orchestrator_/odata/Jobs"
    $headers = @{
        "Authorization" = "Bearer $bearerToken"
        "X-UIPATH-OrganizationUnitId" = $folderId
    }
    $response = Invoke-RestMethod -Uri $jobsEndpoint -Method Get -Headers $headers -ContentType "application/json"
    return $response| ConvertTo-Json -Depth 5
}

# Call Jobs Request
$jobsResult = Invoke-GetOCJobsAPI -bearerToken $bearerToken -folderId {フォルダID}

# Export to file
echo $jobsResult > jobs.json

おわりに

最後まで読んで頂きありがとうございました。本稿では外部アプリケーションのきめ細かいアクセス権を使ってアクセス権を管理する方法をご紹介しました。サードパーティのツールからAPI連携をする際には便利な機能だと思います。ぜひ活用してみてください。

それでは快適なUiPathライフを！

UiPath Automation Cloud: きめ細かいアクセス権の細かい話