Applications externes (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.

Astuce :

Avant de commencer :

• L'application externe doit déjà être enregistrée par un administrateur de l'organisation.
• Obtenez les détails d'enregistrement auprès de l'administrateur de l'organisation.

Vue d'ensemble (Overview)

Les applications externes à la plate-forme UiPath peuvent se voir accorder l’accès aux ressources UiPath sans avoir à partager les informations d’identification de l’utilisateur. À l’aide de l’infrastructure OAuth, les administrateurs de l’organisation peuvent déléguer l’autorisation à des applications externes. Une fois enregistrées, ces applications peuvent effectuer des appels d’API vers les applications UiPath ou les ressources que vous incluez dans l’étendue de l’enregistrement.

En tant qu'administrateur, pour définir les étendues d'applications externes :

• au niveau de l'organisation (Admin > Applications externes > OAuth), vous lui attribuez des autorisations telles que OR.Machines.Read - cela permet d'accorder un accès en lecture aux machines de tous les locataires de l'organisation.

• au niveau du locataire (Orchestrator > Locataire > Gérer l'accès) ou du dossier (Orchestrator > Dossier > Paramètres > Gérer l'accès) - vous ajoutez l'application au locataire ou au dossier souhaité en lui attribuant un rôle. Cette action permet de configurer des étendues plus précises.

  Par exemple, si une application est ajoutée dans le dossier Finance du locataire EMEA avec l'autorisation Assets.View, elle obtient les autorisations de consultation des ressources du locataire EMEA dans le dossier Finance.

Remarque :

Pour que les développeurs puissent utiliser ces applications externes, ils doivent indiquer des étendues spécifiques dans la requête.

Accès précis

En fonction des autorisations avec lesquelles une application externe a été enregistrée, les développeurs doivent indiquer des étendues spécifiques pour les utiliser. Il existe trois options :

1. Une autorisation spécifique, telle que OR.Machines.View , pour consulter toutes les machines de l'organisation.
2. Une combinaison entre une autorisation spécifique et OR.Default, par exemple OR.Machines.View + OR.Default, pour demander à consulter les machines sur toute l'organisation et rechercher des autorisations granulaires dans des locataires et des dossiers spécifiques.
3. OR.Default uniquement, pour demander exclusivement des autorisations granulaires dans des locataires et des dossiers spécifiques.

Utilisation des différents types d'accord

Une fois l'application externe enregistrée, vous devez implémenter le mécanisme d'autorisation approprié pour l'application externe, avec le type d'accord approprié pour l'étendue autorisée, afin que l'application externe puisse récupérer un jeton d'accès.

Quel type d'accord d'autorisation utiliser :

Type de demande (Application Type)	Portée	Type d'accord requis
confidentiel	Utilisateur (User)	Code d'autorisation
confidentiel	Application	Informations d’identification du client
non confidentiel	Utilisateur (User)	Code d'autorisation avec PKCE

Remarque :

Si une application confidentielle s'est vu accorder à la fois des étendues d'utilisateur et d'application, vous devez implémenter les deux types d'accord.

Lorsque le nom de l'étendue est le même dans l'étendue de l'utilisateur et de l'application, comme dans le cas d'Orchestrator, le type d'octroi que vous utilisez détermine si la ressource est appelée dans l'étendue de l'utilisateur ou dans l'étendue de l'application.

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

Accès précis

Pour les applications confidentielles avec un accès affiné configuré via Orchestrator, vous devez demander l'étendue OR.Default, qui permet à l'application de vérifier les affectations effectuées dans Orchestrator, aux niveaux du locataire et du dossier. L'application peut ensuite accéder aux ressources auxquelles l'accès lui a été accordé dans ces locataires et dossiers.

Par exemple, vous souhaitez qu'une application externe affiche les tâches et les machines de tous les locataires de l'organisation. En tirant parti de la fonctionnalité accès affiné, vous pouvez également configurer l'application pour qu'elle affiche les files d'attente dans un dossier.

Pour obtenir le jeton d'accès de votre application externe dans ce scénario, vous devez demander les étendues suivantes : OR.Jobs.Read, OR.Machines.Read, OR.Default. Cela accorde à votre application les autorisations Afficher (View) sur les tâches et les machines pour tous les locataires de l'organisation, ainsi que les autorisations Afficher (View) sur les files d'attente dans le dossier, sous réserve que l'application externe lui ait été attribuée et que les autorisations requises aient été accordées à cette application externe via un rôle.

Code d'autorisation

Utilisez ce type d'accord lorsque l'application enregistrée est de type confidentiel et que la demande concerne l' étendue de l'utilisateur.

Avec ce type d'accord, le flux est le suivant :

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	Description
   https://{yourDomain}/identity_/connect/authorize	Le point de terminaison d'autorisation d'Identity Server.
   response_type=code	Spécifie que l'application demande un code d'autorisation.
   acr_values	Permet à Identity Server d'appliquer une politique d'authentification en fonction de l'organisation à laquelle appartient l'utilisateur. Peut avoir différentes valeurs : acr_values=tenant:{target organization GlobalId} : l'ID de l'organisation fait office de valeur ACR. acr_values=tenantName:{target organization name} : le nom de l'organisation fait office de valeur ACR.
   client_id	Doit contenir l'ID de l'application (affiché sur la page Applications externes).
   scope	Contient les étendues demandées par l'application, délimitées par un espace ; par exemple : OR.Machines OR.Robots. Remarque : vérifiez le point de terminaison dans la documentation de l'API de la ressource pour obtenir les valeurs d'étendue dont vous avez besoin. Par exemple :
   redirect_uri	Contains the URL where UiPath® Identity Server redirects the authorize request after the authorization code is granted.

2. Un utilisateur doit se connecter pour authentifier la demande d'autorisation.

   La demande échoue si :

   • l'utilisateur ne fait pas partie de l'organisation où l'application externe a été enregistrée ;
   • pour certaines ressources, l'utilisateur connecté ne dispose pas des autorisations requises pour l'étendue de la demande.
3. L'application externe reçoit le code d'autorisation.
   Exemple de redirection de demande d'autorisation : {redirect_url}?code={authorization_code}&scope={scopes}Vous ne pouvez utiliser le code d'autorisation qu'une seule fois.
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}"
   }

   Si vous utilisez Postman ou un outil similaire, utilisez le type de contenu application/x-www-form-urlencoded :

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

   Remarque :

   Le client_secret est renvoyé après l'enregistrement d'une application confidentielle dans Applications externes ( External Applications).

   Pour une application non confidentielle, utilisez code_challenge et code_challenge_method au lieu de client_secret.
5. L'application externe reçoit une réponse contenant le jeton d'accès, par exemple :

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

L'application peut désormais utiliser le jeton d'accès pour accéder aux ressources utilisateur jusqu'à l'expiration du jeton (une heure).

Code d'autorisation avec PKCE

Utilisez ce type d'accord si l'application enregistrée est de type non confidentielle et que la demande concerne l'étendue de l'utilisateur.

Le flux est le même que lors de l'utilisation du code d'autorisation, mais dans la demande d'autorisation, vous devez inclure les paramètres de requête suivants :

• code_challenge_method, qui doit être S256
• code_challenge, une string à la cryptographie aléatoire dérivée de code_verifier, utilisée pour connecter la demande d'autorisation à la demande de jeton.

Vous devez utiliser un algorithme de vérification de code pour générer le défi de code. Vous pouvez également créer le vôtre, à condition qu'il soit conforme à la norme rfc7636 .

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

Dans la demande de jeton POST à https://{yourDomain}/identity_/connect/token, vous devez inclure code_verifier (la chaîne d'origine utilisée pour générer code_challenge) dans le corps de la demande.

Si vous utilisez Postman ou un outil similaire, utilisez le type de contenu application/x-www-form-urlencoded.

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

La réponse comprend un jeton d'accès que l'application peut utiliser pour accéder aux ressources utilisateur jusqu'à l'expiration du jeton (une heure). Voir Utilisation du jeton d'accès et Obtention d'un jeton de réactualisation pour plus d'informations.

Client Credentials

Pour que les applications confidentielles accèdent à l'étendue de l'application, l'application externe demande un jeton d'accès en envoyant une demande POST qui inclut le client_id et le client_secret au point de terminaison du jeton Identity Server : https://{yourDomain}/identity_/connect/token.

Si vous utilisez Postman ou un outil similaire, utilisez le type de contenu application/x-www-form-urlencoded.

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

Utilisation du jeton d'accès

Une fois que l'application dispose d'un jeton d'accès, elle peut utiliser le jeton pour accéder aux ressources autorisées, limitées aux étendues sélectionnées, jusqu'à l'expiration du jeton (une heure).

Voici un exemple de demande à l'API OData/Machines qui utilise un jeton d'accès dans l'en-tête d'autorisation, où le jeton d'accès contient l'étendue OR.Machines dans la demande d'étendue.

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

Remarque : Consultez l'application Swagger de l'API Orchestrator sur https://{yourDomain}/{organizationName}/{tenantName}/orchestrator_/swagger/index.html pour plus d'informations sur les API disponibles.

Obtention d'un jeton de réactualisation

Les jetons d'accès expirent dans une heure. L'application externe peut obtenir un nouveau jeton d'accès sans interaction de l'utilisateur en lui échangeant un jeton de réactualisation. Les applications externes confidentielles et non confidentielles peuvent demander toutes deux un jeton d'actualisation.

Les jetons de réactualisation sont également valables pour une seule utilisation et ils expirent après 60 jours.

Pour demander un jeton de réactualisation, incluez offline_access dans le paramètre scope de la demande d'autorisation afin que le code d'autorisation puisse être utilisé dans une demande de jeton afin d'obtenir un jeton de réactualisation.

Obtenir un jeton d'actualisation

Envoyer une requête POST avec le code d'autorisation au point de terminaison du jeton

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

Remarque : Si vous utilisez Postman ou un outil similaire, utilisez le type de contenu application/x-www-form-urlencoded.

La requête renvoie un nouveau jeton d'accès et un jeton de réactualisation :

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

Obtenir un nouveau jeton de réactualisation et un nouveau jeton d'accès

Envoyer une requête POST au point de terminaison du jeton https://{yourDomain}/identity_/connect/token à l'aide du type d'accord refresh_token.

Remarque : Si vous utilisez Postman ou un outil similaire, utilisez le type de contenu application/x-www-form-urlencoded.

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

Remarque : Si l'application externe n'est pas confidentielle et utilise le code d'autorisation avec le type d'accord PKCE, supprimez le paramètre client_secret du corps de la demande.

La réponse renvoie un nouveau jeton d'accès et un nouveau jeton de réactualisation.

Le jeton de réactualisation existant n'est plus valide après utilisation, alors assurez-vous d'utiliser le nouveau jeton de réactualisation que vous avez reçu.

UiPath® Identity Server Endpoints

Si vous utilisez Postman ou un outil similaire, utilisez le type de contenu application/x-www-form-urlencoded pour toutes les demandes faites aux points de terminaison d'Identity Server. Si vous effectuez des demandes par programmation, cela n'est pas nécessaire.

Couche Identity Server	Endpoint	Description
Découverte	https://{yourDomain}/identity_/.well-known/openid-configuration	Utilisez ce point de terminaison pour récupérer des métadonnées sur votre instance d'Identity Server.
Autorisation	https://{yourDomain}/identity_/connect/authorize	Utilisez ce point de terminaison pour demander des jetons ou des codes d'autorisation via le navigateur. Ce processus comprend l'authentification de l'utilisateur final et éventuellement le consentement.
Jeton	https://{yourDomain}/identity_/connect/token	Utilisez ce point de terminaison pour demander des jetons par programmation. Veuillez noter que pour ce point de terminaison, le type de contenu doit être application/x-www-form-urlencoded.