Externe Anwendungen (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.

Tipp:

Bevor Sie beginnen:

• Die externe Anwendung muss bereits von einem Organisationsadministrator registriert sein.
• Rufen Sie die Registrierungsdetails vom Organisationsadministrator ab.

Überblick

Anwendungen, die sich außerhalb der UiPath Platform befinden, können Zugriff auf UiPath-Ressourcen erhalten, ohne dass Benutzeranmeldeinformationen freigegeben werden müssen. Mit dem OAuth-Framework können Organisationsadministratoren die Autorisierung an externe Anwendungen delegieren. Nach der Registrierung können diese Anwendungen API-Aufrufe an UiPath-Anwendungen oder -Ressourcen senden, die Sie in den Registrierungs-Scope aufnehmen.

Als Administrator zum Definieren externer App-Scopes auf:

• Organisationsebene (Administrator > Externe Apps > OAuth) – Sie weisen Berechtigungen zu, z. B. OR.Machines.Read – Das gewährt Lesezugriff auf die Maschinen in allen Mandanten der Organisation.

• Mandantenebene (Orchestrator > Mandant > Zugriff verwalten) oder Ordnerebene (Orchestrator > Ordner > Einstellungen > Zugriff verwalten) – Sie fügen die App dem gewünschten Mandanten oder Ordner hinzu und weisen ihr eine Rolle zu. Mit dieser Aktion werden detailliertere Scopes konfiguriert.

  Wenn eine App beispielsweise zum EMEA-Mandanten, Ordner „Finance“ mit der Berechtigung Assets.View hinzugefügt wird, erhält sie Anzeigeberechtigungen für Assets im EMEA-Mandanten und Ordner „Finance“.

Hinweis:

Damit Entwickler diese externen Apps verwenden können, müssen sie bestimmte Scopes in der Anforderung deklarieren.

Detaillierter Zugriff

Je nach den Berechtigungen, mit denen eine externe Anwendung registriert wurde, müssen Entwickler bestimmte Scopes deklarieren, um sie verwenden zu können. Es gibt drei mögliche Optionen:

1. Eine bestimmte Berechtigung, z. B. OR.Machines.View – um alle Maschinen in der Organisation anzuzeigen.
2. Eine Kombination aus einer bestimmten Berechtigung und OR.Default, z. B. OR.Machines.View +OR.Default – um die Anzeige von Maschinen in der gesamten Organisation anzufordern und nach detaillierten Berechtigungen in bestimmten Mandanten und Ordnern zu suchen.
3. Nur OR.Default – um detaillierte Berechtigungen ausschließlich in bestimmten Mandanten und Ordnern anzufordern.

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	Authorisierungscode
vertraulich	Anwendung	Client-Anmeldeinformationen
nicht vertraulich	Benutzer	Autorisierungscode mit PCKE

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.

The authorization server for accessing UiPath® resources is the UiPath® Identity Server, which supports the OAuth 2.0 framework.

Detaillierter Zugriff

Für vertrauliche Anwendungen mit detailliertem Zugriff, der über den Orchestrator konfiguriert wurde, müssen Sie den Scope OR.Default anfordern, der es der Anwendung ermöglicht, auf Mandanten- und Ordnerebene nach Zuweisungen zu suchen, die im Orchestrator vorgenommen wurden. Die Anwendung kann dann auf die Ressourcen zugreifen, auf die sie in diesen Mandanten und Ordnern Zugriff hat.

Sie möchten beispielsweise, dass eine externe Anwendung Aufträge und Maschinen für alle Mandanten in der Organisation anzeigt. Durch die Nutzung der detaillierten Zugriffsfunktionalität können Sie die Anwendung auch so konfigurieren, dass Warteschlangen in einem Ordner angezeigt werden.

Um das Zugriffstoken für Ihre externe App in diesem Szenario abzurufen, sollten Sie die folgenden Scopes anfordern: OR.Jobs.Read, OR.Machines.Read, OR.Default. Dadurch werden Ihrer App Anzeigeberechtigungen für Aufträge und Maschinen für alle Mandanten in der Organisation und auch Anzeigen für Warteschlangen im Ordner erteilt, sofern ihr die externe App zugewiesen und die erforderlichen Berechtigungen über eine Rolle erteilt wurden.

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. The external application sends an authorize request to the UiPath® Identity Server authorize endpoint to get the authorization code.

   https://{yourDomain}/identity_/connect/authorize?
   response_type=code&
   acr_values={value}&
   client_id={app_id}&
   scope={scopes}&
   redirect_uri={redirect_url}

   Option	Beschreibung
   https://{yourDomain}/identity_/connect/authorize	Der Autorisierungsendpunkt des Identity Servers.
   response_type=code	Gibt an, dass die Anwendung einen Autorisierungscode anfordert.
   acr_values	Hiermit kann Identity Server eine Authentifizierungsrichtlinie auf Grundlage der Organisation anwenden, zu der der Benutzer gehört. Kann unterschiedliche Werte annehmen: acr_values=tenant:{target organization GlobalId} – Die Organisations-ID dient als ACR-Wert. acr_values=tenantName:{target organization name} – Der Organisationsname fungiert als ACR-Wert.
   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 in der API-Dokumentation der Ressource, um die benötigten Scope-Werte abzurufen. Zum Beispiel:
   redirect_uri	Contains the URL where UiPath® Identity Server redirects the authorize request after the authorization code is granted.

2. A user must log in to authenticate the authorize request.

   Die Anforderung schlägt fehl, wenn:

   • der Benutzer nicht in der Organisation ist, in der 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} Sie können den Autorisierungscode nur einmal verwenden.
4. The external application requests an access token from UiPath® Identity Server using the authorization code and authentication details (client_id and client_secret). These are included in the body of a POST request to the token endpoint https://{yourDomain}/identity_/connect/token.

   {
       "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).

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 eines Autorisierungscodes, mit der Ausnahme, dass Sie in die Autorisierungsanforderung die folgenden Anforderungsabfrageparameter aufnehmen müssen:

• 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 Ihren eigenen erstellen, sofern er dem RFC7636-Standard entspricht.

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

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

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}", 
    "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: https://{yourDomain}/identity_/connect/token.

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

{
    "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 "https://{yourDomain}/{organizationName}/{tenantName}/orchestrator_/odata/Machines"
  -H "Authorization: Bearer {access_token}" -H  "accept: application/json"

Hinweis: Informationen zu den verfügbaren APIs finden Sie im Orchestrator API-Swagger unter https://{yourDomain}/{organizationName}/{tenantName}/orchestrator_/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. Sowohl vertrauliche als auch nicht vertrauliche externe Anwendungen können ein Aktualisierungstoken anfordern.

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

Um ein Aktualisierungstoken anzufordern, 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.

Abrufen eines Aktualisierungstokens

Senden einer POST-Anforderung mit dem Autorisierungscode an den Token-Endpunkt

https://{yourDomain}/identity_/connect/token.

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

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" 
}

Abrufen eines neuen Aktualisierungstokens und eines neuen Zugriffstokens

Senden Sie eine POST-Anforderung mit dem Gewährungstyp refresh_token an den Token-Endpunkt https://{yourDomain}/identity_/connect/token.

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

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

Hinweis: Wenn die externe Anwendung nicht vertraulich ist und den Autorisierungscode mit dem PKCE-Gewährungstyp verwendet, entfernen Sie den client_secret-Parameter aus dem Anforderungstext.

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.

UiPath® Identity Server Endpoints

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.

Identity Server-Schicht	Endpoint	Beschreibung
Erkennung	https://{yourDomain}/identity_/.well-known/openid-configuration	Verwenden Sie diesen Endpunkt, um Metadaten zu Ihrer Identity Server-Instanz abzurufen.
Autorisierung	https://{yourDomain}/identity_/connect/authorize	Verwenden Sie diesen Endpunkt, um Token oder Autorisierungscodes über den Browser anzufordern. Dieser Prozess umfasst die Authentifizierung des Endbenutzers und optional die Zustimmung.
Token	https://{yourDomain}/identity_/connect/token	Verwenden Sie diesen Endpunkt, um Token programmgesteuert anzufordern. Für diesen Endpunkt muss der Inhaltstyp application/x-www-form-urlencoded sein.