Orchestrator
2021.10
バナーの背景画像
Orchestrator API ガイド
最終更新日 2023年11月10日

外部アプリに OAuth を使用する

以下の手順は、On-Premises Orchestrator のインストールまたはセルフホストの Orchestrator インストールの環境で UiPath 製品と外部アプリケーションの連携を管理する開発者を対象としたものです。

注: Automation Cloud の Orchestrator クラウド サービスを使用する場合は、代わりに Automation Cloud のドキュメントの「外部アプリケーションを管理する」をご覧ください。
重要:

このページでは、プログラムを使用して Identity Server エンドポイントに要求を送信する手順を説明しています。

Postman や同様のツールを使用して、このページのエンドポイントに要求を送信する場合は、以下を使用する必要があります。

  • コンテンツの種類 application/x-www-form-urlencoded
  • このコンテンツの種類に適した要求構文 (このページで挙げた例の構文とは異なる場合があります)
ヒント:

はじめる前に

  • システム管理者が外部アプリケーションの登録を完了している必要があります。
  • システム管理者から登録の詳細情報を入手する必要があります。

各種の許可を使用する

外部アプリケーションの登録後、許可するスコープに対する適切な許可の種類を使用して、外部アプリケーションに対する適切な認可メカニズムを実装する必要があります。これによって外部アプリケーションはアクセス トークンを取得できるようになります。

認可に使用する許可の種類

アプリケーションの種類

スコープ

必要な許可の種類

機密

ユーザー

認証コード (手順)

機密

アプリケーション

クライアント資格情報 (手順)

非機密

ユーザー

PKCE による認可コード (手順)

注:

機密アプリケーションをユーザーとアプリケーションの両方のスコープに対して許可した場合、両方の種類の許可を実装する必要があります。

Orchestrator のように、ユーザーとアプリケーションの両方のスコープが同名の場合、リソースがユーザー スコープまたはアプリケーション スコープのどちらで呼び出されるかは、使用する許可の種類によって決まります。

UiPath リソースにアクセスするための認可サーバーは UiPath Identity Server であり、OAuth 2.0 フレームワークに対応しています。

認可コード

登録したアプリケーションの種類が機密で、要求のスコープがユーザー の場合、この種類の許可を使用します。

この種類の許可の場合、フローは次のようになります。

  1. 外部アプリケーションは認可コードを取得するために、UiPath Identity Server 認可エンドポイントに認可要求を送信します。
    {BaseURL}/identity/connect/authorize?
    response_type=code&
    client_id={app_id}&
    scope={scopes}&
    redirect_uri={redirect_url}{BaseURL}/identity/connect/authorize?
    response_type=code&
    client_id={app_id}&
    scope={scopes}&
    redirect_uri={redirect_url}
    • {BaseURL}/identity/connect/authorize は、Identity Server の認可エンドポイントです。
    • response_type=code は、アプリケーションが認可コードを要求していることを示します。
    • client_id には、アプリケーション ID ([外部アプリケーション] ページに表示されます) を含める必要があります。
    • scope には、アプリケーションが要求するスコープが空白で区切って列挙されます (例: OR.Machines OR.Robots)。
      注: 必要なスコープの値を取得するには、Swagger でエンドポイントを確認します。以下に例を示します。
    • redirect_uri には、認可コードの許可後に UiPath Identity Server が認可要求をリダイレクトする URL が含まれます。
  2. 認可要求を認証するには、ユーザーが Orchestrator にログインする必要があります。

    次のような場合、要求は失敗します。

    • ユーザーが、外部アプリケーションが登録されたテナントに属していない場合
    • 一部のリソースで、ログインしたユーザーが要求のスコープに対して必要な権限を持っていない場合
  3. 外部アプリケーションが認可コードを受信します。
    認可要求のリダイレクトの例: {redirect_url}?code={authorization_code}&scope={scopes} :fa-info-circle: 認可コードは 1 回だけ使用できます。
  4. 外部アプリケーションが認可コードと認証の詳細情報 (client_idclient_secret) を使用して、UiPath Identity Server からのアクセス トークンを要求します。これらは、トークン エンドポイント {BaseURL}/identity/connect/token への POST 要求の本文に含まれています。
    {
        "grant_type": "authorization_code",
        "code": "{authorization_code}",
        "redirect_uri": "{redirect_url}",
        "client_id": "{app_id}",
        "client_secret": "{app_secret}"
    }{
        "grant_type": "authorization_code",
        "code": "{authorization_code}",
        "redirect_uri": "{redirect_url}",
        "client_id": "{app_id}",
        "client_secret": "{app_secret}"
    }
    Postman や同様のツールを使用している場合は、コンテンツの種類 application/x-www-form-urlencoded を使用します。
    grant_type=authorization_code&code={authorization_code}&redirect_uri={redirect_url}&client_id={app_id}&client_secret={app_secret}grant_type=authorization_code&code={authorization_code}&redirect_uri={redirect_url}&client_id={app_id}&client_secret={app_secret}
    注:
    [外部アプリケーション]機密アプリケーションを登録すると、client_secret が返されます。
    非機密アプリケーションの場合は、client_secret の代わりに、code_challengecode_challenge_method を使用します。
  5. 外部アプリケーションが、下記のようなアクセス トークンを含む応答を受信します。
    {
        "access_token":"{access_token}",
        "expires_in":3600,
        "token_type":"Bearer",
        "scope":"{scopes}"
    }{
        "access_token":"{access_token}",
        "expires_in":3600,
        "token_type":"Bearer",
        "scope":"{scopes}"
    }

これで、アプリケーションはアクセス トークンを使用して、その期限が切れるまで (1 時間) ユーザー リソースにアクセスできるようになりました。詳細については、「アクセス トークンを使用する」と「更新トークンを取得する」をご覧ください。

PKCE による認可コード

登録したアプリケーションの種類が非機密で、要求のスコープがユーザーの場合、この許可の種類を使用します。

フローは認可コードを使用する場合と同じですが、認可要求に以下の要求クエリ パラメーターを含める必要があります。

  • code_challenge_methodS256 に設定する必要があります。
  • 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_idclient_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"lcurl -X GET "{OrchestratorURL}/odata/Machines"
  -H "Authorization: Bearer {access_token}" -H  "accept: application/json"l
注: 使用可能な API については、{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}"
}

要求により、新しいアクセス トークンと新しい更新トークンが返されます。

既存の更新トークンは使用後に無効になるため、受信した新しい更新トークンを使用していることを確認してください。

トラブルシューティング

このページの説明に従って OAuth を正しく設定した後に 401 Unauthorized エラーが発生する場合は、UiPath.Orchestrator.dll.config ファイルを開き、以下の行があることを確認してください。

[add key="IdentityServer.OAuth.Enabled" value="true"/]

この行が見つからない場合は、<appSettings> ノードの下に手動で追加してから、Orchestrator を再起動して変更を適用します。

UiPath Identity Server エンドポイント

Postman や同様のツールを使用している場合は、Identity Server エンドポイントへの要求にはすべて、コンテンツの種類 application/x-www-form-urlencoded を使用します。プログラムを使用して要求を行う場合は、これは必要ありません。
ディスカバリ: {BaseURL}/identity/.well-known/openid-configuration
認可: {BaseURL}/identity/connect/authorize
トークン: {BaseURL}/identity/connect/token

Was this page helpful?

サポートを受ける
RPA について学ぶ - オートメーション コース
UiPath コミュニティ フォーラム
UiPath ロゴ (白)
信頼とセキュリティ
© 2005-2024 UiPath. All rights reserved.