- 基本情報
- 認証
- 外部アプリケーション (OAuth)
- API キー
- ROPC (非推奨)
- 範囲と権限
- プラットフォーム管理 API
外部アプリケーション (OAuth)
These instructions are intended for developers who maintain the integration between UiPath® products and external applications using the UiPath® functionality based on the OAuth framework.
はじめる前に
- 組織管理者が Automation Cloud への外部アプリケーションの登録を完了している必要があります。
- Organization Administrator から登録の詳細情報を入手する必要があります。
外部アプリケーションの登録後、許可するスコープに対する適切な許可の種類を使用して、外部アプリケーションに対する適切な認可メカニズムを実装する必要があります。これによって外部アプリケーションはアクセス トークンを取得できるようになります。
認可に使用する許可の種類
アプリケーションの種類 |
スコープ |
必要な許可の種類 |
---|---|---|
機密 |
ユーザー |
認可コード |
機密 |
アプリケーション |
クライアント資格情報 |
非機密 |
ユーザー |
PKCE による認可コード |
機密アプリケーションをユーザーとアプリケーションの両方のスコープに対して許可した場合、両方の種類の許可を実装する必要があります。
Orchestrator のように、ユーザーとアプリケーションの両方のスコープが同名の場合、リソースがユーザー スコープまたはアプリケーション スコープのどちらで呼び出されるかは、使用する許可の種類によって決まります。
The authorization server for accessing UiPath® resources is the UiPath® Identity Server, which supports the OAuth 2.0 framework.
OR.Default
スコープを要求する必要があります。これにより、アプリケーションは Orchestrator で行われた割り当てをテナント レベルおよびフォルダー レベルで確認できます。その後、アプリケーションは、そのテナントおよびフォルダー内の、アクセス権が付与されているリソースにアクセスできます。
たとえば、外部アプリケーションで組織内のすべてのテナントのジョブとマシンを表示するとします。この場合、きめ細かいアクセス権機能を利用すると、キューを 1 つのフォルダー内に表示するようにアプリケーションを設定することもできます。
OR.Jobs.Read, OR.Machines.Read, OR.Default
を要求する必要があります。これにより、組織内のすべてのテナントのジョブとマシンに対する表示権限に加え、フォルダー内のキューに対する表示権限もアプリに付与されます。ただし、外部アプリにそのフォルダーが割り当てられていて、ロールによって必要な権限が付与されていることが条件です。
登録したアプリケーションの種類が機密で、要求のスコープがユーザー の場合、この種類の許可を使用します。
この種類の許可の場合、フローは次のようになります。
これで、アプリケーションはアクセス トークンを使用して、その期限が切れるまで (1 時間) ユーザー リソースにアクセスできるようになりました。
登録したアプリケーションの種類が非機密で、要求のスコープがユーザーの場合、この許可の種類を使用します。
フローは認可コードを使用する場合と同じですが、認可要求に以下の要求クエリ パラメーターを含める必要があります。
-
code_challenge_method
。S256
に設定する必要があります。 -
code_challenge
。code_verifier から派生した、暗号化されたランダムな文字列で、認可要求をトークン要求に関連付けるために使用します。
code_challenge を生成するには、code_verifier のアルゴリズムを使用する必要があります。rfc7636 規格に準拠していれば、独自に作成することも可能です。
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
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
https://{yourDomain}/identity_/connect/token
への POST トークン要求では、要求本文に code_verifier
(code_challenge
の生成に使用した元の文字列) を含める必要があります。
application/x-www-form-urlencoded
を使用します。
{
"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 のトークン エンドポイント
https://{yourDomain}/identity_/connect/token
に送信することで、アクセス トークンを要求します。
application/x-www-form-urlencoded
を使用します。
{
"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 "https://{yourDomain}/{organizationName}/{tenantName}/orchestrator_/odata/Machines"
-H "Authorization: Bearer {access_token}" -H "accept: application/json"
curl -X GET "https://{yourDomain}/{organizationName}/{tenantName}/orchestrator_/odata/Machines"
-H "Authorization: Bearer {access_token}" -H "accept: application/json"
https://{yourDomain}/{organizationName}/{tenantName}/orchestrator_/swagger/index.html
の Orchestrator API Swagger をご覧ください。
アクセス トークンは 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 にする必要がありますのでご注意ください。
|