2021年9月30日

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

2021年9月30日

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

はじめに

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

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

 

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

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

 

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

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

  • Automation Cloud
    • クライアントID、ユーザーキーを使用して エンドポイント https://account.uipath.com/oauth/token をコールして認証します。
      ※ 2021年10月にDeprecated(非推奨)となる予定です。
  • オンプレミス版 Orchestrator
    • ローカルユーザーのUsernameとPasswordを使用して /api/account/authenticate をコールして認証します。
      ※ v2021.4以降でDeprecated(非推奨)となっています。
    • Windows認証を使用して直接APIをコールします。(PowerShellでは Invoke-WebRequest または Invoke-RestMethod コマンドレットの -UseDefaultCredentials オプションを使用)
      ※ v2021.10にDiscontinued(廃止)となる予定です

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

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

 

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

 

OAuthとは?

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

 

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

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

キーワード 役割 Automation Cloud / Orchestrator
リソース所有者 APIへのアクセス権限を持ち、その権限を委譲できる所有者 ブラウザーで管理コンソールにアクセスするユーザー
認可サーバー アクセストークンをクライアントアプリケーションに渡すサーバー Identity Server (Automation Cloud / Orchestrator に内包されている)
クライアントアプリケーション

認可サーバーよりトークンを取得し、保護対象リソースにアクセスするクライアント

機密情報を保持する「機密アプリケーション」と機密情報を保持しない「非機密アプリケーション」の2種類がある

エンドユーザーによって開発されたカスタムアプリケーションやスクリプトなど
アクセストークン クライアントアプリケーションが保護対象リソースにアクセスするために必要となる 認可サーバーが発行するランダムな文字列 Bearerトークン
保護対象リソース 認可されたクライアントにのみアクセスを許可する保護されたリソース OrchestratorリソースやData Serviceリソースなど

 

OAuth

 

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

  • 機密アプリケーション: クライアントアプリケーションにクライアントシークレットを保存します。このため第三者にソースを見られることがないようにアプリケーションを管理する必要があります。クライアントクレデンシャル付与方式 (後述) ではリソース所有者の操作を介せずに実行できるため、バッチ処理などの無人実行も可能になります。
  • 非機密アプリケーション: クライアントアプリケーションにクライアントシークレットを保存しません。このため第三者にソースコードを見られる可能性があるアプリケーションで使用する場合に適しています。ただし非機密アプリケーションでは認可コード + 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

クライアントクレデンシャル (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 を選択します。
  • クライアントがWebアプリケーションの場合にはIdentity Serverからの応答として認可コードが返されトークン取得の処理を行うためにコールバックされるURLを「リダイレクトURL」として設定します。スクリプトから認可コードを取得する場合にはAutomation Cloud / Orchestrator など任意のURLを設定し、スクリプトから呼び出す際に同じ値を指定します。クライアントクレデンシャル付与方式ではリダイレクトURLを設定する必要はありません。
  • [追加] をクリックし、アプリケーション設定を保存します。 ポップアップで表示されるアプリIDとアプリシークレットをメモします。 アプリシークレットは再表示できないため、万が一紛失してしまった場合にはアプリケーションを編集し、 [新しく作成] をクリックして再生成します。

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

  • OrchestratorのHostテナントにホスト管理者でログインし、 [セキュリティ]タブ > [外部アプリケーション] をクリックし、[アプリケーションを追加] をクリックします。
  • 以降の設定は「Automation Cloudでの設定方法」と同様です。
ExternalAppSettings

 

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

それぞれの付与方式をクライアントアプリケーションとしてどのように実装するかを理解しやすくするために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' -redirectUrl 'https://cloud.uipath.com/MyOrganization/MyTenant' -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' -redirectUrl 'https://cloud.uipath.com/MyOrganization/MyTenant' -browser 'Edge'
    • uriOrch: Orchestrator URLを指定します。Automation Cloudの場合にはアカウント論理名・テナント名も含むURL (例: https://cloud.uipath.com/orgName/tenantName) を指定します。
    • clientId: 外部アプリケーション設定にて表示されるアプリIDを指定します。
    • clientSecret: 認可コード付与方式では外部アプリケーション設定にて表示されるアプリシークレットを指定します。認可コード + PKCE付与方式では空文字("")を指定します。
    • scopes: 外部アプリケーション設定にて登録されたスコープ。複数スコープはスペース区切りで指定します。 (厳密にはAutomation Cloud/Orchestratorで設定されたスコープと一致または部分集合を指定します)
    • redirectUrl: 外部アプリケーション設定にて登録されたリダイレクトURLを指定します。
    • browser: 認可コード使用時に呼び出されるブラウザーとして "Chrome", "Firefox" または "Edge" を指定します。 (Internet ExplorerまたはレガシーEdgeはサポートされません)
    • timeoutCount: ユーザーによるログイン操作が完了し後続処理を実施するまで5秒間隔で待機する回数を指定します。既定値では20回、つまり20*5=100秒間待機します。

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)を合わせます。

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

  • 現ユーザー:
    %UserProfile%\Documents\PowerShell\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: 既存の認証方法では下記のような処理によりアクセストークンを取得しています。

Automation Cloud 既存認証方法

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

Automation Cloud 外部アプリケーションによるトークン取得方法

$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: 既存の認証方法では下記のような処理によりアクセストークンを取得しています。

Orchestrator 既存認証方法

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

Orchestrator 外部アプリケーションによるトークン取得方法

$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: Automation_Cloud_既存認証方法.xaml
  • TO-BE: Automation_Cloud_外部アプリケーション.xaml

オンプレミス版Orchestratorの場合

  • AS-IS: オンプレミス_既存認証方法.xaml
  • TO-BE: オンプレミス_外部アプリケーション.xaml

 

参考文献

  • OAuth徹底入門 (ISBN:978-4-7981-5929-4)

by Japan KB team

TOPICS: Region: Japan

Show sidebar