O proxy de credenciais do orquestrador

Você pode adicionar seus próprios armazenamentos de credenciais ao Orchestrator, para controlar independentemente a segurança de seus dados de conexão.

Para fazê-lo, você pode carregar seus plug-ins de armazenamento de credenciais desejados, na forma de arquivos .dll, para o serviço da Web Orchestrator Credentials Proxy. O kit de instalação contém todos os plug-ins compatíveis com o UiPath, mas você também pode desenvolver seus próprios arquivos .dll de plug-in para carregar. Esse serviço torna seus plugins disponíveis para o Orchestrator por meio de um proxy, que é criado no Orchestrator com base no URL público e na chave secreta gerada pelo proxy.

Problema conhecido

Isso só se aplica a cenários em que a porta do Orchestrator Credentials Proxy é definida com um valor diferente do padrão 443.

Quando você atualiza a partir de qualquer versão entre a 1.0.0 e a 2.0.1 e você usa uma porta personalizada, a porta local na regra de entrada UiPathOrchestratorCredentialsProxy é alterada automaticamente para 443, que é o padrão. Isso impede que a conexão com o proxy seja estabelecida.

Para contornar isso, você precisa alterar manualmente a porta local na regra de entrada após a atualização.

Instalação

O Orchestrator Credentials Proxy pode ser instalado por meio de um arquivo .msi instalador ou por meio de uma imagem do Docker fornecida pela UiPath.

Requisitos de hardware e software

Requisitos de Hardware

Esses são os requisitos mínimos para executar o proxy em um Windows Server com IIS. As necessidades reais de recursos variam dependendo do uso individual.

Núcleos da CPU	BATER
2	4GB

Requisitos de software

As seguintes versões do Windows Server são necessárias para instalar o proxy:

• 2012 R2
• 2016
• 2019
• 2022

Por meio do instalador .msi instalador

Pré-requisitos

O seguinte é necessário para poder usar o proxy:

• ASP.NET Core versões 3.1, 6.0.x ou 8.0.x
• IIS versão 8.0 ou superior

• Os seguintes recursos do Windows devem ser instalados:

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

Passos de instalação

Siga estas etapas para realizar a instalação:

1. Baixe o instalador do Credential Proxy do UiPath Orchestrator no Customer Portal.
2. Instale o proxy.

   Proxy conectado

   • URL pública - a URL do Orchestrator Credentials Proxy que é exposta publicamente
   • Certificado SSL - o Assunto ou Impressão digital do certificado SSL usado para proteger conexões com o Credentials Proxy do Orchestrator. Este é o certificado SSL instalado no computador ou servidor web que hospeda o proxy.

     Observe que deve ser emitido por um provedor de certificados públicos e precisa ser válido para a URL Pública.

   • Porta - a porta correspondente ao URL público
   • Chave secreta - (gerada automaticamente) a chave necessária para configurar um proxy personalizado na interface do orquestrador; certifique-se de copiá-lo para a área de transferência para uso futuro.

     Isso pode ser alterado manualmente e também é adequado para rotação de chave.

   Proxy desconectado

   Essa funcionalidade só estará disponível se você estiver no plano de licenciamento Enterprise - Advanced.

   • Certificado SSL - o Assunto ou Impressão digital do certificado SSL usado para proteger conexões com o Credentials Proxy do Orchestrator. Este é o certificado SSL instalado no computador ou servidor web que hospeda o proxy.
   • Porta - a porta correspondente ao URL
   • Chave secreta - (gerada automaticamente) a chave necessária para configurar um proxy personalizado na interface do orquestrador; certifique-se de copiá-lo para a área de transferência para uso futuro.

     Isso pode ser alterado manualmente e também é adequado para rotação de chave.

   Após a instalação, o parâmetro AppSettings.CredentialsProxyType" id="1"/> no arquivo appsettings.Production.json" id="2"/> é definido como Desconectado. É assim que o proxy detecta o tipo na inicialização.

Por meio da imagem do Docker

Informação preliminar

Todas as configurações do Credentials Proxy do Orchestrator que podem ser editadas estão disponíveis em seu arquivo appsettings.json. Os seguintes parâmetros são importantes na configuração inicial:

• Jwt:Keys - (inicialmente vazio) este array de strings é usado para configurar a autenticação do proxy. Isso constitui a chave secreta que você usará durante o processo de criação do proxy e que permite ao Orchestrator recuperar dados do proxy com êxito. Quaisquer valores inválidos são ignorados. Se nenhum valor válido for encontrado, o proxy não será iniciado.

  As chaves secretas devem estar em base64 e podem ser geradas usando um dos scripts do PowerShell abaixo.

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

O script acima gera 64 bytes aleatórios (usando SeccureRandom) e os converte em uma string 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 - (inicialmente definido para os armazenamentos de credenciais padrão disponíveis no Orchestrator) esta é uma string CSV usada para especificar o que .dll os assemblies devem ser carregados do disco (de path/plugins) para permitir que armazenamentos seguros sejam usados pelo proxy. Adicionar assemblies inválidos à lista não interromperá a inicialização, mas você receberá erros de log ao tentar implantá-lo.
• appSettings:SigningCredentialSettings:FileLocation:SigningCredential:FilePath e appSettings:SigningCredentialSettings:FileLocation:SigningCredential:Password - (inicialmente oculto) para serem usados para criptografar os parâmetros Jwt:Keys e SecureStoreConfigurations:Context. Isso representa o caminho do arquivo para seu certificado de assinatura.
• appSettings:SigningCredentialSettings:StoreLocation:Name, appSettings:SigningCredentialSettings:StoreLocation:Location, appSettings:SigningCredentialSettings:StoreLocation:NameType - (inicialmente oculto) para ser usado para criptografar os parâmetros Jwt:Keys e SecureStoreConfigurations:Context.

Criptografando o parâmetro Jwt:Keys

Para adicionar uma camada extra de segurança, você pode criptografar os parâmetros Jwt:Keys e SecureStoreConfigurations:Context em seu arquivo appsettings.json.

Nota: Isso requer UiPath.ConfigProtector.exe versão 1.0.9 ou superior.

Configurando e executando a imagem do Docker

Para executar o Orchestrator Credentials Proxy usando o Docker, siga as etapas abaixo.

1. Baixe a imagem do Docker

   Você pode baixar a imagem em http://registry.uipath.com/.

   Observe que a versão 1.0.0 Apenas oferece suporte ao proxy conectado, enquanto as versões 2.0.0+ também oferecem suporte ao proxy desconectado.

   Use este comando para obter a imagem:

   $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

   Essa é a imagem UiPath padrão, que contém os armazenamentos de credenciais que já estão disponíveis em sua conta de nuvem. Você pode implantar a imagem no ambiente de nuvem da sua escolha.

   O comando acima também gera a chave secreta.

2. Crie sua própria imagem personalizada do Docker

   Você pode criar sua própria imagem do Docker, com assemblies adicionais, com base na imagem fornecida pelo UiPath e baixada na etapa 1. Fazer isso:

   1. Crie um novo Dockerfile (para fins de ilustração, vamos chamá-lo de CustomDockerfile) e adicione o seguinte a ele:

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

      • Substitua {docker-image-path} pelo caminho para a imagem inicial do Docker, fornecido por UiPath.
      • Substitua {path of your custom assemblies} pelo caminho para seu próprio armazenamento de credenciais .dll arquivos.

      Descubra como o Visual Studio usa esse Dockerfile para criar suas imagens para uma depuração mais rápida.
   2. Gere a imagem do Docker usando este comando, que inclui o nome do Dockerfile recém-criado:

      docker build -f CustomDockerfile . -t customproxy

   3. Execute a imagem do Docker:

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

      • Substitua {your-list-of-assemblies} pelo .dll arquivos dos armazenamentos de credenciais personalizados que você deseja adicionar ao Orchestrator.
      Para executar a imagem com um parâmetro Jwt:Keys :

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

      Para executar a imagem com vários parâmetros 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}

      • Substitua {docker-image-name} pelo nome que você definiu para sua imagem personalizada do Docker.

      Para executar a imagem com um valor personalizado para o parâmetro appSettings:Plugins.SecureStores (ou seja, com o armazenamento de credenciais desejado), substitua o conteúdo desse parâmetro por seu próprio armazenamento de credenciais .dll arquivos:

      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. (Opcional) Teste a nova imagem do Docker
      Para testar sua imagem, acesse sua interface Swagger (http://localhost:8000/swagger/index.html) e verifique se os endpoints estão funcionando.

Configuração

Connected and disconnected proxy

A primeira etapa na configuração de seu proxy é adicionar quaisquer plugins .dll personalizados que você deseja usar na pasta C:\Program Files\UiPath\CredentialsProxy\plugins" id="1"/>.

Some credential stores may require you to configure settings at the application, host, or proxy level. The settings are equivalent to their Orchestrator counterparts. You must specify these settings in the proxy's appsettings.Production.json file.

CyberArk

You must add any host-level settings such as CLIPasswordSDKExePath, UsePowerShellCLI, and AdditionalAllowedCharacters under the Appsettings parameter in the appsettings.Production.json file:

{
// ...
  "AppSettings": {
    "Plugins.SecureStores.CyberArk.CLIPasswordSDKExePath": "D:\\PathName\\CLIPasswordSDK.exe",
    // ...
  }
  // ...
}

CyberArkCCP

If you cannot retrieve the CyberArkCCP via proxy, add the following parameter in the appsettings.Production.json file:

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

Disconnected proxy-only

This proxy type is completely separated from Orchestrator, so you must provide the information related to the credential vaults locally, in the appsettings.Production.json configuration file. You can find the files at the following location: C:\Program Files\UiPath\OrchestratorCredentialsProxy\appsettings.Production.json.

You must edit the following fields in said file, in the AppSettings - SecureStoreConfigurations section:

• Key" id="1"/> - a chave de identificador para a configuração
• Type" id="1"/> - o tipo de cofre de credenciais, conforme identificado no .dll arquivos configurados por meio do parâmetro Plugins.SecureStores" id="2"/> encontrado em appsettings.json" id="3"/> (consulte os exemplos abaixo)
• Context" id="1"/> - as informações de conectividade relacionadas à implementação de armazenamento seguro

Importante:

Depois de editar o arquivo de configuração, você precisa reiniciar o serviço a partir do IIS.

Exemplos de configuração

You need to add the following samples to the appsettings.Production.json configuration file in order to start the disconnected proxy. Otherwise, the service will not start.

Escolha o exemplo apropriado com base em seu tipo de armazenamento de credenciais ou adicione vários armazenamentos de credenciais usando o último exemplo nesta página.

AWS Secrets Manager/AWS Secrets Manager (somente leitura)

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

Azure Key Vault (somente leitura)

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

Importante:

Azure Key Vault (leitura/gravação) não é compatível.

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

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
        }
      },
    ]

Based on your IIS configuration, you may need to configure additional KeyStorageFlags as follows:

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

CyberArk® Conjur Cloud (somente leitura)

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

HashiCorp Vault / HashiCorp Vault (somente leitura)

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

Vários armazenamentos de credenciais

If you use multiple credential stores, you can add one under the other, as follows:

{
...
  "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"
        }
      }
    ]
  ...
  }
}

Validação

Importante:

Isso se aplica apenas ao Credentials Proxy desconectado.

The proxy validates the configuration on startup, if the type it detects is Disconnected.

These are some of the validation steps the proxy performs:

• The proxy ensures that that appsettings.Production.json contains the expected configurations, as detailed in the Configuration section above.
• The proxy ensures that SecureStoreConfigurations does not contain any duplicate Key parameters, i.e. that the credential stores configured in the appsettings.Production.json file are unique.

• The SecureStoreConfigurations parameter is an array of configurations. You can add as many credential stores as you want, even of the same type. For example, you can have multiple Azure Key Vault (read only) instances configured, as long as the Key field is unique.

• The proxy checks that all Type values are valid.

• Based on the implementation of each secure store, the proxy checks that the vault can be reached successfully.

Geração de logs

Os logs de Credentials Proxy do Orchestrator serão armazenados localmente, na pasta C:\Program Files\UiPath\OrchestratorCredentialsProxy, se o pool de aplicativos do proxy tiver permissões de gravação para esse caminho. Estes são configurados no IIS.

If you do not want to give write permissions to that folder, provide a relative or absolute path of your choice via the NLog.targets.logfile.fileName parameter in appsettings.Production.json.

Em máquinas Windows, o proxy também armazena logs no Visualizador de eventos do Windows.

Considerações de segurança

• O Orchestrator permite apenas URLs seguras (HTTPS) para o proxy. O certificado HTTPS deve ser válido e assinado por uma autoridade de certificação amplamente reconhecida. Certificados autoassinados ou assinados por uma autoridade interna não são suportados.
• Orchestrator is validated through a client secret generated by the Orchestrator Credentials Proxy. The client secret is stored in a configuration file on the machine where the Orchestrator Credentials Proxy is installed, and it is encrypted and stored in the database by Orchestrator.
• When you edit a credential store proxy in Orchestrator and changing its URL, you must enter the client secret.

• Orchestrator Credentials Proxy 2.0.0+ as ações são registradas em log no Visualizador de Eventos do Windows.

• Os binários devem ser assinados na máquina Windows.
• A imagem do Docker deve ser assinada.

Uso do Credentials Proxy do Orchestrator com um balanceador de carga

If you use the proxy in combination with a load balancer, make sure that you maintain the same configuration across all nodes.

Elementos que devem permanecer idênticos entre os nós

• A versão do instalador de proxy. Por exemplo, se você usar a versão 1.0.0, todos os nós do balanceador de carga também precisarão usar a 1.0.0.
• As configurações nos arquivos de configuração do aplicativo. Na maioria dos casos, eles são appsettings.jsone appsettings.Production.json. Observe que appsettings.Production.json é exclusivo para cada instalação, então você deve adicioná-lo manualmente a cada nó para garantir a consistência.
• The credential store plugins added to path/plugins. All plugins supported by us are already in this folder, so you only need to be mindful of any custom plugins you add.

Fatores importantes a considerar

• If you want to make any changes to the Docker image configuration, we provide for installing the proxy, we highly recommend that you create a custom Docker image instead. You should then use this custom image to deploy the proxy on all nodes.
• Some environment variables can have an impact at runtime. For example, environment variables that override appsettings.json configuration values or those that affect .NET environment.
• You can use the https://{YourOrchestratorCredentialsProxyURL}/api/v1/Health dedicated unauthenticated endpoint to check if the Orchestrator Credentials Proxy is still running.

Atualização do certificado Credentials Proxy do Orchestrator

Para instalações de nó único, atualize o certificado SSL da seguinte forma:

1. Importe o novo certificado para a pasta Pessoal, em Certificados, no console de certificados da máquina local (certlm.msc).
2. No Console de Gerenciamento IIS, expanda Sites e selecione Credential Proxy do UiPath Orchestrator.
3. No painel do lado direito, selecione Ligações....
4. Na visualização Ligações... selecione o registro padrão https e, em seguida, use o botão Selecionar... para escolher um certificado.
5. Na janela pop-up Selecionar certificado, selecione o certificado recém-adicionado.
6. Selecione OK até concluir a configuração.

Observação:

Para instalações de vários nós, certifique-se de atualizar o certificado em todas as máquinas.

Para atualizar o certificado para instalações usando um balanceador de carga, use as mesmas etapas descritas acima. Como o Orchestrator Credentials Proxy é sem estado, remova o nó do balanceador de carga ao atualizar o certificado.