- Erste Schritte
- Authentication
- Authentifizierungsmethoden
- Externe Anwendungen (OAuth)
- Scopes und Berechtigungen
- Plattformverwaltungs-APIs
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.
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.).
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.
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 |
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 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.
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:
Eine detaillierte Beschreibung des OAuth-Flows unter Verwendung von Autorisierungscodes finden Sie im Dokument RFC 6749.
application/x-www-form-urlencoded
.Die Anwendung kann das Zugriffstoken verwenden, um auf Benutzerressourcen zuzugreifen, bis das Token abläuft (eine Stunde).
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:
-
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
response_type=code&client_id={app_id}&scope={scopes}&redirect_uri={redirect_url}&code_challenge={cryptographically-random string from code_verifier}&code_challenge_method=S256Option
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 diecode_challenge
codiert wird. Der Wert für dieses Feld muss S256 sein, d. h. dercode_verifier
sollte mit SHA256 und base64url-codiert werden, um diecode_challenge
zu erstellen.code_challenge
Eine kryptografisch zufällige Zeichenkette, die voncode_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.
-
In der POST-Tokenanforderung an
https://{identity_baseURL}/connect/token
müssen Siecode_verifier
(die ursprüngliche Zeichenfolge, die zum Generieren voncode_challenge
verwendet wird) in den Anforderungstext aufnehmen.Die Antwort enthält ein Zugriffstoken, das die Anwendung für den Zugriff auf Benutzerressourcen verwenden kann, bis das Token abläuft (eine Stunde).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}
Bei diesem Gewährungstyp ist der Ablauf wie folgt:
-
Die externe Anwendung fordert ein Zugriffstoken an, indem eine POST-Anforderung, die die
client_id
und dasclient_secret
enthält, an den Identity Server-Tokenendpunkt gesendet wird:
:https://govcloud.uipath.us/{organizationName}/{tenantName}/identity_
/connect/tokengrant_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}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 derclient_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.
-
-
Die externe Anwendung erhält eine Antwort, die das Zugriffstoken enthält:Die Anwendung kann das Zugriffstoken verwenden, um auf Benutzerressourcen zuzugreifen, bis das Token abläuft (eine Stunde).
{ "access_token":"{access_token}", "expires_in":3600, "token_type":"Bearer", "scope":"{scopes}" }
{ "access_token":"{access_token}", "expires_in":3600, "token_type":"Bearer", "scope":"{scopes}" }
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).
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"
curl -X GET "https://govcloud.uipath.us/{organizationName}/{tenantName}/orchestrator_/odata/Machines"
-H "Authorization: Bearer {access_token}" -H "accept: application/json"
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.
offline_access
in den scope
-Parameter der Autorisierungsanforderung aufnehmen, damit der Autorisierungscode in einer Tokenanforderung verwendet werden kann, um ein Aktualisierungstoken zu erhalten.
POST
-Anforderung mit dem Autorisierungscode an den Token-Endpunkt
https://govcloud.uipath.us/{organizationName}/{tenantName}/identity_/connect/token
.
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"
}
{
"access_token": "{access_token}",
"expires_in": 3600,
"token_type": "Bearer",
"refresh_token": "{refresh_token}",
"scope": "OR.Machines OR.Robots offline_access"
}
POST
-Anforderung mit dem Gewährungstyp refresh_token
an den Token-Endpunkt https://govcloud.uipath.us/{organizationName}/{tenantName}/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
-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.
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.
|
- Voraussetzungen
- Authentifizierung und Autorisierung externer Apps
- Der zu verwendende Typ der Berechtigungserteilung
- Deklarieren von Scopes
- Vertrauliche Apps mit Benutzer-Scopes (Autorisierungscode-Flow)
- Nicht vertrauliche Apps mit Benutzer-Scopes (Autorisierungscode mit PKCE-Flow)
- Vertrauliche Apps mit App-Scopes (Flow der Client-Anmeldeinformationen)
- Verwenden des Zugriffstokens
- Abrufen eines Aktualisierungstokens
- Abrufen eines Aktualisierungstokens
- Abrufen eines neuen Aktualisierungstokens und eines neuen Zugriffstokens
- UiPath® Identity Server-Endpunkte