Suporte KeyVaultReference para aplicações do Service Fabric implementados no Azure.

  • Artigo

Um desafio comum ao criar aplicativos em nuvem é descobrir como distribuir segredos com segurança para seus aplicativos e gerenciá-los. O suporte a KeyVaultReference do Service Fabric facilita isso. Uma vez configurado, você pode fazer referência à URL do segredo armazenado no Cofre da Chave em sua definição de aplicativo e o Service Fabric cuidará de buscar esse segredo e ativar seu aplicativo com ele. Ao usar a versão "gerenciada por SF" do recurso, o Service Fabric também pode monitorar seu Cofre de Chaves e acionar automaticamente atualizações contínuas de parâmetros de aplicativos à medida que seus segredos giram no cofre.

Opções para entregar segredos a aplicativos no Service Fabric

A maneira clássica de entregar segredos a um aplicativo do Service Fabric era declarar parâmetros criptografados. Isso envolvia criptografar segredos em um certificado de criptografia e passar esses segredos criptografados para seu aplicativo. Esse método tem algumas desvantagens: a necessidade de gerenciar o certificado de criptografia, a exposição dos segredos no pipeline de implantação e a falta de visibilidade dos metadados dos segredos anexados a um aplicativo implantado. Da mesma forma, a rotação de segredos requer uma implantação de aplicativo. A menos que você esteja executando um cluster autônomo, não recomendamos mais o uso de parâmetros criptografados.

Outra opção é o uso de Referências de Loja Secreta. Essa experiência permite o gerenciamento central dos segredos do aplicativo, melhor visibilidade dos metadados dos segredos implantados e permite o gerenciamento central do certificado de criptografia. Alguns podem preferir esse estilo de gerenciamento secreto ao executar clusters autônomos do Service Fabric.

A recomendação hoje é reduzir a dependência de segredos sempre que possível usando identidades gerenciadas para aplicativos do Service Fabric. As identidades gerenciadas podem ser usadas para autenticar diretamente no Armazenamento do Azure, no SQL do Azure e muito mais. Isso significa que não há necessidade de gerenciar uma credencial separada ao acessar os serviços do Azure que dão suporte à autenticação do Microsoft Entra.

Quando não for possível usar o Managed Identity como cliente, recomendamos o uso de KeyVaultReferences. Você deve usar KeyVaultReferences em vez de usar Managed Identity para ir diretamente para o Key Vault. KeyVaultReferences ajuda a aumentar a disponibilidade do seu aplicativo porque impõe que alterações secretas aconteçam durante atualizações contínuas. Ele também é melhor dimensionado à medida que os segredos são armazenados em cache e servidos de dentro do cluster. Se seu aplicativo usa parâmetros criptografados hoje, há apenas alterações mínimas necessárias no código do aplicativo para usar KeyVaultReferences. Seu aplicativo pode continuar a esperar criar um único segredo, e que esse segredo seja o mesmo durante o tempo de vida do processo.

Pré-requisitos

  • Identidade gerenciada para aplicativos do Service Fabric

    O suporte a KeyVaultReference do Service Fabric usa a Identidade Gerenciada de um aplicativo para buscar segredos em nome do aplicativo. Você deve implantar seu aplicativo via ARM e atribuir-lhe uma identidade gerenciada. Siga este documento para habilitar a identidade gerenciada para seu aplicativo.

  • Loja Central de Segredos (CSS).

    O Repositório de Segredos Centrais (CSS) é o cache de segredos locais criptografados do Service Fabric. Esse recurso usa CSS para proteger e persistir segredos depois que eles são buscados no Cofre da Chave. A habilitação deste serviço do sistema é necessária para usar KeyVaultReferences. Siga este documento para habilitar e configurar o CSS.

  • Conceder permissão de acesso de identidade gerenciada do aplicativo ao Cofre da Chave

    Consulte este documento para ver como conceder acesso de identidade gerenciada ao Cofre de Chaves. Observe também que, se você estiver usando a identidade gerenciada atribuída ao sistema, a identidade gerenciada será criada somente após a implantação do aplicativo. Isso pode criar condições de corrida em que o aplicativo tenta acessar o segredo antes que a identidade possa ter acesso ao cofre. O nome da identidade atribuída ao sistema será {cluster name}/{application name}/{service name}.

KeyVaultReferences vs. KeyVaultReferences Gerenciado

A ideia básica de KeyVaultReferences é que, em vez de definir o valor do parâmetro do seu aplicativo como seu segredo, você o defina como o URL do Cofre da Chave, que será resolvido para o valor secreto após a ativação do seu aplicativo. No Key Vault, um único segredo, por exemplo, pode ter várias versões, por exemplo, https://my.vault.azure.net/secrets/MySecret/https://my.vault.azure.net/secrets/MySecret/<oid1> e <oid2>. Quando você usa um KeyVaultReference, o valor deve ser uma referência versionada (https://my.vault.azure.net/secrets/MySecret/<oid1>). Se você girar esse segredo no cofre, por exemplo, para , deverá acionar uma atualização de aplicativo para <oid2>a nova referência. Quando você usa um ManagedKeyVaultReference, o valor deve ser uma referência sem versão (https://my.vault.azure.net/secrets/MySecret/). O Service Fabric resolverá a instância <oid1> mais recente e ativará o aplicativo com esse segredo. Se você girar o segredo no cofre para <oid2>o , o Service Fabric acionará automaticamente uma atualização de parâmetro de aplicativo para ser movida em <oid2> seu nome.

Nota

O suporte a KeyVaultReference (segredos versionados) para aplicativos do Service Fabric está geralmente disponível a partir da versão 7.2 CU5 do Service Fabric. É recomendável que você atualize para esta versão antes de usar esse recurso.

Nota

O suporte gerenciado de KeyVaultReference (segredos sem versão) para aplicativos do Service Fabric está geralmente disponível a partir da versão 9.0 do Service Fabric.

Use KeyVaultReferences em seu aplicativo

KeyVaultReferences pode ser consumido

Como variável de ambiente

<EnvironmentVariables>
      <EnvironmentVariable Name="MySecret" Type="KeyVaultReference" Value="<KeyVaultURL>"/>
</EnvironmentVariables>

string secret =  Environment.GetEnvironmentVariable("MySecret");

Montado como um arquivo em seu contêiner

  • Adicione uma secção às definições.xml

    Definir MySecret parâmetro com Tipo KeyVaultReference e Valor <KeyVaultURL>

    <Section Name="MySecrets">
    <Parameter Name="MySecret" Type="KeyVaultReference" Value="<KeyVaultURL>"/>
</Section>

  • Consulte a nova seção em ApplicationManifest.xml em <ConfigPackagePolicies>

    <ServiceManifestImport>
    <Policies>
    <IdentityBindingPolicy ServiceIdentityRef="MyServiceMI" ApplicationIdentityRef="MyApplicationMI" />
    <ConfigPackagePolicies CodePackageRef="Code">
        <!--Linux container example-->
        <ConfigPackage Name="Config" SectionName="MySecrets" EnvironmentVariableName="SecretPath" MountPoint="/var/secrets"/>
        <!--Windows container example-->
        <!-- <ConfigPackage Name="Config" SectionName="dbsecrets" EnvironmentVariableName="SecretPath" MountPoint="C:\secrets"/> -->
    </ConfigPackagePolicies>
    </Policies>
</ServiceManifestImport>

  • Consumir os segredos do código de serviço

    Cada parâmetro listado em <Section Name=MySecrets> será um arquivo na pasta apontada por EnvironmentVariable SecretPath. O trecho de código C# abaixo mostra como ler MySecret do seu aplicativo.

    string secretPath = Environment.GetEnvironmentVariable("SecretPath");
using (StreamReader sr = new StreamReader(Path.Combine(secretPath, "MySecret"))) 
{
    string secret =  sr.ReadToEnd();
}

    Nota

    MountPoint controla a pasta onde os arquivos contendo valores secretos serão montados.

Como referência a uma senha de repositório de contêiner

 <Policies>
      <ContainerHostPolicies CodePackageRef="Code">
        <RepositoryCredentials AccountName="MyACRUser" Type="KeyVaultReference" Password="<KeyVaultURL>"/>
      </ContainerHostPolicies>

Usar Managed KeyVaultReferences em seu aplicativo

Primeiro, você deve habilitar o monitoramento secreto atualizando sua definição de cluster para adicionar a EnableSecretMonitoring configuração, além das outras configurações CSS necessárias:

"fabricSettings": [
    {
        "name": "CentralSecretService",     
        "parameters": [
            {
                "name": "EnableSecretMonitoring",
                "value": "true"
            },
            {
                "name":  "DeployedState",
                "value":  "enabled"
            },
            {
                "name" : "EncryptionCertificateThumbprint",
                "value": "<thumbprint>"
            },
            {
                "name":  "MinReplicaSetSize",
                "value":  "<size>"
            },
            {
                "name":  "TargetReplicaSetSize",
                "value":  "<size>"
            }
        ]
    }
],

Nota

O padrão pode se tornar true no futuro

Após a conclusão da atualização do cluster, seu aplicativo de usuário poderá ser atualizado. Em qualquer lugar onde um KeyVaultReference possa ser usado, um ManagedKeyVaultReference também pode ser usado, por exemplo,

    <Section Name="MySecrets">
        <Parameter Name="MySecret" Type="ManagedKeyVaultReference" Value="[MySecretReference]"/>
    </Section>

A principal diferença na especificação de ManagedKeyVaultReferences é que eles não podem ser codificados no manifesto do tipo de aplicativo. Eles devem ser declarados como parâmetros no nível do aplicativo e, além disso, devem ser substituídos na definição do aplicativo ARM.

Aqui está um trecho de um manifesto bem formado:

<?xml version="1.0" encoding="utf-8"?>
<ApplicationManifest ApplicationTypeName="MyAppType" ApplicationTypeVersion="1.0.0">
  <Parameters>
    <Parameter Name="MySecretReference" DefaultValue="" />
  </Parameters>
  <ServiceManifestImport>
    <EnvironmentOverrides CodePackageRef="Code">
      <EnvironmentVariable Name="MySecret" Value="[MySecretReference]" Type="ManagedKeyVaultReference" />
    </EnvironmentOverrides>
    <Policies>
      <IdentityBindingPolicy ServiceIdentityRef="MySvcIdentity" ApplicationIdentityRef="MyAppIdentity" />
    </Policies>
  </ServiceManifestImport>
  <Principals>
    <ManagedIdentities>
      <ManagedIdentity Name="MyAppIdentity" />
    </ManagedIdentities>
  </Principals>
</ApplicationManifest>

e um excerto da definição de recurso da aplicação:

{
    "type": "Microsoft.ServiceFabric/clusters/applications",
    "name": "MyApp",
    "identity": {
        "type" : "userAssigned",
        "userAssignedIdentities": {
            "[variables('userAssignedIdentityResourceId')]": {}
        }
    },
    "properties": {
        "parameters": {
            "MySecretReference": "https://my.vault.azure.net/secrets/MySecret/"
        },
        "managedIdentities": [
            {
            "name" : "MyAppIdentity",
            "principalId" : "<guid>"
            }
        ]
    }
}

Declarar o ManagedKeyVaultReference como um parâmetro de aplicativo, bem como substituir esse parâmetro na implantação é necessário para que o Service Fabric gerencie com êxito o ciclo de vida do segredo implantado.

Próximos passos