Accèder aux ressources UiPath à l'aide d'applications externes

Ces instructions sont destinées aux développeurs qui maintiennent l'intégration entre les produits UiPath et les applications externes dans un environnement avec une installation Orchestrator locale ou une installation Orchestrator auto-hébergée.

Astuce :

Avant de commencer :

• L'application externe doit déjà être enregistrée dans Applications externes ( External Applications) par l'administrateur de l'organisation.
• Obtenez les détails d'enregistrement auprès de l'administrateur de l'organisation.

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 (instructions)
confidentiel	Application	Identifiants du client (Client credentials) (instructions)
non confidentiel	Utilisateur (User)	Code d'autorisation avec PKCE (instructions)

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.

Le serveur d'autorisation pour accéder aux ressources UiPath est UiPath Identity Server, qui prend en charge l'infrastructure OAuth 2.0.

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. L'application externe envoie une demande d'autorisation au point de terminaison d'autorisation UiPath Identity Server pour obtenir le code d'autorisation.

   {BaseURL}/identity/connect/authorize?
   response_type=code&
   client_id={app_id}&
   scope={scopes}&
   redirect_uri={redirect_url}

   • {BaseURL}/identity/connect/authorize est le point de terminaison d'autorisation d'Identity Server.
   • response_type=code spécifie que l'application demande un code d'autorisation.
   • client_id doit contenir l'ID de l'application (Application ID) (affiché sur la page Applications externes (External Applications)).
   • 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 Swagger pour obtenir les valeurs d’étendue dont vous avez besoin. Par exemple :

     

   • redirect_uri contient l'URL vers laquelle UiPath Identity Server redirige la demande d'autorisation une fois le code d'autorisation accordé.
2. Un utilisateur doit se connecter à Orchestrator 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. 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 {BaseURL}/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). Voir Utilisation du jeton d'accès et Obtention d'un jeton de réactualisation pour plus d'informations.

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, sauf que dans la demande d'autorisation, vous devez inclure les paramètres de requête de demande 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.

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

Remarque : Consultez l'application Swagger de l'API Orchestrator sur {OrchestratorURL}/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 jetons de réactualisation sont également valables pour une seule utilisation et ils expirent après 60 jours.

Les applications externes confidentielles et non confidentielles peuvent demander toutes deux un jeton d'actualisation. Pour ce faire, elles doivent inclure 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 pour obtenir un jeton de réactualisation.

Pour obtenir un jeton de réactualisation, envoyez une demande POST avec le code d'autorisation au point de terminaison du jeton

{BaseURL}/identity/connect/token.

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" 
}

Pour obtenir un nouveau jeton d'actualisation et un nouveau jeton d'accès, envoyez une requête POST au point de terminaison du jeton {BaseURL}/identity/connect/token à l'aide du type d'accord refresh_token.

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}"
}

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.

Découverte : {BaseURL}/identity/.well-known/openid-configuration

Autorisation : {BaseURL}/identity/connect/authorize

Jeton : {BaseURL}/identity/connect/token