S’authentifier avec une application externe

Les applications externes sont configurées dans Admin > Apps externes dans UiPath Cloud et utilisent OAuth 2.0 pour l'authentification. Ils prennent en charge plusieurs scénarios d'authentification:

• Accès automatisé ou sans connexion de l’utilisateur (octroi d’informations d’identification du client)
• Intégrations tierces qui effectuent leur propre flux OAuth, tel que Copilot Studio ou ChatGPT (octroi de code d'autorisation)
• Applications de bureau ou mobiles où aucune clé secrète de client ne peut être stockée en toute sécurité (octroi de code d'autorisation avec PKCE)

Comprendre les types d'applications externes

Lorsque vous créez une application externe, vous effectuez deux choix qui déterminent le fonctionnement de l’authentification:

• Indique si l'application est confidentielle ou non confidentielle.
• Indique s'il utilise des étendues d'application ou des étendues d'utilisateur.

Applications confidentielles ou non confidentielles

	Confidentiel	non confidentiel
Secret du client	Généré lors de la création. Doit être stocké en toute sécurité.	Non généré
Qui s’authentifie	L’application elle-même (aucun utilisateur requis), ou un utilisateur via l’application	Un seul utilisateur via l’application
Onglets de l’étendue dans l’interface utilisateur	Étendue(s) de l’application et Étendue(s) des utilisateurs	Étendue(s) des utilisateurs uniquement

Utilisez une application confidentielle lorsque le secret peut être stocké en toute sécurité, pour les backends, les serveurs et les pipelines CI/CD.

Utilisez une application non confidentielle pour les applications de bureau, les applications mobiles ou les applications à page unique basées sur un navigateur où un secret ne peut pas être conservé en sécurité. Les applications non confidentielles nécessitent PKCE.

Étendues d'application et étendues d'utilisateur

Les deux onglets de l’interface utilisateur des External Apps correspondent à des flux OAuth Profondément différents:

	Étendues de l’application	Étendue d’utilisateur
OAuth grant type	Informations d'identification du client (client_credentials)	Code d'autorisation (authorization_code)
Identité	L’application elle-même	Un utilisateur humain qui se connecte via l’application
Revendication du jeton sub	Le profil de l’application client_id	L’ID de l’utilisateur
Revendication du jeton sub_type	service.external	user
Comment les serveurs MCP le voient	UserType.ExternalApp	UserType.User
Nécessite une connexion utilisateur	Non (No)	Oui, le navigateur redirige vers la connexion UiPath
Activités Integration Service	Non pris en charge (aucun contexte d’utilisateur)	Pris en charge (contexte utilisateur présent)
Accès aux dossiers	L’application doit être explicitement attribuée au dossier	L'utilisateur doit disposer du rôle approprié dans le dossier. L’application ne peut être attribuée au dossier que si elle dispose également des étendues d’application; une application avec uniquement des étendues d'utilisateur ne peut pas être affectée au dossier
Disponible sur	Applications confidentielles uniquement	Confidentiel et non confidentiel

Lorsque vous enregistrez l’application externe, Identity Server définit les types d’accord que le client est autorisé à utiliser, en fonction des types d’étendue que vous avez configurés:

• Étendues de l’application uniquement → l’autorisation client_credentials est autorisée
• Étendues des utilisateurs uniquement → l'autorisation authorization_code est autorisée
• tous les deux → les deux sont autorisés

Si vous demandez manuellement un jeton à https://cloud.uipath.com/identity_/connect/token, vous devez spécifier explicitement grant_type dans chaque demande de jeton. Si vous l'omettez, une erreur sera renvoyée. L'envoi d'un type d'accord qui n'a pas été autorisé pour le client échoue également.

Configuration de l’authentification de l’étendue de l’application

Les étendues d'application utilisent l'octroi d'informations d'identification du client. Il s'agit de la seule méthode d'authentification qui fonctionne sans interaction de l'utilisateur.

Important :

Les serveurs MCP UiPath qui exposent les connecteurs Integration Service échouent lorsqu’ils sont accessibles avec les informations d’identification du client. Pour les outils basés sur Integration Service, utilisez plutôt l’authentification de l’étendue de l’utilisateur .

Prérequis

• Vous pouvez accéder à Admin > Apps externes dans UiPath.
• Vous pouvez gérer l'accès aux dossiers dans Orchestrator.

Créer l’application externe

1. Accédez à UiPath, sélectionnez Admin, puis External Apps.

2. Sélectionnez Ajouter une application.

3. Saisissez un nom et conservez le type d'application Confidentiel .

4. Sélectionnez l'onglet Étendue(s) de l'application .

   Important :

   Ajoutez des étendues sous l’onglet Étendue(s) de l’application , et non l’onglet Étendue(s) des utilisateurs .

5. Ajoutez les étendues suivantes:

   • OR.Execution: requis pour la liste des outils. Les serveurs MCP appellent l'API ListReleases d'Orchestrator pour récupérer les métadonnées du processus lors de la gestion tools/list, et ce point de terminaison est autorisé avec OR.Execution.
   • OR.Jobs: requis pour l'exécution des outils. Tous les types de serveur MCP qui exécutent des processus en tant qu'outils (UiPath, Coded et Command) appellent l'API StartJobs d'Orchestrator, qui est autorisée avec OR.Jobs

6. Sélectionnez Ajouter, puis copiez l’ ID client et la Clé secrète du client.

Attribuer l’application externe au dossier

1. Dans Orchestrator, accédez à Locataire > Gérer l'accès ou aux paramètres d'accès du dossier spécifique.

2. Ajoutez l’application externe avec le rôle Automation User .

   Ce rôle inclut l’autorisation MCPServers.View requise pour accéder aux serveurs MCP.

S’authentifier à l’aide de l’application externe

Choisissez l'une des options suivantes en fonction de la façon dont vous souhaitez qu'Orchestrator résolve les autorisations.

Option A: OR.Default uniquement (recommandé par souci de simplicité)

Le jeton ne comporte aucune étendue explicite au niveau de l’API. Orchestrator résout les autorisations via les rôles attribués à l'application externe dans chaque dossier. Les appels d'API multi-dossiers fonctionnent sans en-tête de clé de dossier. Cette option nécessite que l'application externe ait le rôle Automation User dans le dossier cible.

uipath auth --client-id "<your-client-id>" \
  --client-secret "<your-client-secret>" \
  --base-url "https://cloud.uipath.com/{org}/{tenant}" \
  --scope "OR.Default"

Option B: étendues explicites

Le jeton porte les revendications d’étendue OR.Execution et OR.Jobs explicites. Orchestrator valide ces étendues directement à chaque appel API. Cette option requiert l'en-tête X-UIPATH-FolderKey , mais les serveurs MCP le gèrent automatiquement.

uipath auth --client-id "<your-client-id>" \
  --client-secret "<your-client-secret>" \
  --base-url "https://cloud.uipath.com/{org}/{tenant}" \
  --scope "OR.Default OR.Execution OR.Jobs"

Résultat

La CLI obtient un jeton d’accès que vous pouvez utiliser dans l’en-tête Authorization pour les requêtes du serveur MCP.

Comprendre les combinaisons d'étendues

OR.Default n'est pas une étendue que vous configurez dans l'interface utilisateur des External Apps. Il s’agit d’une étendue spéciale que vous incluez dans le paramètre --scope lorsque vous demandez un jeton. Les étendues que vous demandez déterminent la façon dont Orchestrator résout les autorisations et comment les serveurs MCP acheminent les appels d'API.

Le flux MCP implique deux appels d'API Orchestrator qui nécessitent des étendues différentes:

• tools/list: les serveurs MCP appellent odata/Releases/ListReleases pour récupérer les métadonnées du processus. Le contrôleur Releases (Versions) nécessite OR.Execution.
• tools/call: les serveurs MCP appellent odata/Jobs/StartJobs pour exécuter un processus. Le contrôleur de tâches nécessite OR.Jobs.

La table suivante résume le comportement des différentes combinaisons d’étendue:

Étendues à la demande de jeton	Résolution des autorisations d'Orchestrator	X-UIPATH-FolderKey En-tête	Comportement des serveurs MCP
OR.Default uniquement	Attributions de rôle au niveau du dossier (par exemple, Automation User dans le dossier cible)	Non requis	Appel d'API multi-dossiers unique
Étendues spécifiques uniquement (par exemple, OR.Execution OR.Jobs)	Revendications d'étendue explicites dans le jeton	Obligatoire pour chaque appel API	Appels d'API par dossier (regroupés par dossier)
OR.Default plus des étendues spécifiques	Revendications d'étendue explicites (les étendues spécifiques ont priorité)	Obligatoire pour chaque appel API	Appels d'API par dossier (regroupés par dossier)

Remarques sur le comportement:

• Demander OR.Default uniquement est la configuration la plus simple. Orchestrator vérifie les rôles attribués à l’application externe dans chaque dossier. Le rôle Automation User couvre à la fois l’accès aux versions et aux tâches.
• L'ajout d'étendues spécifiques telles que OR.Execution ou OR.Jobs (avec ou sans OR.Default) modifie le fonctionnement de la résolution des dossiers. Orchestrator vérifie à la fois les revendications d'étendue et les autorisations de rôle de dossier, et l'accès est accordé si l'une des vérifications est réussie. Cela nécessite l'en-tête X-UIPATH-FolderKey sur chaque appel API. Les serveurs MCP gèrent automatiquement cela en détectant les étendues du jeton et en effectuant des appels par dossier si nécessaire.
• Sans OR.Default, les étendues OR.* spécifiques contournent la résolution des rôles au niveau du dossier et accordent l'accès à tous les dossiers du locataire. L'en-tête X-UIPATH-FolderKey est toujours requis pour le routage de l'API.

Limitation connue: GetFoldersForCurrentUser

Lors de l'exécution locale des serveurs MCP avec les informations d'identification du client (uipath run), le SDK Python appelle orchestrator_/api/FoldersNavigation/GetFoldersForCurrentUser pour résoudre le chemin du dossier en une clé de dossier. Cette API ne prend pas en charge l’authentification des informations d’identification du client; elle nécessite un jeton d’utilisateur interactif.

Pour contourner ce problème, définissez directement la variable d’environnement UIPATH_FOLDER_KEY . Lorsque cette variable est définie, le SDK ignore entièrement l'appel GetFoldersForCurrentUser :

export UIPATH_FOLDER_KEY="<folder-guid>"
uipath run mcp-server

Vous pouvez trouver le GUID du dossier dans l'API Orchestrator ou dans l'URL du dossier.

Erreur courante: informations d’identification de la machine vs application externe

L’utilisation des informations d’identification de la machine (depuis Orchestrator > Machines), au lieu des informations d’identification de l’application externe, renvoie les erreurs invalid_scope . Les informations d’identification de la machine sont destinées à l’authentification du Robot, et non à l’accès à l’API.

Si vous voyez:

{"error":"invalid_scope","error_description":"..."}

Vérifiez que vous utilisez les informations d’identification de Admin > External Apps, et non d’ Orchestrator > Machines.

Configuration de l’authentification de l’étendue utilisateur

Les étendues d'utilisateur utilisent l'octroi de code d'autorisation. Un utilisateur doit se connecter via l’application externe, le jeton porte l’identité de l’utilisateur plutôt que celle de l’application.

Utilisez l’authentification à l’échelle de l’utilisateur dans les situations suivantes:

• Le serveur MCP expose des outils soutenus par les activités Integration Service (connecteurs).
• Vous intégrez un client tiers qui effectue son propre flux OAuth (Copilot Studio, ChatGPT).
• Vous avez besoin d'une identité par utilisateur et d'un contrôle d'accès basé sur qui s'est connecté, et non sur l'application qui appelle.

Prérequis

• Vous pouvez accéder à Admin > Apps externes dans UiPath.
• Vous pouvez gérer l'accès aux dossiers dans Orchestrator.
• Vous connaissez l’URL de redirection de votre application cliente.

Créer l’application externe

1. Accédez à UiPath, sélectionnez Admin, puis External Apps.

2. Sélectionnez Ajouter une application.

3. Saisissez un nom et conservez le type d'application Confidentiel .

4. Sélectionnez l'onglet Étendue(s) des utilisateurs .

   Important :

   Ajoutez des étendues sous l’onglet Étendue(s) des utilisateurs , et non l’onglet Étendue(s) de l’application .

5. Ajoutez les étendues suivantes:

   • OR.Execution: requis pour la liste des outils.
   • OR.Jobs: requis pour l'exécution d'outils (serveurs codés ou de commande).

6. Ajoutez une URL de redirection. Il s'agit de l'adresse à laquelle le navigateur de l'utilisateur est envoyé après la connexion. Utilisez l'URL de rappel fournie par votre application cliente.

   Pour Copilot Studio, utilisez initialement une URL factice et mettez-la à jour après la création de la connexion.

7. Sélectionnez Ajouter, puis copiez l’ ID client et la Clé secrète du client.

Configurer l'accès aux dossiers

Étant donné que l'application externe créée ci-dessus n'a que des étendues Utilisateur, elle ne peut pas être affectée à un dossier dans Gérer l'accès. L'accès aux dossiers est accordé par le rôle de l'utilisateur; le jeton hérite des autorisations de l'utilisateur, et non de l'application.

1. Dans Orchestrator, accédez à Locataire > Gérer l'accès ou aux paramètres d'accès du dossier spécifique.

2. Affectez l'utilisateur qui se connectera avec le rôle Automation User, Automation Developer ou Folder Administrator .

   Ce rôle détermine ce que l'utilisateur peut faire dans le dossier et doit inclure l'autorisation MCPServers.View requise pour accéder aux serveurs MCP.

Si l’application externe a également des étendues d’application définies, vous pouvez en outre attribuer l’application elle-même au dossier avec le rôle Utilisateur d’automatisation . Cela est uniquement requis pour les flux d'informations d'identification du client qui n'impliquent pas de connexion utilisateur.

Exécuter le flux de code d'autorisation

L'application cliente lance le flux.

1. Redirigez l’utilisateur vers le point de terminaison de l’autorisation:

   GET https://cloud.uipath.com/identity_/connect/authorize
     ?client_id=<your-client-id>
     &response_type=code
     &redirect_uri=<your-callback-url>
     &scope=OR.Default
   

2. L'utilisateur se connecte via le navigateur et est redirigé vers l'URL de rappel avec un paramètre code .

3. Échangez le code d'autorisation contre un jeton de votre application côté serveur:

   POST https://cloud.uipath.com/identity_/connect/token
     Content-Type: application/x-www-form-urlencoded
   
     client_id=<your-client-id>
     &client_secret=<your-client-secret>
     &grant_type=authorization_code
     &code=<authorization-code>
     &redirect_uri=<your-callback-url>
   

Résultat

Le point de terminaison de jeton renvoie un jeton d'accès que vous pouvez utiliser dans l'en-tête Authorization pour les requêtes du serveur MCP.

Variante: application non confidentielle avec PKCE

Le même flux fonctionne avec une application externe non confidentielle. Les différences sont résumées ci-dessous:

	Confidentiel	non confidentiel
Secret du client	Inclus dans l'échange de jetons	Non utilisé (aucune clé secrète n’existe)
PKCE	Facultatif	Obligatoire
Attribution de dossier	L’application ne peut être affectée au dossier que si des étendues d’application sont également définies. Avec les étendues d'utilisateur uniquement, l'application n'apparaît pas dans Gérer l'accès et seuls les rôles de dossier de l'utilisateur s'appliquent	L’application ne peut pas avoir d’étendues d’application et n’apparaît jamais dans Gérer l’accès; seuls les rôles de dossier de l’utilisateur s’appliquent
Créer dans l’IU	Sélectionner Confidentiel	Sélectionnez Non confidentiel

Pour utiliser cette variante:

1. Lors de la création de l’application externe, sélectionnez Non confidentiel au lieu de Confidentiel. Seul l'onglet Étendue(s) des utilisateurs est disponible. Ajoutez OR.Execution, ajoutez OR.Jobs pour les serveurs codés ou de commande et ajoutez l'URL de redirection.

2. Affectez uniquement l'utilisateur (pas l'application) au dossier avec le rôle approprié.

3. Utilisez le flux d'autorisation basé sur PKCE suivant:

   # 1. Generate PKCE code verifier and challenge
   code_verifier = <random 64-byte base64url string>
   code_challenge = BASE64URL(SHA256(code_verifier))
   
   # 2. Redirect user to authorize (with PKCE challenge)
   GET https://cloud.uipath.com/identity_/connect/authorize
     ?client_id=<your-client-id>
     &response_type=code
     &redirect_uri=<your-callback-url>
     &scope=OR.Default
     &code_challenge=<code_challenge>
     &code_challenge_method=S256
   
   # 3. Exchange the code for a token (no client_secret; include code_verifier)
   POST https://cloud.uipath.com/identity_/connect/token
     Content-Type: application/x-www-form-urlencoded
   
     client_id=<your-client-id>
     &grant_type=authorization_code
     &code=<authorization-code>
     &redirect_uri=<your-callback-url>
     &code_verifier=<code_verifier>
   

Le jeton obtenu est identique au jeton des étendues d’utilisateur confidentielles: sub correspond au GUID de l’utilisateur, sub_type correspond à user et l’audience est UiPath.Orchestrator. Les serveurs MCP la traitent de la même manière que la variante confidentielle.

caractéristiques des jetons (étendues des utilisateurs)

Ces caractéristiques s’appliquent aux applications confidentielles et non confidentielles utilisant le flux de codes d’autorisation:

• JWT avec sub défini sur le GUID de l'utilisateur et sub_type défini sur user.
• Audience: UiPath.Orchestrator.
• Les serveurs MCP résolvent le jeton en tant qu'identité d'utilisateur - au niveau de la couche Serveurs MCP, le jeton suit le même chemin de code que la connexion interactive.
• Le routage par clé de dossier ne s'applique pas (appel Orchestrator multi-dossiers unique).
• Les activités Integration Service fonctionnent (le contexte de l’utilisateur est présent).
• Actualiser le jeton: renvoyé lorsque offline_access est inclus dans le paramètre scope ; non renvoyé sans celui-ci. La durée de vie du jeton d’actualisation est de 60 jours.

Connexion de Copilot Studio à un serveur MCP UiPath

Utilisez cette procédure pour connecter un agent Microsoft Copilot Studio à un serveur MCP UiPath à l'aide de l'authentification manuelle OAuth 2.0.

Prérequis

• Vous pouvez gérer les applications externes.
• Vous pouvez gérer l'accès aux dossiers dans Orchestrator.
• Vous pouvez configurer des connexions dans Copilot Studio.

Étapes

1. Dans UiPath, accédez à Admin > External Apps et sélectionnez Ajouter une application.

2. Définissez le type d'application sur Confidentiel.

3. Sous Ressources, ajoutez Accès à l’API Orchestrator avec l’étendue OR.Execution , et ajoutez-le à la fois en tant qu’étendue d’application et en tant qu’étendue d’utilisateur.

   Si le serveur MCP est de type Codé ou Commande, ajoutez également OR.Jobs sous les deux étendues.

   L'ajout de l'étendue sous l'onglet Étendue(s) de l'application est ce qui rend l'étape 6 opérationnelle; une application avec uniquement des étendues d'utilisateur ne peut pas être affectée à un dossier dans Gérer l'accès.

4. Saisissez une URL de redirection factice pour l'instant (par exemple, https://cloud.uipath.com).

5. Enregistrez l'application, puis copiez l' ID client et la Clé secrète du client.

6. Dans Orchestrator, attribuez l'application externe au dossier contenant le serveur MCP avec le rôle Automation User . Cela fonctionne, car l'application a reçu des Étendues d'application à l'étape 3; une application avec uniquement des étendues d'utilisateur ne peut pas être affectée au dossier. Attribuez également le rôle de locataire Allow to be Automation User.

7. Dans Copilot Studio, ajoutez l'URL du serveur MCP avec l'authentification manuelle OAuth 2.0 , à l'aide des valeurs suivantes:

   • ID de client: la valeur copiée à l'étape 5.
   • Clé secrète du client: la valeur copiée à l'étape 5.
   • URL d’autorisation: https://cloud.uipath.com/identity_/connect/authorize
   • URL du jeton: https://cloud.uipath.com/identity_/connect/token
   • Actualiser l’URL: https://cloud.uipath.com/identity_/connect/token
   • Étendue: OR.Default

8. Sélectionnez Créer dans Copilot Studio. Copilot Studio génère une URL de redirection, le champ est grisé avant la création.

9. Copiez l'URL de redirection générée et ajoutez-la aux URL de redirection de l'application externe dans UiPath Admin > External Apps.

10. Retournez à Copilot Studio et sélectionnez Se connecter.

Résultat

Copilot Studio est connecté au serveur MCP UiPath. L’utilisateur se connecte via le flux OAuth lorsque l’agent accède aux outils MCP.

Connexion de ChatGPT à un serveur MCP UiPath

Utilisez cette procédure pour les applications ChatGPT nouvelles ou non publiées où l’enregistrement dynamique du client ne fonctionne pas.

ChatGPT a modifié ses URI de redirection de /connector_platform_oauth_redirect à /connector/oauth/{callback_id}. Les applications déjà publiées fonctionnent toujours avec DCR. Les applications nouvelles ou non publiées nécessitent une configuration OAuth manuelle.

Prérequis

• Vous pouvez gérer les applications externes.
• Vous pouvez créer des applications dans ChatGPT.

Obtenir l'URL de rappel de ChatGPT

1. Accédez à ChatGPT, sélectionnez votre profil, puis sélectionnez Apps, puis Créer une application.
2. Saisissez le nom, la description et l'URL du serveur MCP d'UiPath.
3. Sélectionnez Paramètres avancés.
4. Sous Méthode d'enregistrement, passez de DCR à Client OAuthDéfiniUtilisateur.
5. Copiez l' URL de rappel (https://chatgpt.com/connector/oauth/{callback_id}).
6. Gardez cet onglet de navigateur ouvert.

Créer l'application externe dans UiPath

1. Accédez à Admin > External Apps et sélectionnez Ajouter une application.

2. Sélectionnez Confidentiel comme type d'application.

3. Ajoutez OR.Execution, OR.Jobs et OR.Folders sous les onglets Étendue de l'application et Étendue de l'utilisateur .

   L'ajout des étendues sous l'onglet Étendue(s) de l'application est ce qui permet à l'étape suivante (affectation de dossier) de fonctionner; une application avec uniquement des étendues d'utilisateur ne peut pas être affectée à un dossier dans Gérer l'accès.

4. Dans le champ URL de redirection , collez l'URL de rappel copiée depuis ChatGPT.

5. Enregistrez l'application, puis copiez l' ID client et la Clé secrète du client.

Attribuer l’application externe au dossier

1. Dans Orchestrator, ouvrez le dossier contenant le serveur MCP.
2. Accédez à Gérer l’accès > Attribuer.
3. Ajoutez l’application externe avec le rôle Automation User .

Configurer ChatGPT

1. Retournez à l’onglet du navigateur ChatGPT.
2. Saisissez l’ ID de client OAuth et la clé secrète du client copiés à partir de l’application externe.
3. Sous Enregistrement du client > Méthode d’authentification du point de terminaison de jeton, sélectionnez client_secret_basic.
4. Sous Étendues > Étendues par défaut, désactivez toutes les étendues par défaut existantes.
5. Sous Étendues > Étendues de base, ajoutez OR.Default.
6. Sélectionnez Créer.

Résultat

ChatGPT est connecté au serveur MCP UiPath. Les utilisateurs s’authentifient via le flux OAuth manuel lorsque l’application accède aux outils MCP.

Comportement de OR.Default

OR.Default est référencé à la fois dans les flux d'étendue d'application et d'étendue utilisateur, mais il se comporte différemment dans chaque contexte:

Context	Comportement
Étendues d'application, dans le paramètre --scope de la demande de jeton	Contrôle la façon dont Orchestrator résout les autorisations. Lorsque OR.Default est la seule étendue, Orchestrator utilise des affectations de rôle de dossier au lieu de revendications explicites d'étendue. Vérifiez Comprendre les combinaisons d’étendues.
Étendues des utilisateurs, dans le paramètre scope de la demande d'autorisation	Utilisé comme paramètre d'étendue dans la demande d'autorisation. Au niveau d'Orchestrator, il active un mode d'autorisation permissif dans lequel l'accès est accordé si la vérification de l'étendue ou les autorisations du rôle de dossier de l'utilisateur sont respectées. Les serveurs MCP n'utilisent pas OR.Default pour les jetons d'étendue utilisateur, ils effectuent toujours des appels multi-dossiers uniques quelles que soient les étendues portées par le jeton.

Dans aucun des deux cas, il s'agit OR.Default une étendue que vous configurez dans l'interface utilisateur des External Apps. Elle n'apparaît dans le paramètre d'étendue qu'au moment du jeton ou de la demande d'autorisation.