外部アプリケーション機能(OAuth)によるOrchestrator APIコール実装方法

はじめに

本文書ではAutomation Cloudおよびオンプレミス版Orchestrator v2021 で実装された「外部アプリケーション機能」の使用方法について詳細に説明をします。

本内容は Orchestrator v2023.4 および2023年4月時点での情報を元に記述をしているため、今後リリースされる新しいバージョンによっては挙動が異なる可能性があります。あらかじめご了承ください。 公式Webガイドは下記ページをご参照ください。

• Automation Cloud

  • https://docs.uipath.com/ja/automation-cloud/automation-cloud/latest/admin-guide/external-applications

• オンプレミス版Orchestrator

  • https://docs.uipath.com/ja/orchestrator/standalone/2023.4/user-guide/authorizing-external-applications 

  • https://docs.uipath.com/ja/orchestrator/standalone/2023.4/api-guide/accessing-uipath-resources-using-external-applications

外部アプリケーション機能の概要と移行が必要な理由

外部アプリケーションとはどのような機能でしょうか？

OAuth と呼ばれる標準的な認可プロトコルを使用することにより、安全かつ適切にAutomation CloudやOrchestratorのAPIをコールするクライアントアプリケーションにアクセストークンを付与する機能です。

従来のAPIコールするための認証は下記の方式が採られており、それぞれサポートポリシーが定められています。

• Automation Cloud

  • クライアントID、ユーザーキーを使用して エンドポイント https://account.uipath.com/oauth/token をコールして認証します。 ※ 2021年10月にDeprecated(非推奨)となり、外部アプリケーション機能(OAuth)への移行が推奨されています。

• オンプレミス版 Orchestrator

  • ローカルユーザーのTenancyName, Username, Passwordを使用して /api/account/authenticate をコールして認証します。 ※ v2021.4以降でDeprecated(非推奨)となっています。

  • Windows認証(NTLM認証)を使用して直接APIをコールします。(PowerShellでは Invoke-WebRequest または Invoke-RestMethod コマンドレットの -UseDefaultCredentials オプションを使用) ※ v2021.10に削除済みとなっています。

従来の認証方式では、Automation CloudのクライアントIDやユーザーキー、オンプレミス版 OrchestratorのUsernameやPasswordといった機密情報が悪意のあるユーザーに漏れてしまった場合、意図せずAPIコールを許容してしまうことになります。

特にOrchestratorの運用においてはそれだけに留まらず、UsernameとPasswordを使用して管理画面へのログインも許容することになってしまい、不用意にリソースへのアクセスを許容してしまうことになりかねません。 またこのような「意図しないアクセス」は通常のアクセスと区別が付きにくく監査ログでも検出しにくい、というデメリットがありました。

外部アプリケーション機能を使用することにより、これらのデメリットを解消し、より安全にアクセスコントロールを行うことができるようになります。 このため従来の認証方式を使用したカスタムスクリプトなどのクライアントアプリケーションは、今後は外部アプリケーション機能を利用したAPI連携を移行していただくことを推奨します。 

OAuthとは？

この機能を使いこなすためには OAuth の仕組みについて理解する必要があります。 

一般的に、OAuthとは「リソース所有者 の許可を得て、 認可サーバー が クライアントアプリケーション に アクセストークン を付与し、 保護対象リソース に適切にアクセスするための標準的な手順を定めたもの」になります。

太字で記述したキーワードが特に重要になりますので、それぞれの役割とAutomation Cloud / Orchestratorでは具体的に何に当てはまるのかを下記の表で示します。

機密アプリケーションと非機密アプリケーションの違い

• 機密アプリケーション: クライアントアプリケーションにクライアントシークレットを保存します。このため第三者にソースを見られることがないようにアプリケーションを管理する必要があります。クライアントクレデンシャル付与方式 (後述) ではリソース所有者の操作を介せずに実行できるため、バッチ処理などの無人実行も可能になります。

• 非機密アプリケーション: クライアントアプリケーションにクライアントシークレットを保存しません。このため第三者にソースコードを見られる可能性があるアプリケーションで使用する場合に適しています。ただし非機密アプリケーションでは認可コード + PKCE付与方式 (後述) によりリソース所有者がブラウザーを使用して認証処理を手動で行う必要があり、バッチ処理などの無人実行には向いていません。 

アクセストークン付与方式の違い

アクセストークンの付与方式 (Grant Type) にはいくつかの種類があり Automation Cloud / Orchestrator でサポートされている付与方式は下記のものになります。

• 認可コード

• 認可コード + PKCE

• クライアントクレデンシャル

それぞれの付与方式の違いと実装方法について説明をします。

認可コード (Authorization Code)

認可コード付与方式では下記の処理手順が実行されます。

• ① クライアントアプリケーションはリソース所有者に委譲して認可コードを取得するために認可要求のエンドポイント (Automation Cloud: https://cloud.uipath.com/identity_/connect/authorize, オンプレミスOrchestrator: /identity/connect/authorize) をコールし、アプリケーションID・スコープ・リダイレクトURLをIdentity Serverに送信します。

• ② リソース所有者はブラウザーを使用して手動で Automation Cloud / Orchestrator にログインし、Identity Serverに対して自分自身の認証を行います。

• ③ 認証が成功するとIdentity Serverはクライアントアプリケーションに 認可コード を付与します。

• ④ クライアントアプリケーションはアクセストークン取得のエンドポイント (Automation Cloud: https://cloud.uipath.com/identity_/connect/token, オンプレミスOrchestrator: /identity/connect/token) をコールし、認可コードとアプリケーションシークレットをIdentity Serverに送信します。

• ⑤ アクセストークン取得要求が正常の場合、Identity Serverはクライアントアプリケーションにアクセストークンを付与します。

• ⑥ アクセストークン取得後、クライアントアプリケーションはAutomation Cloud / OrchestratorのAPIを使用して保護対象リソースにアクセスできるようになります。

この付与方式を図で示します。

認可コード + PKCE (Authorization Code + PKCE)

"認可コード横取り攻撃" を防御するために、下記手順により RFC 7636 で定められた PKCE (Proof Key for Code Exchange) を使用することもできます。 大まかな処理フローは認可コードと同様ですが、アプリケーションシークレットの代わりにランダムで生成される code_verifier とそのハッシュ値である code_challenge を使用する点が異なります。

• 【事前処理】クライアントアプリケーションは code_verifier と名付けられたシークレットを毎回異なる値で生成して記録します。

• 【事前処理】クライアントアプリケーションは code_verifier の SHA-256 (code_challenge_method) によるハッシュ値を計算し、更にBase64でエンコードを行い code_challenge を算出します。

• ① クライアントアプリケーションはリソース所有者に委譲して認可コードを取得するために認可要求のエンドポイントをコールし、アプリケーションID・スコープ・リダイレクト URLに加えて code_challenge と code_challenge_method (S256) も合わせてIdentity Serverに送信します。

• ② リソース所有者はブラウザーを使用して手動で Automation Cloud / Orchestrator にログインし、Identity Serverに対して自分自身の認証を行います。

• ③ 認可サーバーは通常通り認可コードを応答しますが、 code_challenge と code_challenge_method を記録します。

• ④ クライアントアプリケーションはアクセストークン取得のエンドポイント /identity/connect/token をコールし、認可コードと code_verifier アプリケーションシークレットをIdentity Serverに送信します。

• ⑤ 認可サーバーは code_challenge を再度算出し、元の値と一致するか確認し、一致する場合はクライアントアプリケーションにアクセストークンを送信します。

• ⑥ アクセストークン取得後、クライアントアプリケーションはAutomation Cloud / Orchestratorの保護対象リソースにアクセスできるようになります。

この付与方式も人手を介することになりますが、シークレットをクライアントアプリケーションに埋め込む必要がありません。このためソースコードをAutomation Cloud / Orchestratorへのアクセス権を持たない第三者に見られたとしても保護対象リソースへの意図しないアクセスを許容することはない、というメリットを享受できます。

この付与方式を図で示します。

認可コード および 認可コード + PKCE 付与方式ではアクセストークン取得のために初回ブラウザーでの手動ログインは必須となりますが、2回目以降バックグラウンドで処理するためにリフレッシュトークン(更新トークン)を使用することも可能です。詳細な実装方法は 更新トークンを取得する をご参照ください。

クライアントクレデンシャル (Client Credentials)

クライアントクレデンシャル付与方式は最もシンプルでありクライアントアプリケーション自体がリソース所有者となりアクセストークンを取得することができます。この付与方式は人手を介さないバッチ処理などに適していますが、シークレットをクライアントアプリケーションに埋め込むことになるため厳重に管理を行う必要があります。万が一、シークレットが第三者に漏洩してしまった場合には速やかに再作成を行います。

この付与方式を図で示します。

外部アプリケーションの設定方法

次にAutomation Cloud / Orchestratorでの外部アプリケーションの設定方法について説明をします。

Automation Cloudでの設定方法

• https://cloud.uipath.com に管理者でログインし、 [管理] > [外部アプリケーション] を選択し、[アプリケーションを追加] をクリックします。

• アプリケーション名を入力し、アプリケーションの種類を選択します。

  • 付与方式として認可コードまたはクライアントクレデンシャルを使用する場合には、[機密アプリケーション] を選択します。

  • 付与方式として認可コード + PKCE を使用する場合には、[非機密アプリケーション] を選択します。

• [スコープを追加] をクリックし、 リソースとして [Orchestrator API Access] を選択します。 (Data ServiceにAPIアクセスするには [Data Service API] を選択します)

  • 付与方式として認証コードまたは認可コード + PKCEを使用する場合には、[ユーザースコープ] を選択します。

  • 付与方式としてクライアントクレデンシャルを使用する場合には、[アプリケーションスコープ] を選択します。

• 保護対象リソースに許可する操作をスコープとして選択します。(複数選択可能) たとえばユーザー読み取り権限を付与するには OR.Users.Read 、マシンユーザー読み取り権限を付与するには OR.Machines.Read を選択します。

  • 使用するOrchestrator APIに対応するスコープは、Swagger(https://cloud.uipath.com/{organizationName}/{tenantName}/orchestrator_/swagger)を開き、各APIの OAuth required scopesを確認します。

    

• クライアントがWebアプリケーションの場合にはIdentity Serverからの応答として認可コードが返されトークン取得の処理を行うためにコールバックされるURLを「リダイレクトURL」として設定します。

  • スクリプトから認可コードを取得する場合にはAutomation Cloud / Orchestrator など任意のURLを設定し、スクリプトから呼び出す際に同じ値を指定します。

  • サンプルのPowerShellスクリプト(uipath-authcode-sample.ps1)を実行するには WCF URL 予約 (http://127.0.0.1/TemporaryListenAddresses/) を指定します。

  • クライアントクレデンシャル付与方式ではリダイレクトURLを設定する必要はありません。

• [追加] をクリックし、アプリケーション設定を保存します。 ポップアップで表示されるアプリIDとアプリシークレットをメモします。 アプリシークレットは再表示できないため、万が一紛失してしまった場合にはアプリケーションを編集し、 [新しく作成] をクリックして再生成します。

オンプレミス版 Orchestratorでの設定方法

• OrchestratorのDefaultなどのテナントに管理者としてログインします。

• [テナント] > [アクセス権を管理] > [ロールを割り当て]に移動して、 [アカウントおよびグループを管理] をクリックします。テナントレベルの管理ポータルが表示されます。

• 左側の [外部アプリケーション] を選択し、[アプリケーションを追加] をクリックします。

• 以降の設定は「Automation Cloudでの設定方法」と同様です。

  

サンプルスクリプト実行方法

それぞれの付与方式をクライアントアプリケーションとしてどのように実装するかを理解しやすくするためにPowerShellでのサンプルスクリプトを用意しております。それぞれの実行手順について説明をします。 前提として、オンプレミスOrchestrator環境にて自己署名証明書を使用している場合、スクリプト実行環境であらかじめ証明書を「信頼するルート証明機関」にインポートしておく必要があります。

クライアントクレデンシャル付与方式

• 動作要件:

  • PowerShell 4.0以降

• 添付のPowerShellスクリプト(uipath-cred-sample.ps1)を編集し先頭の変数を設定する、もしくは下記のようにスクリプト実行時に引数として値を渡します。 (例)

.\uipath-cred-sample.ps1 -uriOrch 'https://srv01.lab.test' -clientId '766f74b7-790f-4189-9a13-5d7bffca78ab' -clientSecret 'ABCDEFGHIJKLMNOP' -scopes 'OR.Machines.Read OR.Users.Read'

• uriOrch: Orchestrator URLを指定します。Automation Cloudの場合にはアカウント論理名・テナント名も含むURL (例: https://cloud.uipath.com/orgName/tenantName) を指定します。

• clientId: 外部アプリケーション設定にて表示されるアプリIDを指定します。

• clientSecret: 外部アプリケーション設定にて表示されるアプリシークレットを指定します。

• scopes: 外部アプリケーション設定にて登録されたスコープ。複数スコープはスペース区切りで指定します。厳密にはAutomation Cloud / Orchestratorで設定されたスコープと一致または部分集合を指定します。

認可コード付与方式 および 認可コード + PKCE 付与方式

• 動作要件:

  • PowerShell 5.1以降 + Selenium PowerShell モジュール + WebDriver

  • ブラウザーでログイン操作を行うユーザーはあらかじめ任意のフォルダーへのアクセス権があり、かつ適切なロール(サンプルではユーザーとマシン一覧を取得するため、ユーザーへの参照権限とマシンへの参照・編集権限)を割り当てる必要があります。

• 添付のPowerShellスクリプト(uipath-authcode-sample.ps1)を編集し先頭の変数を設定する、もしくは下記のようにスクリプト実行時に引数として値を渡します。

  • (認可コード方式の実行例)

    .\uipath-authcode-sample.ps1 -uriOrch 'https://cloud.uipath.com/MyOrganization/MyTenant' -clientId 'b68f8070-a6a9-4a47-bb9b-050ce60d0a06' -clientSecret 'ABCDEFGHIJKLMNOP' -scopes 'OR.Machines.Read OR.Users.Read' -browser 'Edge'

  • (認可コード + PKCE方式の実行例)

    .\uipath-authcode-sample.ps1 -uriOrch 'https://cloud.uipath.com/MyOrganization/MyTenant' -clientId '45bfb16d-7612-468d-85ba-76921f76f82c' -clientSecret '' -scopes 'OR.Machines.Read OR.Users.Read' -browser 'Edge'

  • uriOrch: Orchestrator URLを指定します。Automation Cloudの場合にはアカウント論理名・テナント名も含むURL (例: https://cloud.uipath.com/orgName/tenantName) を指定します。

  • clientId: 外部アプリケーション設定にて表示されるアプリIDを指定します。

  • clientSecret: 認可コード付与方式では外部アプリケーション設定にて表示されるアプリシークレットを指定します。認可コード + PKCE付与方式では空文字("")を指定します。

  • scopes: 外部アプリケーション設定にて登録されたスコープ。複数スコープはスペース区切りで指定します。 (厳密にはAutomation Cloud/Orchestratorで設定されたスコープと一致または部分集合を指定します)

  • redirectUrl: 外部アプリケーション設定にて登録されたリダイレクトURLを指定します。既定値ではWCF URL予約 (http://127.0.0.1/TemporaryListenAddresses/) を使用します。

  • httpListener: リダイレクト用にHTTPリッスンするアドレスを指定します。既定値ではWCF URL予約 (http://+:80/TemporaryListenAddresses/) を使用します。このアドレスは非管理者権限にてHTTPリッスン可能な特別なアドレスですが、別のアドレスに変更することも可能です。それに合わせてredirectUrlおよび外部アプリのリダイレクトURLを変更します。

  • browser: 認可コード使用時に呼び出されるブラウザーとして "Chrome", "Firefox" または "Edge" を指定します。 (Internet ExplorerまたはレガシーEdgeはサポートされません)

Selenium PowerShellモジュールのインストール

認可コードを使用する場合、スクリプトからリソース所有者へのブラウザー操作を起動するためにSelenium PowerShellモジュール v3.0.1とWebDriverを使用しており、これらを予めインストールする必要があります。

PowerShellコンソールにて次のコマンドを実行します。

• 現ユーザーのみ:

Install-Module Selenium -Scope CurrentUser

• 全ユーザー (要管理者権限):

Install-Module Selenium -Scope AllUsers

PSModulePath 環境変数 ($Env:PSModulePath 実行時に返される値) に含まれるいずれかのディレクトリ配下にSeleniumモジュールがインストールされていることを確認します。

WebDriverのインストール

各ブラウザー・各バージョンに応じて適切なWebDriverを各サイトからダウンロードします。Firefox, Edgeはブラウザー本体とWebDriverのビット(32ビット→x86, 64ビット→x64)を合わせます。

• Chrome: https://chromedriver.chromium.org/downloads → chromedriver.exe

• Firefox: https://github.com/mozilla/geckodriver/releases → geckodriver.exe

• Edge (Chromium): https://developer.microsoft.com/en-us/microsoft-edge/tools/webdriver/ → msedgedriver.exe

Selenium PowerShellモジュールのインストール方式に応じて下記ディレクトリにコピーします。

• 現ユーザー:

  %UserProfile%\Documents\WindowsPowerShell\Modules\Selenium\3.0.1\assemblies

• 全ユーザー (PowerShell 5.1):

  C:\Program Files\WindowsPowerShell\Modules\Selenium\3.0.1\assemblies

• 全ユーザー (PowerShell 6 以降):

  C:\Program Files\PowerShell\Modules\Selenium\3.0.1\assemblies

以上の手順により認可コード付与方式によるサンプルスクリプトが実行できるようになります。

Debugモード

サンプルスクリプト正常に動作しない場合には -debug オプションを付けて実行することにより詳細な出力を見ることができます。

免責

添付のサンプルスクリプトは外部アプリケーション機能の利用方法をご理解いただくことを目的として提供しております。 スクリプトの動作について万全を期しておりますが本番環境に対して実行する際には、非本番環境にて事前に十分検証を実施していただくことを推奨いたします。 またスクリプトの内容について弊社テクニカルサポートにお問い合わせいただきましても、UiPath製品と直接関わりがない部分についてはお答えできない場合がございます。あらかじめご了承ください。

既存スクリプトの移行手順

外部アプリケーション機能を使用するため、Orchestrator APIをコールしている既存スクリプトの認証部分をどのように書き換えれば良いかPowerShellを例として説明します。

Automation Cloudの場合

AS-IS:

既存の認証方法では下記のような処理によりアクセストークンを取得しています。

$uriToken = "https://account.uipath.com/oauth/token" $clientId = "{Client Id}" $userKey = "{User Key}" $bodyToken = @{ "grant_type" = "refresh_token" "client_id" = $clientId "refresh_token" = $userKey } | ConvertTo-Json $resToken = Invoke-RestMethod -Uri $uriToken -Method Post -Body $bodyToken -ContentType "application/json;charset=utf-8" $authKey = $resToken.access_token $headers = @{"Authorization"="Bearer $authKey"}

TO-BE:

クライアントクレデンシャル付与方式を使用する外部アプリケーション機能では下記のように処理を行います。

$uriToken = "https://cloud.uipath.com/identity_/connect/token" $clientId = "{Application Client Id}" $clientSecret = '{Application Client Secret}' $scopes = "{Application Scopes}" $bodyToken = @{ grant_type = "client_credentials" client_id = $clientId client_secret = $clientSecret scope = $scopes } $resToken = Invoke-RestMethod -Uri $uriToken -Method Post -Body $bodyToken -ContentType "application/x-www-form-urlencoded" $authKey = $resToken.access_token $headers = @{"Authorization"="Bearer $authKey"}

オンプレミス版Orchestratorの場合

AS-IS:

既存の認証方法では下記のような処理によりアクセストークンを取得しています。

$uriOrch = "https://{orchestrator-host}" $uriToken = "$uriOrch/api/Account/authenticate" $tenantName = "default" $adminName = "{admin-name}" $adminPasswd = "{admin-password}" $bodyToken = @{ "tenancyName" = $tenantName "usernameOrEmailAddress" = $adminName "password" = $adminPasswd } | ConvertTo-Json $resToken = Invoke-RestMethod -Uri $uriToken -Method Post -Body $bodyToken -ContentType "application/json;charset=utf-8" $authKey = $resToken.result $headers = @{"Authorization"="Bearer $authKey"}

TO-BE:

クライアントクレデンシャル付与方式を使用する外部アプリケーション機能では下記のように処理を行います。

$uriToken = "https://{orchestrator-host}/identity/connect/token" $clientId = "{Application Client Id}" $clientSecret = '{Application Client Secret}' $scopes = "{Application Scopes}" $bodyToken = @{ grant_type = "client_credentials" client_id = $clientId client_secret = $clientSecret scope = $scopes } $resToken = Invoke-RestMethod -Uri $uriToken -Method Post -Body $bodyToken -ContentType "application/x-www-form-urlencoded" $authKey = $resToken.access_token $headers = @{"Authorization"="Bearer $authKey"} 

サンプルワークフロー実行方法

ワークフローでOrchestrator APIをコールする場合について、クライアントクレデンシャル付与方式のサンプルワークフローも用意しております。UiPath Studio v2020.10 で開発されています。 ワークフローの実行手順について説明をします。

1. 設定ファイル.xlsx を開き、 [設定]シートの認証方式を選択します。

2. 認証方式に応じた設定をそれぞれのExcelシートで設定します。たとえばAutomation Cloudへ外部アプリケーションを用いて認証を行う場合は、[外部アプリケーション（Automation Cloud）]シートを開きます。

3. 認証方法に外部アプリケーションを指定した場合は、外部アプリケーションにて設定した値をそれぞれのキーに対応したフィールドにコピーします。

4. ワークフローを実行し、トークンを取得した後、ユーザー一覧とマシンキー一覧が表示されることを確認します。

既存ワークフローの移行手順

外部アプリケーション機能を使用するため、Orchestrator APIをコールしている既存ワークフローの認証部分をどのように書き換えれば良いかは下記XAMLファイルを比較してご確認ください。

Automation Cloudの場合

• AS-IS: AutomationCloud既存認証方法.xaml

• TO-BE: AutomationCloud外部アプリケーション.xaml

オンプレミス版Orchestratorの場合

• AS-IS: オンプレミス_既存認証方法.xaml

• TO-BE: オンプレミス_外部アプリケーション.xaml

きめ細かいアクセス権の利用

Automation CloudまたはオンプレミスOrchestrator v2023.4以降では外部アプリにて きめ細かいアクセス権 を設定することができます。

まずこの機能の背景となる課題について説明します。従来の機密アプリ&アプリケーションスコープではテナント全体に権限が付与されてしまい、フォルダーごとの制御ができませんでした。たとえばOR.Execution.Readスコープを付与した場合、フォルダーごとに参照可能なプロセスを制御することができずテナントに含まれるすべてのフォルダーのプロセスが参照されます。

きめ細かいアクセス権を利用することにより、Orchestratorユーザーと同様に外部アプリに対してもテナントロールまたはフォルダーロールを割り当てることが可能になります。これによってフォルダーごとにアクセス権を制御することができるようになります。

利用手順

1. オンプレミスOrchestrator v2023.4.0での設定

   • この機能を有効化するため C:\Program Files (x86)\UiPath\Orchestrator\Identity\appsettings.Production.json にて IdentityFeatureFlags > PublicApps セクションに下記設定を追加し、設定反映のために管理者権限で iisreset コマンドを実行し、IISサービスを再起動します。 "IdentityFeatureFlags": { "PublicApps": { "EnableDefaultScope": true, "ApplicationDirectoryMembershipEnabled": true } }

     

   • 詳細はリリースノートをご参照ください。なおこの手順はAutomation Cloudでは不要です。

2. 外部アプリ作成およびロール割り当て

   • 機密アプリ&アプリケーションスコープによって外部アプリ作成する際、Orchestrator側のロールにて制御を行うスコープは含めないようにします。たとえばプロセス参照をフォルダーごとに制限したい場合、OR.Execution.Readスコープは付与しません。(付与した場合、従来通りテナント全体に権限が付与されてしまいます)

     

   • 次にOrchestratorにて外部アプリに割り当てるテナントロールおよびフォルダーロールを作成します。

     • テナントロールの割り当ては、テナント > アクセス権を管理 > ロールを割り当て > 外部アプリ をクリックし、作成した外部アプリを選択し適切なロールを割り当てます。

       

     • フォルダーロールの割り当ては、対象フォルダー > 設定 > アカウント/グループを割り当て をクリックし、作成した外部アプリを選択し適切なロールを割り当てます。

       

3. スクリプトの実装

   • 外部アプリにてアクセストークンを取得する際、scopeに OR.Default を含めるように実装します。これによって外部アプリにて設定したスコープに加えてOrchestrator側のロールが追加されるようになります。

     

   • OR.Default を含めなかった場合、従来通り外部アプリにて設定したスコープのみ有効となります。