Externe Anwendungen (OAuth)

Als Entwickler, der an der Integration von UiPath-Produkten mit externen Anwendungen arbeitet, sind Sie für Aufgaben wie die Verwaltung von Scope-Änderungen, die Verwaltung von Zugriffs- und Aktualisierungs-Tokens und die Pflege der Integration zwischen der externen App und UiPath-Ressourcen verantwortlich. Die folgende Anleitung führt Sie durch diese Vorgänge.

Bei OAuth finden Sie eine Reihe von Bibliotheken, die Sie zur Vereinfachung der Authentifizierung, Autorisierung, Delegation und Sicherung von API-Aufrufen nutzen können. Sie können direkt über die offizielle OAuth-Website auf diese Ressourcen zugreifen.

Voraussetzungen

Sobald der Organisationsadministrator Ihre externe Anwendung in UiPath registriert hat, müssen Sie als Entwickler die Registrierungsdetails erhalten, um Ihre externe App bei den UiPath-Ressourcen zu authentifizieren.

• Der App-Typ und die App-ID. Wenn Sie mit einer vertraulichen Anwendung arbeiten, benötigen Sie auch den geheimen App-Schlüssel. Diese werden verwendet, um Ihre App beim UiPath Identity Server zu authentifizieren, dem Autorisierungsserver für den Zugriff auf UiPath-Ressourcen, der das OAuth 2.0-Framework unterstützt.

• Darüber hinaus müssen Sie die externen App-Scopes kennen, die definieren, auf welche Ressourcen Ihre externe App in UiPath zugreifen kann. Dies umfasst sowohl die Ressourcenspezifikation (wie Assets, Prozesse, etc.) als auch die Berechtigungsstufe (lesen, schreiben, bearbeiten, etc.).

Authentifizierung und Autorisierung externer Apps

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

Fordern Sie während dieses Prozesses ein Zugriffstoken an, indem Sie den Scope der externen App und die Anmeldeinformationen der registrierten App – die App-ID (und bei vertraulichen Anwendungen das App-Geheimnis) – an den Identity Server bereitstellen. Wenn die Anmeldeinformationen gültig sind, reagiert der Identity Server mit der Ausgabe eines Autorisierungscodes, der zum Generieren des Zugriffstokens verwendet wird.

Der zu verwendende Typ der Berechtigungserteilung

Anwendungstyp	Umfang	Erforderlicher Gewährungstyp
vertraulich	Anwendung	Client-Anmeldeinformationen
vertraulich	Benutzer	Authorisierungscode
vertraulich	Anwendung und Benutzer	Client-Anmeldeinformationen und Autorisierungscode
nicht vertraulich	Benutzer	Autorisierungscode mit PCKE

Hinweis:

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.

Deklarieren von Scopes

Der Scope, den der Administrator für eine Anwendung definiert, bestimmt die maximale Zugriffsebene, die die Anwendung erreichen kann. Wenn Sie als Entwickler Zugriff über diesen vordefinierten Scope hinaus anfordern, wird Ihre Anforderung fehlschlagen. Daher ist es wichtig, sicherzustellen, dass sich Ihre Anforderungen innerhalb des vom Administrator definierten Scope befinden.

Auf der Administrator-Ebene können die Berechtigungen der Anwendung Folgende sein:

• Organisationsbezogene Berechtigungen: Wenn eine externe Anwendung registriert ist, hat sie standardmäßig organisationsweiten Zugriff auf die Ressourcen gemäß den festgelegten Scopes.

• Detaillierte Berechtigungen: Für detailliertere Berechtigungseinstellungen kann der Organisationsadministrator der externen App eine Rolle auf Mandanten- oder Ordnerebene im Orchestrator zuweisen. Das gilt jedoch nur für vertrauliche Anwendungen.

Auf Entwicklerebene erfolgt das Deklarieren von Scopes wie folgt:

• Organisationsbezogene Berechtigungen: Wenn Sie einen explizit angegebenen Scope wie OR.Machines.View in der Tokenanforderung deklarieren, impliziert dies, dass die Anwendung eine organisationsweite Zugriffsberechtigung anfordert.
• Detaillierte Berechtigungen: Um Ihrer Anwendung differenzierten Zugriff zu gewähren, müssen Sie OR.Default in der Tokenanforderung deklarieren. OR.Default fungiert wie ein Platzhalter-Scope und bietet Ihrer Anwendung einen fein abgestuften Zugriff, der von der ihr zugewiesenen Rolle in bestimmten Mandanten oder Ordnern abhängt.

Nehmen wir zum Beispiel an, Sie möchten, dass Ihre Anwendung einen organisationsweiten Zugriff auf alle Maschinen sowie exklusive Berechtigungen auf einer detaillierteren Ebene innerhalb definierter Mandanten und Ordner hat. In diesem Fall können Sie die Scopes als OR.Machines.View und OR.Default deklarieren. Diese kombinierte Deklaration ermöglicht es Ihrer externen Anwendung, sowohl auf organisationsweiter Ebene als auch in bestimmten Orchestrator-Mandanten oder -Ordnern zu arbeiten.

Überprüfen Sie den Endpunkt in der API-Dokumentation der Ressource, um die benötigten Scope-Werte abzurufen. Zum Beispiel:

Vertrauliche Apps mit Benutzer-Scopes (Autorisierungscode-Flow)

Für vertrauliche externe Apps mit Benutzer-Scopes führen Sie den Autorisierungscode-Flow gegen den Identity Server aus.

Das Diagramm zeigt den Flow des OAuth-Autorisierungscodes. Der Client fordert die Autorisierung vom Identity Server an. Der Benutzer wird dann aufgefordert, sich anzumelden. Bei Erfolg stellt Identity Server den Autorisierungscode bereit. Der Client verwendet diesen Code und den geheimen Clientschlüssel, um ein Zugriffstoken abzurufen. Mit dem verifizierten Token ist der Zugang zu API-Ressourcen möglich.

Eine detaillierte Beschreibung des OAuth-Flows unter Verwendung von Autorisierungscodes finden Sie im Dokument RFC 6749.

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

1. Die externe Anwendung sendet eine Autorisierungsanforderung, um den Autorisierungscode an den Autorisierungsendpunkt https://govcloud.uipath.us/{organizationName}/{tenantName}/identity_/connect/authorize? des Identity Servers zu erhalten:

   response_type=code&acr_values={value}&client_id={app_id}&scope={scopes}&redirect_uri={redirect_url}

   Option	Beschreibung
   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	Gibt den eindeutigen Bezeichner an, der der Anwendung während der Registrierung zugewiesen wurde. Muss die App-ID enthalten (wie vom Administrator bereitgestellt).
   client_secret	Gibt eine vertrauliche Information an, z. B. ein Kennwort, das vertraulichen Anwendungen bei ihrer Registrierung bereitgestellt wird. Dieses Feld wird zusammen mit der client_id verwendet, um die Anwendung zu authentifizieren, wenn sie Anforderungen an den Identity Server ausstellt. Muss den geheimen App-Schlüssel enthalten (wie vom Administrator bereitgestellt).
   scope	Gibt die von der Anwendung angeforderten Scopes an, getrennt durch ein Leerzeichen; Beispiel: OR.Machines.View OR.Default. Verwenden Sie OR.Default, um kontrollierten, angepassten Zugriff innerhalb bestimmter Mandanten oder Ordner zu gewähren. Die Berechtigungen, die die Anwendung erhält, richten sich nach den Mandanten oder Ordnern, in denen die Anwendung vom Administrator zugewiesen wurde. Verwenden Sie explizite Scopes wie OR.Machines.View, um umfassenden, organisationsweiten Zugriff auf bestimmte Ressourcen zu gewähren.
   redirect_uri	Enthält die URL, an die der Identity Server die Autorisierungsanforderung weiterleitet, nachdem der Autorisierungscode erteilt wurde.

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. Sie können den Autorisierungscode nur einmal verwenden.
   Beispiel einer Umleitung der Autorisierungsanforderung: {redirect_url}?code={authorization_code}&scope={scopes}
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 https://govcloud.uipath.us/{organizationName}/{tenantName}/identity_/connect/token enthalten.

   grant_type=authorization_code&code={authorization_code}&redirect_uri={redirect_url}&client_id={app_id}&client_secret={app_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}"
   }

Die Anwendung kann das Zugriffstoken verwenden, um auf Benutzerressourcen zuzugreifen, bis das Token abläuft (eine Stunde).

Nicht vertrauliche Apps mit Benutzer-Scopes (Autorisierungscode mit PKCE-Flow)

Für eine nicht vertrauliche Anwendung mit Benutzer-Scopes führen Sie den Autorisierungscode mit PKCE-Flow aus. Eine detaillierte Beschreibung des OAuth-Flows unter Verwendung des Autorisierungscodes mit PKCE finden Sie im Dokument RFC 7636.

Bei diesem Gewährungstyp ist der Ablauf wie folgt:

1. Die externe Anwendung sendet eine Autorisierungsanforderung, um den Autorisierungscode an den Endpunkt https://govcloud.uipath.us/{organizationName}/{tenantName}/identity_/connect/authorize? zu erhalten:

   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

   Option	Beschreibung
   client_id	Gibt den eindeutigen Bezeichner an, der der Anwendung während der Registrierung zugewiesen wurde. Muss die App-ID enthalten (wie vom Administrator bereitgestellt).
   scope	Enthält die von der Anwendung angeforderten Scopes, getrennt durch ein Leerzeichen, zum Beispiel: OR.Machines.View.
   redirect_uri	Spezifiziert die URL, an die der UiPath Identity Server die Autorisierungsanforderung weiterleitet, nachdem der Autorisierungscode erteilt wurde.
   code_challenge_method	Gibt die Methode an, mit der dercode_verifier für die code_challenge codiert wird. Der Wert für dieses Feld muss S256 sein, d. h. der code_verifier sollte mit SHA256 und base64url-codiert werden, um die code_challenge zu erstellen.
   code_challenge	Eine kryptografisch zufällige Zeichenkette, die von code_verifier abgeleitet ist und dazu dient, die Autorisierungsanfrage mit der Tokenanfrage zu verbinden. Sie müssen einen Codeüberprüfungsalgorithmus verwenden, um die Code-Herausforderung zu generieren. Sie können auch Ihre eigene erstellen, sofern sie dem RFC7636-Standard entspricht.

2. In der POST-Tokenanforderung an https://{identity_baseURL}/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).

Vertrauliche Apps mit App-Scopes (Flow der Client-Anmeldeinformationen)

Vertrauliche Anwendungen mit Anwendungs-Scopes führen den Flow der Client-Anmeldeinformationen für den UiPath Identity Server aus.

Das Diagramm zeigt den Flow der OAuth Client-Anmeldeinformationen. Der Client sendet Anmeldeinformationen an den Identity Server und erhält Zugriffstoken. Mit verifiziertem Token wird der Zugriff auf API-Ressourcen bereitgestellt.

Ein detailliertes Verständnis des OAuth-Flows unter Verwendung von Client-Anmeldeinformationen finden Sie im Dokument RFC 6749.

Bei diesem Gewährungstyp ist der Ablauf wie folgt:

1. Die externe Anwendung fordert 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://govcloud.uipath.us/{organizationName}/{tenantName}/identity_/connect/token:

   grant_type=client_credentials&client_id={app_id}&client_secret={app_secret}&scope={scopes}

   Feld	Beschreibung
   client_id	Gibt den eindeutigen Bezeichner an, der der Anwendung während der Registrierung zugewiesen wurde. Muss die App-ID enthalten (vom Administrator bereitgestellt).
   client_secret	Gibt vertrauliche Informationen wie ein Kennwort an, die vertraulichen Anwendungen bei der Registrierung zur Verfügung gestellt werden. Dieses Feld wird zusammen mit der client_id verwendet, um die Anwendung zu authentifizieren, wenn sie Anforderungen an den Identity Server ausstellt. Muss den geheimen App-Schlüssel enthalten (vom Administrator bereitgestellt).
   scope	Enthält die von der Anwendung angeforderten Scopes, getrennt durch ein Leerzeichen, zum Beispiel: OR.Machines.View OR.Default. Verwenden Sie OR.Default, um kontrollierten, angepassten Zugriff innerhalb bestimmter Mandanten oder Ordner zu gewähren. Die tatsächlichen Berechtigungen, die die Anwendung erhält, hängen davon ab, wo die Anwendung innerhalb von Mandanten oder Ordnern vom Administrator zugewiesen wird. Verwenden Sie explizite Scopes wie OR.Machines.View, um umfassenden, organisationsweiten Zugriff auf bestimmte Ressourcen zu gewähren.

2. Die externe Anwendung erhält eine Antwort, die das Zugriffstoken enthält:

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

   Die Anwendung kann das Zugriffstoken verwenden, um auf Benutzerressourcen zuzugreifen, bis das Token abläuft (eine Stunde).

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

Hier ein Beispiel für eine Anforderung an die odata/Machines-API, die ein Zugriffstoken im Autorisierungsheader verwendet, wobei das Zugriffstoken den Scope OR.Machines im Scope-Anspruch enthält.

curl -X GET "https://govcloud.uipath.us/{organizationName}/{tenantName}/orchestrator_/odata/Machines"
  -H "Authorization: Bearer {access_token}" -H  "accept: application/json"

Abrufen eines Aktualisierungstokens

Zugriffstoken laufen nach einer Stunde ab. Die externe Anwendung kann ein neues Zugriffstoken ohne Benutzerinteraktion erhalten, indem ein Aktualisierungstoken dafür ausgetauscht wird. Sowohl vertrauliche als auch nicht vertrauliche externe Anwendungen können ein Aktualisierungstoken anfordern. Der Flow der Client-Anmeldeinformationen unterstützt jedoch keine Aktualisierungstokens. Im Flow der Client-Anmeldeinformationen werden Zugriffstoken direkt ohne Aktualisierungstoken gewährt. Wenn Clients ein neues Token benötigen, müssen sie sich mit ihren Anmeldeinformationen erneut authentifizieren.

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://govcloud.uipath.us/{organizationName}/{tenantName}/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://govcloud.uipath.us/{organizationName}/{tenantName}/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-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.

Identity Server-Schicht	Endpoint	Beschreibung
Erkennung	https://govcloud.uipath.us/{organizationName}/{tenantName}/identity_/.well-known/openid-configuration	Verwenden Sie diesen Endpunkt, um Metadaten zu Ihrer Identity Server-Instanz abzurufen.
Autorisierung	https://govcloud.uipath.us/{organizationName}/{tenantName}/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://govcloud.uipath.us/{organizationName}/{tenantName}/identity_/connect/token	Verwenden Sie diesen Endpunkt, um Token programmgesteuert anzufordern. Für diesen Endpunkt muss der Inhaltstyp application/x-www-form-urlencoded sein.