Applications externes (OAuth)

En tant que développeur travaillant sur l’intégration des produits UiPath avec des applications externes, vous êtes responsable de tâches telles que la gestion des modifications d’étendue, la gestion des jetons d’accès et des jetons de réactualisation, ainsi que la maintenance de l’intégration entre l’application externe et les ressources UiPath. Le guide suivant vous détaille l’ensemble de ces opérations.

OAuth propose une sélection de bibliothèques que vous pouvez exploiter pour simplifier l’authentification, l’autorisation, la délégation et la sécurisation des appels d’API. Vous pouvez accéder à ces ressources directement sur le site Web officiel d’OAuth.

Prérequis

En tant que développeur, une fois que l’administrateur de l’organisation a enregistré votre application externe dans UiPath, vous devriez obtenir les détails d’enregistrement vous permettant d’authentifier votre application externe avec les ressources UiPath.

• Le Type d’application et l’ID d’application. Si vous travaillez avec une application confidentielle, vous aurez également besoin de la clé secrète de l’application. Cette clé sert à authentifier votre application auprès de UiPath Identity Server, le serveur d’autorisation permettant d’accéder aux ressources UiPath, lequel prend en charge l’infrastructure OAuth 2.0.

• De plus, vous devez connaître les étendues de l’application externe, qui définissent les ressources auxquelles votre application externe pourra accéder dans UiPath. Cela inclut à la fois la spécification des ressources (comme ressources, processus, etc.) et le niveau d’autorisation (lecture, écriture, modification, etc.).

Authentifier et autoriser des applications externes

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é, afin que l’application externe puisse récupérer un jeton d’accès.

Au cours de ce processus, demandez un jeton d’accès en fournissant à Identity Server l’étendue de l’application externe ainsi que les informations d’identification de l’application enregistrée, soit l’ID de l’application, ainsi que la clé secrète de l’application dans le cas d’applications confidentielles. Si les informations d’identification sont valides, Identity Server répond en émettant un code d’autorisation, qui sera utilisé pour générer le jeton d’accès.

Quel type d’accord d’autorisation utiliser ?

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

Remarque :

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.

Déclarer les étendues

L’étendue définie par l’administrateur pour une application détermine le niveau d’accès maximum que l’application peut atteindre. En tant que développeur, si vous demandez un accès supérieur à cette étendue prédéfinie, votre demande échouera. Par conséquent, il est important de veiller à ce que vos demandes respectent l’étendue définie par l’administrateur.

Au niveau de l’administrateur, les autorisations de l’application peuvent être les suivantes :

• Autorisations à l’échelle de l’organisation : par défaut, lorsqu’une application externe est enregistrée, l’accès aux ressources est accordé à l’ensemble de l’organisation, en fonction des étendues définies.

• Autorisations affinées : pour des paramètres d’autorisation plus précis, l’administrateur de l’organisation peut attribuer à l’application externe un rôle au niveau du locataire ou du dossier dans Orchestrator, bien que cela soit uniquement possible pour les applications confidentielles.

Au niveau du développeur, la déclaration des étendues s’effectue comme suit :

• Autorisations à l’échelle de l’organisation : lorsque vous déclarez une étendue explicitement spécifiée dans la demande de jeton, telle que OR.Machines.View, cela implique que l’application demande une autorisation d’accès à l’échelle de l’organisation.
• Autorisations affinées : afin de fournir à votre application des accès affinés, vous devez déclarer OR.Default dans la demande de jeton. OR.Default agit comme une étendue de caractère générique, en fournissant à votre application un accès précis qui dépendra du rôle lui étant attribué dans des locataires ou des dossiers spécifiques.

Par exemple, imaginons que vous souhaitiez que votre application dispose d’un accès à l’échelle de l’organisation pour afficher toutes les machines, ainsi que des autorisations exclusives à des niveaux plus précis dans les locataires et les dossiers définis. Dans ce cas, vous pouvez déclarer les étendues OR.Machines.View et OR.Default. Cette déclaration combinée permet à votre application externe de fonctionner à l’échelle de toute l’organisation, ainsi qu’à l’échelle de locataires ou de dossiers Orchestrator spécifiques.

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 :

Applications confidentielles avec étendues d’application (flux d’informations d’identification du client)

Les applications confidentielles avec des étendues d’application effectuent le flux des informations identification du client par rapport à UiPath Identity Server.

Le diagramme affiche le flux d’informations d’identification du client OAuth. Le client envoie les informations d’identification à Identity Server et reçoit le jeton d’accès. Une fois le jeton vérifié, l’accès aux ressources de l’API est accordé.

Pour une présentation détaillée du flux OAuth utilisant les informations d’identification du client, référez-vous au document RFC 6749.

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

1. 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:

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

   Champ	Description
   client_id	Spécifie l’identifiant unique attribué à l’application lors de son enregistrement. Doit contenir l’ID de l’application (fourni par l’administrateur).
   client_secret	Spécifie des informations confidentielles telles qu’un mot de passe, lesquelles seront fournies aux applications confidentielles lors de leur enregistrement. Ce champ est utilisé avec client_id pour authentifier l’application lorsque celle-ci envoie des requêtes à Identity Server. Doit contenir la clé secrète de l’application (fournie par l’administrateur).
   scope	Spécifie les étendues demandées par l’application, délimitées par un espace ; par exemple : OR.Machines.View OR.Default. Utilisez OR.Default pour accorder un accès contrôlé et personnalisé à des locataires ou des dossiers spécifiques. Les autorisations réelles obtenues par l’application sont déterminées en fonction de l’emplacement où l’application a été attribuée par l’administrateur (locataires ou dossiers). Utilisez des étendues explicites telles que OR.Machines.View afin d’accorder un accès étendu à certaines ressources à l’échelle de l’organisation.

2. L’application externe reçoit une réponse contenant le jeton d’accès :

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

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

Applications confidentielles avec étendues d’utilisateur (flux de code d’autorisation)

Pour les applications externes confidentielles avec des étendues d’utilisateur, vous effectuez le flux de code d’autorisation par rapport à Identity Server.

Le diagramme indique le flux de code d’autorisation OAuth. Le client demande l’autorisation à Identity Server. L’utilisateur est alors invité à se connecter. Si cela réussit, Identity Server fournit le code d’autorisation. Le client va utiliser ce code ainsi que la clé secrète du client pour récupérer un jeton d’accès. Le jeton vérifié permet alors d’accéder aux ressources de l’API.

Pour une présentation détaillée du flux OAuth utilisant des codes d’autorisation, reportez-vous au document RFC 6749.

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

1. L’application externe envoie une demande d’autorisation au point de terminaison d’autorisation Identity Server https://{yourDomain}/identity/connect/authorize? afin d’obtenir le code d’autorisation :

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

   Option	Description
   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	Spécifie l’identifiant unique attribué à l’application lors de son enregistrement. Doit contenir l’ID de l’application (tel que fourni par l’administrateur).
   client_secret	Spécifie une information confidentielle telle qu’un mot de passe, laquelle sera fournie aux applications confidentielles lors de leur enregistrement. Ce champ est utilisé avec client_id pour authentifier l’application lorsque celle-ci envoie des requêtes à Identity Server. Doit contenir la clé secrète de l’application (telle que fournie par l’administrateur).
   scope	Spécifie les étendues demandées par l’application, délimitées par un espace ; par exemple : OR.Machines.View OR.Default. Utilisez OR.Default pour accorder un accès contrôlé et personnalisé à des locataires ou des dossiers spécifiques. Les autorisations obtenues par l’application sont déterminées en fonction des locataires ou des dossiers dans lesquels l’application a été attribuée par l’administrateur. Utilisez des étendues explicites telles que OR.Machines.View afin d’accorder un accès étendu à certaines ressources à l’échelle de l’organisation.
   redirect_uri	Spécifie l’URL vers laquelle Identity Server redirige la demande d’autorisation une fois le code d’autorisation accordé

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. Vous ne pouvez utiliser le code d'autorisation qu'une seule fois.
   Exemple de redirection de demande d'autorisation : {redirect_url}?code={authorization_code}&scope={scopes}
4. L’application externe demande un jeton d’accès à UiPath® Identity Server à l’aide du code d’autorisation et des détails d’authentification (client_id et client_secret). Ceux-ci sont inclus dans le corps d’une requête POST au point de terminaison du jeton https://{yourDomain}/identity/connect/token.

   grant_type=authorization_code&code={authorization_code}&redirect_uri={redirect_url}&client_id={app_id}&client_secret={app_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 utiliser le jeton d’accès pour accéder aux ressources utilisateur jusqu’à l’expiration du jeton (une heure).

Applications non confidentielles avec des étendues d’utilisateur (code d’autorisation avec flux PKCE)

Pour une application non confidentielle avec des étendues d’utilisateur, le code d’autorisation s’exécute avec le flux PKCE. Pour une présentation détaillée du flux OAuth utilisant le code d’autorisation PKCE, reportez-vous au document RFC 7636.

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

1. L’application externe envoie une demande d’autorisation au point de terminaison https://{yourDomain}/identity/connect/authorize? afin d’obtenir le code d’autorisation :

   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	Description
   client_id	Spécifie l’identifiant unique attribué à l’application lors de son enregistrement. Doit contenir l’ID de l’application (tel que fourni par l’administrateur).
   scope	Spécifie les étendues demandées par l’application, délimitées par un espace ; par exemple : OR.Machines.View.
   redirect_uri	Spécifie l’URL vers laquelle UiPath Identity Server redirige la demande d’autorisation une fois le code d’autorisation accordé.
   code_challenge_method	Spécifie la méthode utilisée pour encoder le code_verifier du code_challenge. La valeur de ce champ doit être S256, ce qui signifie que le code_verifier doit être haché via SHA256 et via un encodage base64url pour créer le code_challenge.
   code_challenge	Une chaîne de caractères à 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.

2. Dans la demande de jeton POST à https://{identity_baseURL}/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.

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

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

Obtention d'un jeton de réactualisation

Les jetons d’accès ont un délai d’expiration d’une heure. L’application externe peut obtenir un nouveau jeton d’accès, sans interaction de l’utilisateur, en le remplaçant par un jeton de réactualisation. Les applications externes confidentielles et non confidentielles peuvent toutes deux demander un jeton d’actualisation. Le flux d’informations d’identification du client ne prend cependant pas en charge les jetons de réactualisation. Dans le flux d’informations d’identification du client, les jetons d’accès sont délivrés directement sans passer par un jeton de réactualisation. Lorsque les clients ont besoin d’un nouveau jeton, ils doivent procéder à une nouvelle authentification à l’aide de leurs informations d’identification.

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.

Points de terminaison du serveur d’identité UiPath®

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.