- 基本情報
- Swagger 定義
- Orchestrator API の使用例
- プラットフォーム管理 API
外部アプリに OAuth を使用する
以下の手順は、On-Premises Orchestrator のインストールまたはセルフホストの Orchestrator インストールの環境で UiPath 製品と外部アプリケーションの連携を管理する開発者を対象としたものです。
このページでは、プログラムを使用して Identity Server エンドポイントに要求を送信する手順を説明しています。
Postman や同様のツールを使用して、このページのエンドポイントに要求を送信する場合は、以下を使用する必要があります。
- コンテンツの種類
application/x-www-form-urlencoded
- このコンテンツの種類に適した要求構文 (このページで挙げた例の構文とは異なる場合があります)
はじめる前に
- システム管理者が外部アプリケーションの登録を完了している必要があります。
- システム管理者から登録の詳細情報を入手する必要があります。
外部アプリケーションの登録後、許可するスコープに対する適切な許可の種類を使用して、外部アプリケーションに対する適切な認可メカニズムを実装する必要があります。これによって外部アプリケーションはアクセス トークンを取得できるようになります。
認可に使用する許可の種類
機密アプリケーションをユーザーとアプリケーションの両方のスコープに対して許可した場合、両方の種類の許可を実装する必要があります。
Orchestrator のように、ユーザーとアプリケーションの両方のスコープが同名の場合、リソースがユーザー スコープまたはアプリケーション スコープのどちらで呼び出されるかは、使用する許可の種類によって決まります。
UiPath リソースにアクセスするための認可サーバーは UiPath Identity Server であり、OAuth 2.0 フレームワークに対応しています。
登録したアプリケーションの種類が機密で、要求のスコープがユーザー の場合、この種類の許可を使用します。
この種類の許可の場合、フローは次のようになります。
これで、アプリケーションはアクセス トークンを使用して、その期限が切れるまで (1 時間) ユーザー リソースにアクセスできるようになりました。詳細については、「アクセス トークンを使用する」と「更新トークンを取得する」をご覧ください。
登録したアプリケーションの種類が非機密で、要求のスコープがユーザーの場合、この許可の種類を使用します。
フローは認可コードを使用する場合と同じですが、認可要求に以下の要求クエリ パラメーターを含める必要があります。
code_challenge_method
。S256
に設定する必要があります。code_challenge
。code_verifier から派生した、暗号化されたランダムな文字列で、認可要求をトークン要求に関連付けるために使用します。
code_challenge を生成するには、code_verifier のアルゴリズムを使用する必要があります。rfc7636 規格に準拠していれば、独自に作成することも可能です。
{BaseURL}/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
{BaseURL}/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
{BaseURL}/identity/connect/token
への POST トークン要求では、要求本文に code_verifier
(code_challenge
の生成に使用した元の文字列) を含める必要があります。
{
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 時間) 使用できます。詳細については、「アクセス トークンを使用する」と「更新トークンを取得する」をご覧ください。
client_id
と client_secret
を含む POST 要求を Identity Server のトークン エンドポイント {BaseURL}/identity/connect/token
に送信することで、アクセス トークンを要求します。
{
grant_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}"
}
アクセス トークンを取得したアプリケーションは、期限が切れるまで (1 時間) そのトークンを使用して、選択されたスコープ内に限り、許可されたリソースにアクセスできます。
以下に、認可ヘッダーにアクセス トークンを使用した、OData/マシン API に対する要求の例を示します。アクセス トークンのスコープ要求には OR.Machines スコープが含まれます。
curl -X GET "{OrchestratorURL}/odata/Machines"
-H "Authorization: Bearer {access_token}" -H "accept: application/json"l
curl -X GET "{OrchestratorURL}/odata/Machines"
-H "Authorization: Bearer {access_token}" -H "accept: application/json"l
{OrchestratorURL}/swagger/index.html
の Orchestrator API Swagger をご覧ください。
アクセス トークンは 1 時間で期限が切れます。外部アプリケーションは、更新トークンを交換することで、ユーザーの操作なしで新しいアクセス トークンを取得できます。
更新トークンも 1 回の使用に対してのみ有効で、60 日後に期限が切れます。
scope
パラメーターにoffline_access
を含めて、更新トークンを取得するためのトークン要求内で認可コードを使用できるようにする必要があります。
更新トークンを取得するには、認可コードを含む POST 要求をトークン エンドポイント
{BaseURL}/identity/connect/token
.
要求により、次のような新しいアクセス トークンと更新トークンが返されます。
{
"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 要求をトークン エンドポイント {BaseURL}/identity/connect/token
に送信します。
{
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}"
}
要求により、新しいアクセス トークンと新しい更新トークンが返されます。
既存の更新トークンは使用後に無効になるため、受信した新しい更新トークンを使用していることを確認してください。
401 Unauthorized
エラーが発生する場合は、UiPath.Orchestrator.dll.config ファイルを開き、以下の行があることを確認してください。
[add key="IdentityServer.OAuth.Enabled" value="true"/]
<appSettings>
ノードの下に手動で追加してから、Orchestrator を再起動して変更を適用します。
application/x-www-form-urlencoded
を使用します。プログラムを使用して要求を行う場合は、これは必要ありません。
{BaseURL}/identity/.well-known/openid-configuration
{BaseURL}/identity/connect/authorize
{BaseURL}/identity/connect/token