- 基本情報
- 認証
- 認証方法
- 外部アプリケーション (OAuth)
- ROPC (非推奨)
- Swagger の定義
- Orchestrator API
- プラットフォーム管理 API
外部アプリケーション (OAuth)
UiPath 製品と外部アプリケーションとの連携に取り組む開発者は、スコープの変更管理、アクセス トークンと更新トークンの管理、外部アプリと UiPath リソースとの連携の維持などの作業を担当します。このガイドの以降では、これらの操作について説明します。
OAuth には、認証、認可、委任、および API 呼び出しのセキュリティ保護を簡素化するために利用できるライブラリの選択肢が用意されています。これらのリソースには、OAuth の公式 Web サイトから直接アクセスできます。
開発者は、組織管理者が外部アプリケーションを UiPath に登録した後、UiPath リソースで外部アプリを認証するための、登録の詳細を取得する必要があります。
-
アプリの種類とアプリ ID。機密アプリケーションを使用している場合は、アプリ シークレットも必要になります。これらを使用して、UiPath の Identity Server でアプリを認証します。Identity Server は OAuth 2.0 フレームワークに対応している、UiPath リソースにアクセスするための認可サーバーです。
-
さらに、外部アプリの範囲も知っておく必要があります。範囲は、外部アプリがアクセスできる UiPath のリソースを定義するものです。これには、リソースの仕様 (アセット、プロセスなど) とアクセス許可レベル (読み取り、書き込み、編集など) の両方が含まれます。
外部アプリケーションの登録後、適切な許可の種類を使用して、外部アプリケーションに対する適切な認可メカニズムを実装する必要があります。これによって外部アプリケーションはアクセス トークンを取得できるようになります。
このプロセスでは、外部アプリの範囲と登録済みアプリの資格情報、すなわちアプリ ID (機密アプリケーションの場合は、アプリ シークレット) を Identity Server に提供して、アクセス トークンを要求します。資格情報が有効な場合、Identity Server はアクセス トークンの生成に使用される認可コードを発行して応答します。
アプリケーションの種類 |
スコープ |
必要な許可の種類 |
---|---|---|
機密 |
アプリケーション |
クライアント資格情報 |
機密 |
ユーザー |
認可コード |
機密 |
アプリケーションとユーザー |
クライアント資格情報と認証コード |
非機密 |
ユーザー |
PKCE による認可コード |
Orchestrator のように、ユーザーとアプリケーションの両方のスコープが同名の場合、リソースがユーザー スコープまたはアプリケーション スコープのどちらで呼び出されるかは、使用する許可の種類によって決まります。
管理者がアプリケーションに対して定義した範囲によって、アプリケーションが得られる最大レベルのアクセス権が決まります。開発者がこの定義済みのスコープを超えるアクセス権を要求した場合、要求は失敗します。したがって、管理者が定義したスコープで要求することが重要です。
管理者レベルでは、アプリケーションのアクセス許可は以下のとおりです。
-
組織を対象範囲としたアクセス許可: 既定では、外部アプリケーションが登録されると、そのアプリケーションは範囲セットに従って組織全体のリソースにアクセスできます。
-
きめ細かいアクセス許可: より詳細にアクセス許可を設定する場合は、組織管理者が Orchestrator 内のテナント レベルまたはフォルダー レベルで外部アプリにロールを割り当てることができます。ただし、それが可能なのは、機密アプリケーションの場合のみです。
開発者レベルでは、スコープの宣言は次のように行われます。
-
組織を対象範囲としたアクセス許可: トークン要求で
OR.Machines.View
のように範囲を明示的に指定して宣言すると、アプリケーションが組織全体のリソースへのアクセス許可を要求していることになります。 -
きめ細かいアクセス許可: アプリケーションにきめ細かいアクセス権を付与するには、トークン要求で
OR.Default
を宣言する必要があります。OR.Default
はワイルドカード範囲のように機能し、特定のテナントまたはフォルダーで割り当てられたロールに応じて、きめ細かいアクセス権をアプリケーションに付与します。
OR.Machines.View
かつ OR.Default
として宣言できます。この結合された宣言により、外部アプリケーションは、組織全体と、特定の Orchestrator テナントまたはフォルダーの両方で動作することができます。
必要なスコープの値を取得するには、リソースの API ドキュメントのエンドポイントを確認します。以下に例を示します。
この種類の許可の場合、フローは次のようになります。
-
外部アプリケーションは、
client_id
とclient_secret
を含む POST 要求を Identity Server のトークン エンドポイント
に送信することで、アクセス トークンを要求します。https://{yourDomain}/identity
/connect/tokengrant_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}フィールド
説明
client_id
登録時にアプリケーションに割り当てられた一意の識別子を指定します。
アプリ ID (管理者から提供されたもの) を含む必要があります。
client_secret
機密アプリケーションの登録時に提供される機密情報 (パスワードなど) を指定します。このフィールドは、Identity Server への要求が発行される際、client_id
と共に、アプリケーションを認証するために使用されます。アプリ シークレット (管理者から提供されたもの) を含む必要があります。
scope
アプリケーションが要求する範囲を空白で区切って指定します (例:OR.Machines.View OR.Default
)。-
OR.Default
を使用すると、特定のテナントまたはフォルダー内で、制御およびカスタマイズされたアクセス権を付与できます。アプリケーションが実際に得るアクセス許可は、管理者がアプリケーションを割り当てたテナントまたはフォルダーに基づいて決定されます。 -
特定のリソースに対する組織全体の広範なアクセス権を付与するには、
OR.Machines.View
のような明示的な範囲を使用します。
-
-
外部アプリケーションが、下記のようなアクセス トークンを含む応答を受信します。アプリケーションはアクセス トークンを使用して、その期限が切れるまで (1 時間) ユーザー リソースにアクセスできます。
{ "access_token":"{access_token}", "expires_in":3600, "token_type":"Bearer", "scope":"{scopes}" }
{ "access_token":"{access_token}", "expires_in":3600, "token_type":"Bearer", "scope":"{scopes}" }
認可コードを利用した OAuth フローについて詳しくは、RFC 6749 のドキュメントをご覧ください。
application/x-www-form-urlencoded
を使用します。アプリケーションはアクセス トークンを使用して、その期限が切れるまで (1 時間) ユーザー リソースにアクセスできます。
ユーザー スコープを持つ非機密アプリケーションの場合は、PKCE フローを使用して認可コードを実行します。PKCE の認可コードを利用する OAuth フローについて詳しくは、RFC 7636 のドキュメントをご覧ください。
この種類の許可の場合、フローは次のようになります。
-
外部アプリケーションは認可リクエストを送信して、
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
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オプション
説明
client_id
登録時にアプリケーションに割り当てられた一意の識別子を指定します。
アプリ ID (管理者から提供されたもの) を含む必要があります。
scope
アプリケーションが要求するスコープを空白で区切って指定します (例:OR.Machines.View
)。redirect_uri
認可コードの許可後に UiPath Identity Server が認可要求をリダイレクトする URL を指定します。
code_challenge_method
code_challenge
のcode_verifier
のエンコードに使用するメソッドを指定します。このフィールドの値は S256 である必要があります。つまり、SHA256 を使用してcode_verifier
をハッシュし、base64url でエンコードしてcode_challenge
を作成する必要があります。code_challenge
code_verifier
から派生した、暗号化されたランダムな文字列で、認可要求をトークン要求に関連付けるために使用します。code_challenge を生成するには、code_verifier のアルゴリズムを使用する必要があります。rfc7636 規格に準拠していれば、独自に作成することも可能です。
-
https://{identity_baseURL}/connect/token
への POST トークン要求では、要求本文にcode_verifier
(code_challenge
の生成に使用した元の文字列) を含める必要があります。応答には、アプリケーションがユーザー リソースにアクセスするために使用できるアクセス トークンが含まれます。このトークンは期限が切れるまで (1 時間) 使用できます。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 時間) そのトークンを使用して、選択されたスコープ内に限り、許可されたリソースにアクセスできます。
odata/Machines
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"
アクセス トークンの有効期限は 1 時間です。 外部アプリケーションは、更新トークンを交換することで、ユーザーの操作なしで新しいアクセス トークンを取得できます。 機密外部アプリケーションと非機密外部アプリケーションの両方が更新トークンを要求できます。 ただし、クライアント資格情報フローでは更新トークンはサポートされていません。 クライアント資格情報フローでは、アクセス トークンは更新トークンなしで直接付与されます。 クライアントが新しいトークンを必要とする場合は、資格情報を使用して再認証する必要があります。
更新トークンも 1 回の使用に対してのみ有効で、60 日後に期限が切れます。
scope
パラメーターにoffline_access
を含めて、更新トークンを取得するためのトークン要求内で認可コードを使用できるようにする必要があります。
認可コードを含む POST 要求を以下のトークン エンドポイントに送信します。
https://{yourDomain}/identity/connect/token
です。
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
に送信します。
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}"
}
client_secret
パラメーターを削除します。
要求により、新しいアクセス トークンと新しい更新トークンが返されます。
既存の更新トークンは使用後に無効になるため、受信した新しい更新トークンを使用していることを確認してください。
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 にする必要がありますのでご注意ください。
|