Verwenden von OAuth für externe Apps

Diese Anweisungen richten sich an Entwickler, die die Integration zwischen UiPath-Produkten und externen Anwendungen in einer Umgebung mit einer lokalen Orchestrator-Installation oder einer selbst gehosteten Orchestrator-Installation aufrechterhalten.

Hinweis: Wenn Sie den Orchestrator Cloud-Dienst in der Automation Cloud verwenden, siehe stattdessen Verwalten externer Anwendungen in der Automation Cloud-Dokumentation.

Wichtig:

Die Anweisungen auf dieser Seite gelten für das programmgesteuerte Senden von Anforderungen an Identity Server-Endpunkte.

Wenn Sie Postman oder ein ähnliches Tool verwenden, um Anforderungen an die Endpunkte auf dieser Seite zu stellen, müssen Sie Folgendes verwenden:

• der Inhaltstyp application/x-www-form-urlencoded
• die entsprechende Anforderungssyntax für diesen Inhaltstyp, die sich von der Syntax in den Beispielen auf dieser Seite unterscheiden kann.

Tipp:

Bevor Sie beginnen:

• Die externe Anwendung muss bereits von einem Systemadministrator in Externe Anwendungen registriert sein.
• Rufen Sie die Registrierungsdetails vom Systemadministrator ab.

Verwenden der verschiedenen Gewährungstypen

Nachdem die externe Anwendung registriert wurde, müssen Sie den entsprechenden Autorisierungsmechanismus für die externe Anwendung mit dem entsprechenden Gewährungstyp für den zulässigen Scope implementieren, damit die externe Anwendung ein Zugriffstoken abrufen kann.

Welcher Berechtigungs-Gewährungstyp verwendet werden soll:

Anwendungstyp	Umfang	Erforderlicher Gewährungstyp
vertraulich	Benutzer	Autorisierungscode (Anweisungen)
vertraulich	Anwendung	Client-Anmeldeinformationen (Anweisungen)
nicht vertraulich	Benutzer	Autorisierungscode mit PKCE (Anweisungen)

Hinweis:

Wenn einer vertraulichen Anwendung sowohl Benutzer- als auch Anwendungs-Scopes gewährt wurden, müssen Sie beide Gewährungstypen implementieren.

Wenn der Scope-Name sowohl unter Benutzer- als auch Anwendungs-Scopes derselbe ist wie im Fall vom Orchestrator, bestimmt der von Ihnen verwendete Gewährungstyp, ob die Ressource unter dem Benutzer-Scope oder unter dem Anwendungs-Scope aufgerufen wird.

Der Autorisierungsserver für den Zugriff auf UiPath-Ressourcen ist der UiPath Identity Server, der das OAuth 2.0-Framework unterstützt.

Authorization Code

Verwenden Sie diesen Gewährungstyp, wenn die registrierte Anwendung vom Typ vertraulich ist und die Anforderung für den Benutzer-Scope gilt.

Bei diesem Gewährungstyp ist der Ablauf wie folgt:

1. Die externe Anwendung sendet eine Autorisierungsanforderung an den UiPath Identity Server-Endpunkt, um den Autorisierungscode abzurufen.

   {BaseURL}/identity/connect/authorize?
   response_type=code&
   client_id={app_id}&
   scope={scopes}&
   redirect_uri={redirect_url}

   • {BaseURL}/identity/connect/authorize ist der Identity Server-Autorisierungsendpunkt.
   • response_type=code gibt an, dass die Anwendung einen Autorisierungscode anfordert.
   • client_id muss die Anwendungs-ID enthalten (zu sehen auf der Seite Externe Anwendungen).
   • scope: enthält die von der Anwendung angeforderten Scopes, getrennt durch ein Leerzeichen, zum Beispiel: OR.Machines OR.Robots.
     Hinweis: Überprüfen Sie den Endpunkt im Swagger, um die benötigten Scope-Werte abzurufen. Zum Beispiel:

     
   • redirect_uri enthält die URL, an die der UiPath Identity Server die Autorisierungsanforderung umleitet, nachdem der Autorisierungscode gewährt wurde.
2. Ein Benutzer muss sich beim Orchestrator anmelden, um die Autorisierungsanforderung zu authentifizieren.

   Die Anforderung schlägt fehl, wenn:

   • der Benutzer nicht in dem Mandanten ist, in dem die externe Anwendung registriert wurde.
   • der angemeldete Benutzer nicht über die erforderlichen Berechtigungen für den Scope der Anforderung verfügt (bei einigen Ressourcen).
3. Die externe Anwendung erhält den Autorisierungscode.
   Beispiel für eine Umleitung einer Autorisierungsanforderung: {redirect_url}?code={authorization_code}&scope={scopes} :fa-info-circle: Sie können den Autorisierungscode nur einmal verwenden.
4. Die externe Anwendung fordert ein Zugriffstoken vom UiPath Identity Server mithilfe des Autorisierungscodes und der Authentifizierungsdetails an (client_id und client_secret). Diese sind im Textkörper einer POST-Anforderung an den Tokenendpunkt {BaseURL}/identity/connect/token enthalten.

   {
       "grant_type": "authorization_code",
       "code": "{authorization_code}",
       "redirect_uri": "{redirect_url}",
       "client_id": "{app_id}",
       "client_secret": "{app_secret}"
   }

   Wenn Sie Postman oder ein ähnliches Tool verwenden, verwenden Sie den Inhaltstyp application/x-www-form-urlencoded:

   grant_type=authorization_code&code={authorization_code}&redirect_uri={redirect_url}&client_id={app_id}&client_secret={app_secret}

   Hinweis:

   client_secret wird zurückgegeben, nachdem eine vertrauliche Anwendung in Externe Anwendungenregistriert wurde.

   Verwenden Sie für eine nicht vertrauliche Anwendung code_challenge und code_challenge_method anstelle des client_secret.
5. Die externe Anwendung erhält eine Antwort, die das Zugriffstoken enthält, z. B.:

   {
       "access_token":"{access_token}",
       "expires_in":3600,
       "token_type":"Bearer",
       "scope":"{scopes}"
   }

Jetzt kann die Anwendung das Zugriffstoken verwenden, um auf Benutzerressourcen zuzugreifen, bis das Token abläuft (eine Stunde). Weitere Informationen finden Sie unter Verwenden des Zugriffstokens und Abrufen eines Aktualisierungstokens.

Autorisierungscode mit PCKE

Verwenden Sie diesen Gewährungstyp, wenn die registrierte Anwendung vom Typ nicht vertraulich ist und die Anforderung für den Benutzer-Scope gilt.

Der Ablauf ist derselbe wie bei der Verwendung des Autorisierungscodes: Mit Ausnahme der Autorisierungsanforderung müssen Sie die folgenden Abfrageparameter der Anforderung einschließen:

• code_challenge_method, die S256 sein muss
• code_challenge ist eine kryptografisch zufällige Zeichenfolge, die vom code_verifier abgeleitet ist und verwendet wird, um die Autorisierungsanforderung mit der Tokenanforderung zu verbinden.

Sie müssen einen Codeüberprüfungsalgorithmus verwenden, um die Codeabfrage zu generieren. Sie können auch Ihre eigene erstellen, sofern sie dem RFC7636-Standard entspricht.

{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

In der POST-Tokenanforderung an {BaseURL}/identity/connect/token müssen Sie code_verifier (die ursprüngliche Zeichenfolge, die zum Generieren von code_challengeverwendet wird) in den Anforderungstext aufnehmen.

{ 
    grant_type: "authorization_code" 
    code: "{authorization_code}" 
    redirect_uri: "{redirect_url}" 
    client_id: "{app_id}" 
    code_verifier: "{code_verifier}" 
}

Die Antwort enthält ein Zugriffstoken, das die Anwendung für den Zugriff auf Benutzerressourcen verwenden kann, bis das Token abläuft (eine Stunde). Weitere Informationen finden Sie unter Verwenden des Zugriffstokens und Abrufen eines Aktualisierungstokens.

Client Credentials

Für vertrauliche Anwendungen zum Zugriff auf den Anwendungs-Scope fordert die externe Anwendung ein Zugriffstoken an, indem sie eine POST-Anforderung, die die client_id und das client_secret enthält, an den Identity Server-Tokenendpunkt sendet: {BaseURL}/identity/connect/token.

{
    grant_type: "client_credentials"
    client_id: "{app_id}"
    client_secret: "{app_secret}"
    scope: "{scopes}"
}

Verwenden des Zugriffstokens

Sobald die Anwendung über ein Zugriffstoken verfügt, kann sie das Token verwenden, um auf zulässige Ressourcen zuzugreifen (auf die ausgewählten Scopes beschränkt), bis das Token abläuft (eine Stunde).

Dies ist eine Beispielanforderung an die odata/Machines-API, die ein Zugriffstoken im Autorisierungsheader verwendet, in dem das Zugriffstoken den Scope „OR.Maschines“ in der Scope-Anforderung enthält.

curl -X GET "{OrchestratorURL}/odata/Machines"
  -H "Authorization: Bearer {access_token}" -H  "accept: application/json"l

Hinweis: Informationen zu den verfügbaren APIs finden Sie im Orchestrator API-Swagger unter {OrchestratorURL}/swagger/index.html.

Abrufen eines Aktualisierungstokens

Zugriffstoken laufen nach einer Stunde ab. Die externe Anwendung kann ein neues Zugriffstoken ohne Benutzerinteraktion erhalten, indem ein Aktualisierungstoken im Austausch dafür verwendet wird.

Aktualisierungstokens sind auch für nur eine Verwendung gültig und laufen nach 60 Tagen ab.

Sowohl vertrauliche als auch nicht vertrauliche externe Anwendungen können ein Aktualisierungstoken anfordern. Dazu müssen sie offline_access in den scope-Parameter der Autorisierungsanforderung aufnehmen, damit der Autorisierungscode in einer Tokenanforderung verwendet werden kann, um ein Aktualisierungstoken zu erhalten.

Um ein Aktualisierungstoken abzurufen, senden Sie eine POST-Anforderung mit dem Autorisierungscode an den Tokenendpunkt.

{BaseURL}/identity/connect/token.

Die Anforderung gibt ein neues Zugriffstoken und ein Aktualisierungstoken zurück:

{ 
    "access_token": "{access_token}", 
    "expires_in": 3600, 
    "token_type": "Bearer", 
    "refresh_token": "{refresh_token}", 
    "scope": "OR.Machines OR.Robots offline_access" 
}

Um ein neues Aktualisierungstoken und ein neues Zugriffstoken abzurufen, senden Sie eine POST-Anforderung an den Tokenendpunkt {BaseURL}/identity/connect/token mit dem Gewährungstyp refresh_token.

{
    grant_type: "refresh_token"
    client_id: "{app_id}"
    client_secret: "{app_secret}"
    refresh_token: "{existing_refresh_token}"
}

Als Antwort wird ein neues Zugriffstoken und ein Aktualisierungstoken zurückgegeben:

Das vorhandene Aktualisierungstoken ist nach der Verwendung nicht mehr gültig, also stellen Sie sicher, dass Sie das neue Aktualisierungstoken verwenden, das Sie erhalten haben.

Fehlersuche und ‑behebung

Wenn nach der korrekten Konfiguration von OAuth wie auf dieser Seite beschrieben ein 401 Unauthorized -Fehler auftritt, öffnen Sie Ihre Datei UiPath.Orchestrator.dll.config und überprüfen Sie, ob Sie die folgende Zeile finden:

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

Wenn Sie ihn nicht finden können, fügen Sie ihn manuell unter dem Knoten <appSettings> hinzu und starten Sie den Orchestrator neu, damit die Änderung übernommen wird.

UiPath Identity Server-Endpunkte

Wenn Sie Postman oder ein ähnliches Tool verwenden, verwenden Sie den Inhaltstyp application/x-www-form-urlencoded für alle Anforderungen an Identity Server-Endpunkte. Wenn Sie Anforderungen programmatisch stellen, ist dies nicht erforderlich.

Erkennung: {BaseURL}/identity/.well-known/openid-configuration

Autorisierung: {BaseURL}/identity/connect/authorize

Token: {BaseURL}/identity/connect/token