- Erste Schritte
- Authentication
- Scopes und Berechtigungen
- Plattformverwaltungs-APIs
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.
Bevor Sie beginnen:
- Die externe Anwendung muss bereits von einem Organisationsadministrator registriert sein.
- Rufen Sie die Registrierungsdetails vom Organisationsadministrator ab.
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 BerechtigungAssets.View
hinzugefügt wird, erhält sie Anzeigeberechtigungen für Assets im EMEA-Mandanten und Ordner „Finance“.
Damit Entwickler diese externen Apps verwenden können, müssen sie bestimmte Scopes in der Anforderung deklarieren.
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:
-
Eine bestimmte Berechtigung, z. B.
OR.Machines.View
– um alle Maschinen in der Organisation anzuzeigen. -
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. -
Nur
OR.Default
– um detaillierte Berechtigungen ausschließlich in bestimmten Mandanten und Ordnern anzufordern.
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 |
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.
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.
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.
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:
Jetzt kann die Anwendung das Zugriffstoken verwenden, um auf Benutzerressourcen zuzugreifen, bis das Token abläuft (eine Stunde).
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
, dieS256
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
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
https://{yourDomain}/identity_/connect/token
müssen Sie code_verifier
(die ursprüngliche Zeichenfolge, die zum Generieren von code_challenge
verwendet wird) in den Anforderungstext aufnehmen.
application/x-www-form-urlencoded
.
{
"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}"
}
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_id
und das client_secret
enthält, an den Identity Server-Tokenendpunkt sendet:
https://{yourDomain}/identity_/connect/token
.
application/x-www-form-urlencoded
.
{
"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}"
}
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"
curl -X GET "https://{yourDomain}/{organizationName}/{tenantName}/orchestrator_/odata/Machines"
-H "Authorization: Bearer {access_token}" -H "accept: application/json"
https://{yourDomain}/{organizationName}/{tenantName}/orchestrator_/swagger/index.html
.
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.
offline_access
in den scope
-Parameter der Autorisierungsanforderung aufnehmen, damit der Autorisierungscode in einer Tokenanforderung verwendet werden kann, um ein Aktualisierungstoken zu erhalten.
Senden einer POST-Anforderung mit dem Autorisierungscode an den Token-Endpunkt
https://{yourDomain}/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"
}
refresh_token
an den Token-Endpunkt
https://{yourDomain}/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://{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.
|
- Überblick
- Detaillierter Zugriff
- Verwenden der verschiedenen Gewährungstypen
- Detaillierter Zugriff
- Authorization Code
- Autorisierungscode mit PCKE
- Client Credentials
- Verwenden des Zugriffstokens
- Abrufen eines Aktualisierungstokens
- Abrufen eines Aktualisierungstokens
- Abrufen eines neuen Aktualisierungstokens und eines neuen Zugriffstokens
- UiPath® Identity Server Endpoints