はじめに
- 本記事ではUiPath Automation Cloud (以下AC)にて利用可能な個人用アクセストークン(以下 PAT: Personal Access Token)のメリットと利用手順について説明します。
PATの何が便利？
-
PATのメリットを簡単に述べると、
- API利用時に必要となるアクセストークン取得のフローを省略できる
- ACユーザーに紐づくフォルダーロールを継承できる
-
これらのメリットをご理解いただくために、次にアクセストークンについて簡単に説明します。PATの利用手順を知りたい方はここは読み飛ばして PAT利用手順 まで進んでください。
アクセストークンとは？
- 保護対象リソース(Orchestrator)へのアクセスコントロールを安全に行うために認可サーバー(Identity Server)がクライアント(Studio/Robot/ブラウザー/カスタムアプリなど)に対して発行します。
- クライアントはまず認可サーバーへのアクセストークン取得を要求し、取得したトークンをHTTPヘッダーに埋め込んで保護対象リソースにアクセスできるようになります。
アクセストークン取得方法比較
- アクセストークン取得にはいくつかの方法があり、それぞれのメリット・デメリットについて比較します。
| トークン取得方法 | メリット | デメリット |
|---|---|---|
| APIキー | AC管理画面より取得できるユーザーキーとクライアントIDを使用してアクセストークンを取得するため実装が比較的容易 | スコープの指定ができず管理者権限が付与されてしまうため、これらの情報が漏洩した場合にはセキュリティリスクが高まるため非推奨 |
| 外部アプリケーション (クライアントクレデンシャル) | AC管理画面より取得できるクライアントIDとシークレットを使用してアクセストークンを取得するため実装が比較的容易 | アプリケーションスコープではフォルダーごとに権限を分離できないデメリットあり ※ きめ細かいアクセス権の利用によって解消できる |
| 外部アプリケーション (認可コード) | アクセストークン取得のフローではブラウザー起動とクライアントアプリへのリダイレクトが必要となり実装がやや煩雑 | ユーザースコープを利用することによってブラウザーログインするユーザーのロール設定が継承できるためフォルダーごとの権限分離が可能 |
| PAT | ・アクセストークン取得のフローの実装が不要 ・あらかじめスコープを定義し、かつユーザーに割り当てられたフォルダーへのロール設定が継承できる ・トークンの有効期限を設定できる |
ローカルユーザーに対してのみ利用可能で、ディレクトリユーザーでは現在利用できない |
- 外部アプリケーションのアクセストークン取得フローやサンプルスクリプトについてはナレッジベース記事もご参照ください。
PAT利用手順
- PATのメリットをご理解いただいたところで実際の利用手順について説明したいと思います。
AC設定
-
Automation Cloud にログインし、管理メニューをクリックします。
- External Applications (外部アプリケーション) メニューをクリックします。
- 個人用アクセストークンのタブに移動し、[設定] をクリックします。
- [すべてのユーザーに対して PAT を有効化] のトグルをオンにして [保存] をクリックします。
- PATを取得するユーザーでログインし、右上のユーザーアイコンをクリックし [設定] をクリックします。
- 個人用アクセストークンのメニューに移動し、 [新しいトークンを生成する] をクリックします。
- 今回の例では各Orchestratorフォルダー配下のプロセス一覧を取得したいと思います。
- 適切な名前と有効期限(2日以上)を指定します。
- リソースとして [Orchestrator API Access] を選択し、スコープとして
OR.Folder.ReadとOR.Execution.Readを選択します。これらは実際に利用するAPIに応じて適切に設定します。
- [保存] をクリックするとトークンが表示されるためメモします。
スクリプトの実装
- PowerShellでの実装例を示します。
$uriOrchにACのURL、$patに先ほど取得したトークンを設定して実行します。
uipath-pat-sample.ps1
$uriOrch = "https://cloud.uipath.com/<組織名>/<テナント名>"
$pat = '<先ほど取得した個人用アクセストークン>'
$headers = @{"Authorization" = "Bearer $pat" }
$contentType = "application/json;charset=utf-8"
# Get Folders
$uriFolder = "$uriOrch/odata/Folders"
$resFolder = Invoke-RestMethod -Uri $uriFolder -Method Get -ContentType $contentType -Headers $headers
$resFolder.value | foreach {
try {
$headerUnit = $headers + @{"X-UIPATH-OrganizationUnitId" = $_.Id }
Write-Host $_.FullyQualifiedName -Foreground Cyan
# Get Processes
$uriProcess = "$uriOrch/odata/Releases"
$resProcess = Invoke-RestMethod -Uri $uriProcess -Method Get -ContentType $contentType -Headers $headerUnit
$resProcess.value | ForEach-Object {
$procName = $_.Name
$procVer = $_.ProcessVersion
Write-Host " - $procName [$procVer]"
}
} catch {
Write-Host -ForegroundColor Red $_
}
}
- フォルダーごとにプロセス一覧が表示されることを確認します。
- この時、表示されるフォルダーはPATを取得したユーザーが権限を割り当てられたフォルダーのみに限定されます。
- PATの代わりに外部アプリケーション(クライアントクレデンシャル)を使用しアプリケーションスコープに
OR.Execution.Readを割り当てた場合はすべてのフォルダーのプロセスが表示されてしまい、権限を分離できません。
おわりに
- 本記事では個人用アクセストークン(PAT)のメリットと利用手順について説明しました。外部アプリケーションとの違いをご理解の上、適宜使い分けていただければと思います。