L'Orchestrator Credentials Proxy

Vous pouvez ajouter vos propres magasins d'informations d'identification à Orchestrator, afin de contrôler indépendamment la sécurité de vos données de connexion.

Pour ce faire, vous pouvez charger les plug-ins du magasin d'informations d'identification souhaités, sous la forme de fichiers .dll, vers le service web Orchestrator Credentials Proxy. Le kit d'installation contient tous les plug-ins pris en charge par UiPath, mais vous pouvez également développer vos propres fichiers .dll de plug-ins à charger. Ce service rend ensuite vos plug-ins disponibles sur Orchestrator via un proxy, qui est créé dans Orchestrator en fonction de l'URL publique et de la clé secrète générées par le proxy.

Problème connu

Cela s’applique uniquement aux scénarios où le port de Orchestrator Credentials Proxy est défini sur une valeur différente de la valeur par défaut 443.

Lorsque vous effectuez une mise à niveau à partir de n’importe quelle version comprise entre les versions 1.0.0 et 2.0.1 et que vous avez utilisé un port personnalisé, le port local de la règle entrante UiPathOrchestratorCredentialsProxy est automatiquement remplacé par le port 443, soit le port par défaut. Cela empêche que la connexion au proxy soit établie.

Pour contourner ce problème, vous devez modifier manuellement le port local dans la règle entrante lors de la mise à niveau.

Installation

Le Orchestrator Credentials Proxy peut être installé via un programme d'installation .msi ou via une image Docker fournie par UiPath.

Prérequis logiciels et matériels

Prérequis matériels

Voici la configuration minimale requise pour exécuter le proxy sur un serveur Windows avec IIS. Les besoins réels en ressources varieront en fonction de l’utilisation individuelle.

Cœurs de processeur (CPU Cores)	RAM
2	4 Go

Prérequis logiciels

Les versions de Windows Server suivantes sont requises pour installer le proxy :

• 2012 R2
• 2016
• 2019
• 2022

Via le fichier programme d'installation .msi

Prérequis

Les éléments suivants sont requis pour pouvoir utiliser le proxy :

• ASP.NET Core, versions 3.1, 6.0.x ou 8.0.x
• IIS version 8.0 ou supérieure

• Les fonctionnalités Windows suivantes doivent être installées :

  • IIS-DefaultDocument
  • IIS-HttpErrors
  • IIS-StaticContent
  • IIS-RequestFiltering
  • IIS-URLAuthorization
  • IIS-Authentification Windows
  • IIS-ASPNET45
  • IIS-ISAPIExtensions
  • IIS-ISAPIFilter
  • IIS-WebSockets
  • IIS-ApplicationInit
  • IIS-ManagementConsole

Étapes d'installation

Suivez ces étapes pour effectuer l'installation :

1. Téléchargez le programme d'installation de UiPath Orchestrator Credential Proxy sur le Customer Portal.
2. Installez le proxy.

   Proxy connecté

   • URL publique (Public URL) : l'URL du proxy d'identification d'Orchestrator qui est exposée publiquement.
   • Certificat SSL (SSL Certificate) : le sujet ou l'empreinte du certificat SSL utilisé pour sécuriser les connexions avec l'Orchestrator Credentials Proxy. Il s'agit du certificat SSL installé sur l'ordinateur ou le serveur Web hébergeant le proxy.

     Notez que ce certificat doit être émis par un fournisseur de certificat public et qu’il doit être valide pour l’URL publique.

   • Port : le port correspondant à l'URL publique
   • Clé secrète (Secret Key) : (générée automatiquement) la clé nécessaire à la configuration d'un proxy personnalisé dans l'interface d'Orchestrator. Assurez-vous de le copier dans votre presse-papiers pour une utilisation future.

     Vous pouvez modifier cet élément manuellement, sachant qu'il est également compatible avec la rotation des clés.

   Proxy déconnecté

   Cette fonctionnalité est disponible uniquement si vous êtes sur le plan de licence Enterprise - Avancé.

   • Certificat SSL (SSL Certificate) : le sujet ou l'empreinte du certificat SSL utilisé pour sécuriser les connexions avec l'Orchestrator Credentials Proxy. Il s'agit du certificat SSL installé sur l'ordinateur ou le serveur Web hébergeant le proxy.
   • Port : le port correspondant à l’URL
   • Clé secrète (Secret Key) : (générée automatiquement) la clé nécessaire à la configuration d'un proxy personnalisé dans l'interface d'Orchestrator. Assurez-vous de le copier dans votre presse-papiers pour une utilisation future.

     Vous pouvez modifier cet élément manuellement, sachant qu'il est également compatible avec la rotation des clés.

   Lors de l'installation, le paramètre AppSettings.CredentialsProxyType dans appsettings.Production.json est défini sur Déconnecté (Disconnected). C'est ainsi que le proxy détecte le type au démarrage.

Via l'image Docker

Informations préliminaires

Tous les paramètres de l'Orchestrator Credentials Proxy qui peuvent être modifiés sont disponibles dans son fichier appsettings.json. Les paramètres suivants sont importants dans la configuration initiale :

• Jwt:Keys : (initialement vide) ce tableau de chaînes est utilisé pour configurer l'authentification du proxy. Il s'agit de la clé secrète que vous utiliserez lors du processus de création du proxy et qui permet à Orchestrator de récupérer avec succès les données du proxy. Toutes les valeurs non valides sont ignorées. Si aucune valeur valide n'est trouvée, le proxy ne se lancera pas.

  Les clés secrètes doivent être au format base64 et peuvent être générées à l'aide de l'un des scripts PowerShell ci-dessous.

  $bytes = [System.Security.Cryptography.RandomNumberGenerator]::GetBytes(64)
  $jwtSigningKey = [Convert]::ToBase64String($bytes);
  Write-Host $jwtSigningKey

Le script ci-dessus génère 64 octets aléatoires (en utilisant SeccureRandom) et les convertit en chaîne base64.

[Byte[]] $bytes = 1..64
$rng = New-Object System.Security.Cryptography.RNGCryptoServiceProvider
$rng.GetBytes($bytes)
$jwtSigningKey = [Convert]::ToBase64String($bytes);
Write-Host $jwtSigningKey

• appSettings:Plugins.SecureStores : (initialement défini sur les magasins d'informations d'identification par défaut disponibles dans Orchestrator) il s'agit d'une chaîne CSV utilisée pour spécifier les assemblys .dll à charger depuis le disque (à partir de path/plugins) afin de permettre l'utilisation des magasins sécurisés par le proxy. L'ajout d'assemblys non valides à la liste n'interrompra pas le démarrage, mais vous recevrez des erreurs de journal lors du déploiement.
• appSettings:SigningCredentialSettings:FileLocation:SigningCredential:FilePath et appSettings:SigningCredentialSettings:FileLocation:SigningCredential:Password : (initialement masqués) à utiliser pour chiffrer les paramètres Jwt:Keys et SecureStoreConfigurations:Context. Il s’agit du chemin d’accès au fichier de votre certificat de signature.
• appSettings:SigningCredentialSettings:StoreLocation:Name, appSettings:SigningCredentialSettings:StoreLocation:Location, appSettings:SigningCredentialSettings:StoreLocation:NameType : (initialement masqués) à utiliser pour chiffrer les paramètres Jwt:Keys et SecureStoreConfigurations:Context.

Chiffrement du paramètre Jwt:Keys

Pour ajouter une couche de sécurité supplémentaire, vous pouvez chiffrer les paramètres Jwt:Keys et SecureStoreConfigurations:Context dans votre fichier appsettings.json.

Remarque : cela nécessite UiPath.ConfigProtector.exe la version 1.0.9 ou ultérieure.

Configuration et exécution de l'image Docker

Pour exécuter un Orchestrator Credentials Proxy à l'aide de Docker, effectuez les étapes suivantes.

1. Télécharger l'image Docker

   Vous pouvez télécharger l'image à partir de http://registry.uipath.com/.

   Note that version 1.0.0 only supports the Connected proxy, whereas versions 2.0.0+ also support the Disconnected proxy.

   Utilisez cette commande pour obtenir l'image :

   $bytes = [System.Security.Cryptography.RandomNumberGenerator]::GetBytes(64);
   $jwtSigningKey = [Convert]::ToBase64String($bytes);
   docker run -e LICENSE_AGREEMENT=accept -e Jwt__Keys__0=$jwtSigningKey -p 8000:8080 registry.uipath.com/orchestrator-credentialsproxy:1.0.0

   Il s'agit de l'image UiPath par défaut, qui contient les magasins d'informations d'identification déjà disponibles dans votre compte cloud. Vous pouvez déployer l'image dans l'environnement cloud de votre choix.

   La commande ci-dessus génère également la clé secrète.

2. Créer votre propre image Docker personnalisée

   Vous pouvez créer votre propre image Docker, avec des assemblys supplémentaires, sur la base de l'image fournie par UiPath et téléchargée à l'étape 1. Pour ce faire :

   1. Créez un fichier Dockerfile (à des fins d'illustration, nous le nommerons CustomDockerfile) et ajoutez-y les éléments suivants :

      FROM {docker-image-path}
      RUN rm -rf ./plugins 
      COPY --chown=1001:0 {path of your custom assemblies} ./plugins 
      ENTRYPOINT ["dotnet", "UiPath.OrchestratorCredentialsProxy.dll"]

      • Remplacez {docker-image-path} par le chemin d'accès à l'image Docker initiale, fournie par UiPath.
      • Remplacez {path of your custom assemblies} par le chemin d'accès à vos propres fichiers .dll du magasin d'informations d'identification.

      Découvrez comment Visual Studio utilise ce fichier Docker pour créer vos images et accélérer le débogage.
   2. Générez l'image Docker à l'aide de cette commande, qui inclut le nom du fichier Docker nouvellement créé :

      docker build -f CustomDockerfile . -t customproxy

   3. Exécutez l'image Docker :

      docker run --publish 8000:8080 -e LICENSE_AGREEMENT="accept" -e Jwt__Keys__0=$jwtSigningKey -e appSettings__Plugins.SecureStores="{your-list-of-assemblies}" customproxy

      • Remplacez {your-list-of-assemblies} par les fichiers .dll des magasins d'informations d'identification personnalisés que vous souhaitez ajouter à Orchestrator.
      Pour exécuter l'image avec un paramètre Jwt:Keys :

      docker run --publish 8000:8080 -e LICENSE_AGREEMENT="accept" -e Jwt__Keys__0=$jwtSigningKey {docker-image-name}

      Pour exécuter l'image avec plusieurs paramètres Jwt:Keys :

      docker run --publish 8000:8080 -e LICENSE_AGREEMENT="accept" -e Jwt__Keys__0==$jwtSigningKey" -e Jwt__Keys__1==$jwtSigningKey" -e Jwt__Keys__2==$jwtSigningKey ... {docker-image-name}

      • Remplacez {docker-image-name} par le nom que vous avez défini pour votre image Docker personnalisée.

      Pour exécuter l'image avec une valeur personnalisée pour le paramètre appSettings:Plugins.SecureStores (c'est-à-dire avec le magasin d'informations d'identification souhaité), remplacez le contenu de ce paramètre par vos propres fichiers .dll : du magasin d'informations d'identification :

      docker run --publish 8000:8080 -e LICENSE_AGREEMENT="accept" -e Jwt__Keys__0=$jwtSigningKey -e appSettings__Plugins.SecureStores="UiPath.Orchestrator.CyberArk.dll;UiPath.Orchestrator.AzureKeyVault.SecureStore.dll" {docker-image-name}

   4. (Facultatif) Tester la nouvelle image Docker
      Pour tester votre image, accédez à son interface Swagger (http://localhost:8000/swagger/index.html) et vérifiez que les points de terminaison fonctionnent.

Configuration

La première étape de configuration de votre proxy consiste à ajouter les fichiers .dll que vous souhaitez utiliser dans le dossier C:\Program Files\UiPath\CredentialsProxy\plugins.

Les étapes suivantes s'appliquent uniquement au proxy déconnecté, car le proxy connecté ne nécessite pas de configuration spécifique.

Proxy déconnecté

Ce type de proxy est complètement séparé d'Orchestrator, de sorte que vous devez fournir les informations relatives aux coffres d'informations d'identification localement, dans le fichier de configuration appsettings.Production.json, qui se trouve à l'emplacement suivant : C:\Program Files\UiPath\OrchestratorCredentialsProxy\appsettings.Production.json.

Voici les champs qui doivent être modifiés dans ce fichier, dans la section AppSettings > SecureStoreConfigurations :

• Key : la clé d'identification de la configuration
• Type : le type de coffre d'informations d'identification, tel qu'identifié dans les fichiers .dll configurés via le paramètre Plugins.SecureStores trouvé dans appsettings.json (voir les exemples ci-dessous)
• Context : les informations de connectivité liées à l'implémentation du magasin sécurisé

Important :

Une fois que vous avez modifié le fichier de configuration, vous devez redémarrer le service à partir d'IIS.

Exemples de configuration

Il s'agit d'exemples que vous devez ajouter au fichier de configuration appsettings.Production.json afin de démarrer le proxy déconnecté. Si vous ne le faites pas, le service ne démarrera pas.

Choisissez l'exemple approprié en fonction de votre type de magasin d'informations d'identification ou ajoutez plusieurs magasins d'informations d'identification en utilisant le tout dernier exemple de cette page.

AWS Secrets Manager/AWS Secrets Manager (lecture seule)

"SecureStoreConfigurations": [
      {
        "Key": "<MyAwsStore>",
        "Type": "AWS Secrets Manager" / "AWS Secrets Manager (read only)",
        "Context": {
          "UseDefaultCredentials": "true",
          "AccessKey": "<AccessKey>",
          "SecretKey": "<SecretKey>",
          "Region": "<SelectedRegion>"
        }
      },
    ]

Azure Key Vault (lecture seule)

"SecureStoreConfigurations": [
      {
        "Key": "<MyAzureStore>",
        "Type": "AzureKeyVault (read only)",
        "Context": {
          "KeyVaultUri": "<KeyVaultUri>",
          "DirectoryId": "<DirectoryId>",
          "ClientId": "<ClientId>",
          "ClientSecret": "<ClientSecret>"
        }
      },
    ]

Important :

Azure Key Vault (lecture/écriture) n'est pas pris en charge.

Comptes gérés sécurisés par mot de passe BeyondTrust (BeyondTrust Password Safe - Managed Accounts)

"SecureStoreConfigurations": [
      {
        "Key": "<MyBeyondTrustManagedAccountsSafe>",
        "Type": "BeyondTrust Password Safe - Managed Accounts",
        "Context": {
          "Hostname": "<HostName>",
          "APIRegistrationKey": "<ApiRegistrationKey>",
          "APIRunAsUsername": "<Username>",
          "DefaultManagedSystemName": "", // can be empty or a string
          "SystemAccountDelimiter": "/", // default account delimiter is "/", but it can be changed
          "ManagedAccountType": "<ManagedAccountType>" // expected value is one of "system", "domainlinked", "database", "cloud", "application"
        }
      },
    ]

Mots de passe d'équipe sécurisés par mot de passe BeyondTrust (BeyondTrust Password Safe - Team Passwords)

"SecureStoreConfigurations": [
      {
        "Key": "<MyBeyondTrustTeamPasswordSafe>",
        "Type": "BeyondTrust Password Safe - Team Passwords",
        "Context": {
          "Hostname": "<HostName>",
          "APIRegistrationKey": "<ApiRegistrationKey>",
          "APIRunAsUsername": "<Username>",
          "FolderPathPrefix" : "/", // default delimiter is "/", but it can be changed
          "FolderPasswordDelimiter" : "/" // default delimiter is "/", but it can be changed
        }
      },
    ]

CyberArk - AIM

"SecureStoreConfigurations": [
      {
        "Key": "<MyCyberArk>",
        "Type": "CyberArk",
        "Context": {
          "ApplicationId": "<App_MyCyberArk>",
          "Safe": "<Passwords>",
          "Folder": "<MyFolder>"
        }
      },
    ]

CyberArk - CCP

"SecureStoreConfigurations": [
      {
        "Key": "<MyCyberArkCCPStore>",
        "Type": "CyberArkCCP",
        "Context": {
          "ApplicationId": "<ApplicationId>",
          "Safe": "<CyberArkSafe>",
          "Folder": "<CyberArkFolder>",
          "WebServiceUrl": "<CentralCredentialProviderUrl>",
          "WebServiceName": "<WebServiceName>",
          "SerializedClientCertificate": "<ClientCertificate>", // must be ".pfx" as base64
          "ClientCertificatePassword": "<ClientCertificatePassword>",
          "SerializedRootCA": "<someServerRootCA>" // must be ".crt" or ".cer" as base64
        }
      },
    ]

En fonction de votre configuration d'IIS, vous devrez peut-être configurer des éléments KeyStorageFlags supplémentaires comme suit :

"AppSettings": {
...
"Plugins.SecureStores.CyberArkCCP.KeyStorageFlags": "MachineKeySet",
...
}

CyberArk® Conjur Cloud (lecture seule)

"SecureStoreConfigurations": [
      {
        "Key": "MyCyberArkConjur",
        "Type": "CyberArk Conjur Cloud (read only)",
        "Context": {
          "ServiceUrl": "https://{myCyberArkConjurUrl}/",
          "LoginName": "{myLoginName}",
          "ApiKey": "{myApiKey}",
          "VariableIdPrefix": "{myPrefix}"
        }
      },
    ]

HashiCorp Vault/HashiCorp Vault (lecture seule)

"SecureStoreConfigurations": [
      {
        "Key": "<MyHashiCorp>",
        "Type": "HashiCorp Vault" / "HashiCorp Vault (read only)",
        "Context": {
          "VaultUri": "<VaultUri>",
          "AuthenticationType": "<AppRole>",
          "RoleId": "<RoleId>",
          "SecretId": "<SecretId>",
          "Username": "<Username>",
          "Password": "<Password>",
          "Token": "<Token>",
          "SecretsEngine": "<KeyValueV2>",
          "SecretsEngineMountPath": "<Secret>",
          "DataPath": "<applications/orchestrator>",
          "Namespace": "<orchestrator>"
        }
      },
    ]

Thycotic Secret Server

"SecureStoreConfigurations": [
      {
        "Key": "<MyThicoticServer>",
        "Type": "Thycotic Secret Server",
        "Context": {
          "SecretServerUrl": "<ServerUrl>",
          "RuleName": "<Rule>",
          "RuleKey": "<Key>",
          "UsernameField": "<Username>",
          "PasswordField": "<Password>"
        }
      },
    ]

Plusieurs magasins d'informations d'identification

Si vous utilisez plusieurs magasins d'informations d'identification, vous pouvez les ajouter l'un sous l'autre, comme suit :

{
...
  "AppSettings": {
  ...
    "SecureStoreConfigurations": [
      {
        "Key": "<SecureStoreKey1>",
        "Type": "AzureKeyVault (read only)",
        "Context": {
          "KeyVaultUri": "<Uri>",
          "DirectoryId": "<DirectoryId>",
          "ClientId": "<ClientId>",
          "ClientSecret": "<ClientSecret>"
        }
      },
      {
        "Key": "<SecureStoreKey2>",
        "Type": "BeyondTrust Password Safe - Managed Accounts",
        "Context": {
          "Hostname": "<Host>",
          "APIRegistrationKey": "<ApiKey>",
          "APIRunAsUsername": "<ApiUsername>",
          "DefaultManagedSystemName": "",
          "SystemAccountDelimiter": "/",
          "ManagedAccountType": "system"
        }
      }
    ]
  ...
  }
}

Validation

Important :

Cela s'applique uniquement au Credentials Proxy déconnecté.

Le proxy valide la configuration au démarrage si le type qu'il détecte est Disconnected.

Voici quelques-unes des étapes de validation effectuées :

• Il garantit que appsettings.Production.json contient les configurations attendues, comme détaillé dans la section Configuration ci-dessus.
• Il garantit que SecureStoreConfigurations ne contient pas de paramètres Key en double, autrement dit, que les magasins d'identifiants configurés dans le fichier appsettings.Production.json sont uniques.

• Le paramètre SecureStoreConfigurations est un tableau de configurations, ce qui signifie que vous pouvez ajouter autant de magasins d'informations d'identification que vous le souhaitez, même du même type. Par exemple, vous pouvez avoir plusieurs instances Azure Key Vault (lecture seule) configurées, tant que le champ Key est unique.

• Il vérifie que toutes les valeurs Type sont valides.

• En fonction de l'implémentation de chaque magasin sécurisé, il vérifie que le coffre est accessible avec succès.

Journalisation

Les journaux du Credentials Proxy Orchestrator sont stockés localement, dans le dossier C:\Program Files\UiPath\OrchestratorCredentialsProxy, si le pool d'applications du proxy dispose d'autorisations d'écriture pour ce chemin d'accès. Ils sont configurés dans IIS.

Si vous ne souhaitez pas accorder d'autorisations d'écriture à ce dossier, vous pouvez fournir un chemin d'accès relatif ou absolu de votre choix via le paramètre NLog.targets.logfile.fileName dans appsettings.Production.json.

Sur les machines Windows, le proxy stocke également les journaux dans l'Observateur d'événements (Event Viewer) de Windows.

Considérations de sécurité

• Orchestrator autorise uniquement les URL sécurisées (HTTPS) pour le proxy. Le certificat HTTPS doit être valide et signé par une autorité de certification largement reconnue. Les certificats auto-signés ou signés par une autorité interne ne sont pas pris en charge.
• Orchestrator est validé via une clé secrète de client générée par le Orchestrator Credentials Proxy. La clé secrète du client est stockée dans un fichier de configuration sur la machine où le Orchestrator Credentials Proxy est installé, et est chiffrée et stockée dans la base de données par Orchestrator.
• Lors de la modification d'un proxy de magasin d'informations d'identification dans Orchestrator et de la modification de son URL, vous devez également saisir la clé secrète du client.

• Orchestrator Credentials Proxy 2.0.0 et versions ultérieures les actions sont consignées dans l'Observateur d'événements (Event Viewer) dans Windows.

• Les binaires doivent être signés sur la machine Windows.
• L'image Docker doit être signée.

Utiliser l’Orchestrator Credentials Proxy avec un équilibreur de charge

Vous pouvez utiliser le proxy en combinaison avec un équilibreur de charge, tant que vous vous assurez de conserver la même configuration sur tous les nœuds.

Éléments qui doivent rester identiques sur les nœuds

• La version du programme d’installation du proxy. Par exemple, si vous utilisez la version 1.0.0, tous les nœuds de l’équilibreur de charge doivent également utiliser la version 1.0.0.
• Les paramètres dans les fichiers de configuration de l’application. Dans la plupart des cas, il s’agit de appsettings.json et appsettings.Production.json. Notez que appsettings.Production.json est unique pour chaque installation, vous devez donc l’ajouter manuellement à chaque nœud afin d’assurer la cohérence.
• Les plug-ins du magasin d’informations d’identification ajoutés à path/plugins. Tous les plugins que nous prenons en charge se trouvent déjà dans ce dossier, vous devez donc principalement faire attention aux plugins personnalisés que vous ajoutez.

Éléments importants à prendre en compte

• Si vous souhaitez apporter des modifications à la configuration de l’image Docker que nous fournissons pour l’installation du proxy, nous vous recommandons fortement de créer une image Docker personnalisée à la place. Vous devez ensuite utiliser cette image personnalisée pour déployer le proxy sur tous les nœuds.
• Some environment variables, such as those that override appsettings.json configuration values or those that affect .NET environment, can have an impact at runtime.
• You can use the https://{YourOrchestratorCredentialsProxyURL}/api/v1/Health dedicated unauthenticated endpoint to check whether the Orchestrator Credentials Proxy is still running.

Mettre à jour le certificat Orchestrator Credentials Proxy

Pour les installations à nœud unique, mettez à jour le certificat SSL comme suit :

1. Importez le nouveau certificat dans le dossier Personnel, sous Certificats, dans la console de certificats de la machine locale (certlm.msc).
2. Dans la console de gestion IIS, développez Sites et sélectionnez UiPath Orchestrator Credential Proxy.
3. Dans le panneau de droite, sélectionnez Liaisons....
4. Dans la vue Liaisons..., sélectionnez l’enregistrement https par défaut, puis utilisez le bouton Sélectionner... pour choisir un certificat.
5. Dans la fenêtre contextuelle Sélectionner un certificat (Select Certificate), sélectionnez le certificat récemment ajouté.
6. Sélectionnez OK jusqu’à ce que la configuration soit terminée.

Remarque :

Pour les installations multi-nœuds, veillez à bien mettre à jour le certificat sur toutes les machines.

Pour mettre à jour le certificat pour les installations utilisant un équilibreur de charge, suivez les mêmes étapes que celles décrites ci-dessus. Étant donné que Orchestrator Credentials Proxy est dépourvu d’état, supprimez le nœud de l’équilibreur de charge lors de la mise à jour du certificat.