Gestione dei segreti nelle applicazioni di Service FabricManaging secrets in Service Fabric applications

Questa guida descrive la procedura di gestione dei segreti in un'applicazione di Service Fabric.This guide walks you through the steps of managing secrets in a Service Fabric application. I segreti possono essere informazioni riservate, ad esempio le stringhe di connessione di archiviazione, le password o altri valori che non devono essere gestiti in testo normale.Secrets can be any sensitive information, such as storage connection strings, passwords, or other values that should not be handled in plain text.

Questa guida usa l'insieme di credenziali delle chiavi di Azure per gestire chiavi e segreti.This guide uses Azure Key Vault to manage keys and secrets. Tuttavia, l' uso di segreti in un'applicazione è indipendente dalla piattaforma cloud per consentire alle applicazioni di essere distribuite in un cluster ospitato in un punto qualsiasi.However, using secrets in an application is cloud platform-agnostic to allow applications to be deployed to a cluster hosted anywhere.

PanoramicaOverview

Il metodo consigliato per gestire le impostazioni di configurazione del servizio è tramite i pacchetti di configurazione del servizio.The recommended way to manage service configuration settings is through service configuration packages. I pacchetti di configurazione dispongono di controllo delle versioni e sono aggiornabili tramite gli aggiornamenti in sequenza gestiti con convalida dell'integrità e rollback automatico.Configuration packages are versioned and updatable through managed rolling upgrades with health-validation and auto rollback. Questo approccio è da preferire alla configurazione globale in quanto riduce le probabilità di un'interruzione del servizio globale.This is preferred to global configuration as it reduces the chances of a global service outage. I segreti crittografati non rappresentano un'eccezione.Encrypted secrets are no exception. Service Fabric offre funzionalità incorporate per crittografare e decrittografare i valori in un file Settings.xml del pacchetto configurazione tramite la crittografia del certificato.Service Fabric has built-in features for encrypting and decrypting values in a configuration package Settings.xml file using certificate encryption.

Il diagramma seguente illustra il flusso di base per la gestione dei segreti in un'applicazione di Service Fabric:The following diagram illustrates the basic flow for secret management in a Service Fabric application:

panoramica della gestione dei segreti

In questo flusso sono presenti quattro passaggi principali:There are four main steps in this flow:

  1. Ottenere un certificato di crittografia dei dati.Obtain a data encipherment certificate.
  2. Installare il certificato nel cluster.Install the certificate in your cluster.
  3. Crittografare i valori dei segreti quando si distribuisce un'applicazione con il certificato e inserirli nel file di configurazione Settings.xml del servizio.Encrypt secret values when deploying an application with the certificate and inject them into a service's Settings.xml configuration file.
  4. Leggere i valori crittografati risultati da Settings. XML eseguendo la decrittografia con lo stesso certificato di crittografia.Read encrypted values out of Settings.xml by decrypting with the same encipherment certificate.

Azure Key Vault viene usato come percorso di archiviazione sicuro per i certificati e come un modo per ottenere i certificati installati nei cluster Service Fabric in Azure.Azure Key Vault is used here as a safe storage location for certificates and as a way to get certificates installed on Service Fabric clusters in Azure. Se non si esegue la distribuzione in Azure, non è necessario usare l'insieme di credenziali delle chiavi per gestire i segreti nelle applicazioni di Service Fabric.If you are not deploying to Azure, you do not need to use Key Vault to manage secrets in Service Fabric applications.

Certificato di crittografia dei datiData encipherment certificate

Il certificato di crittografia dei dati viene usato esclusivamente per la crittografia e decrittografia dei valori di configurazione del file Settings.xml del servizio e non viene impiegato per l'autenticazione o la firma di testo crittografato.A data encipherment certificate is used strictly for encryption and decryption of configuration values in a service's Settings.xml and is not used for authentication or signing of cipher text. Il certificato deve soddisfare i requisiti seguenti:The certificate must meet the following requirements:

  • Il certificato deve includere una chiave privata.The certificate must contain a private key.
  • Il certificato deve essere stato creato per lo scambio di chiave, esportabile in un file con estensione pfx (Personal Information Exchange).The certificate must be created for key exchange, exportable to a Personal Information Exchange (.pfx) file.
  • L'uso delle chiavi del certificato deve includere la crittografia dei dati (10) e non deve includere l'autenticazione del server o del client.The certificate key usage must include Data Encipherment (10), and should not include Server Authentication or Client Authentication.

    Ad esempio, quando si crea un certificato autofirmato tramite PowerShell, il flag KeyUsage deve essere impostato su DataEncipherment:For example, when creating a self-signed certificate using PowerShell, the KeyUsage flag must be set to DataEncipherment:

    New-SelfSignedCertificate -Type DocumentEncryptionCert -KeyUsage DataEncipherment -Subject mydataenciphermentcert -Provider 'Microsoft Enhanced Cryptographic Provider v1.0'
    

Installare il certificato nel clusterInstall the certificate in your cluster

Questo certificato deve essere installato su ogni nodo del cluster.This certificate must be installed on each node in the cluster. Verrà usato in fase di esecuzione per decrittografare i valori archiviati in nel file Settings.xml del servizio.It will be used at runtime to decrypt values stored in a service's Settings.xml. Per le istruzioni di installazione, vedere l'articolo che spiega come creare un cluster con Azure Resource Manager.See how to create a cluster using Azure Resource Manager for setup instructions.

Eseguire la crittografia dei segreti dell'applicazioneEncrypt application secrets

L'SDK di Service Fabric ha funzioni di crittografia e decrittografia dei segreti predefinite.The Service Fabric SDK has built-in secret encryption and decryption functions. I valori dei segreti possono essere crittografati in fase di compilazione e quindi decrittografati e letti a livello di programmazione nel codice del servizio.Secret values can be encrypted at built-time and then decrypted and read programmatically in service code.

Il comando PowerShell seguente viene usato per crittografare un segreto.The following PowerShell command is used to encrypt a secret. Questo comando consente unicamente di crittografare il valore e non firma il testo crittografato.This command only encrypts the value; it does not sign the cipher text. È necessario usare lo stesso certificato di crittografia installato nel cluster per produrre il testo crittografato per i valori del segreto:You must use the same encipherment certificate that is installed in your cluster to produce ciphertext for secret values:

Invoke-ServiceFabricEncryptText -CertStore -CertThumbprint "<thumbprint>" -Text "mysecret" -StoreLocation CurrentUser -StoreName My

La stringa Base 64 risultante contiene sia il testo crittografato dei segreti che le informazioni relative al certificato usato per crittografarlo.The resulting base-64 string contains both the secret ciphertext as well as information about the certificate that was used to encrypt it. La stringa con codifica Base 64 può essere inserita in un parametro nel file di configurazione Settings.xml del servizio con l'attributo IsEncrypted impostato su true:The base-64 encoded string can be inserted into a parameter in your service's Settings.xml configuration file with the IsEncrypted attribute set to true:

<?xml version="1.0" encoding="utf-8" ?>
<Settings xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://schemas.microsoft.com/2011/01/fabric">
  <Section Name="MySettings">
    <Parameter Name="MySecret" IsEncrypted="true" Value="I6jCCAeYCAxgFhBXABFxzAt ... gNBRyeWFXl2VydmjZNwJIM=" />
  </Section>
</Settings>

Inserire i segreti dell'applicazione nelle istanze dell'applicazioneInject application secrets into application instances

Idealmente, la distribuzione in ambienti diversi dovrebbe essere il più possibile automatizzata.Ideally, deployment to different environments should be as automated as possible. Questo può essere ottenuto tramite l'esecuzione della crittografia dei segreti in un ambiente di compilazione e l'uso dei segreti crittografati come parametri durante la creazione delle istanze dell'applicazione.This can be accomplished by performing secret encryption in a build environment and providing the encrypted secrets as parameters when creating application instances.

Usare parametri sostituibili in Settings.xmlUse overridable parameters in Settings.xml

Il file di configurazione Settings.xml consente di usare parametri sostituibili che possono essere forniti al momento della creazione dell'applicazione.The Settings.xml configuration file allows overridable parameters that can be provided at application creation time. Usare l'attributo MustOverride invece di fornire un valore per un parametro:Use the MustOverride attribute instead of providing a value for a parameter:

<?xml version="1.0" encoding="utf-8" ?>
<Settings xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://schemas.microsoft.com/2011/01/fabric">
  <Section Name="MySettings">
    <Parameter Name="MySecret" IsEncrypted="true" Value="" MustOverride="true" />
  </Section>
</Settings>

Per sostituire i valori in Settings.xml, dichiarare un parametro di sostituzione per il servizio in ApplicationManifest.xml:To override values in Settings.xml, declare an override parameter for the service in ApplicationManifest.xml:

<ApplicationManifest ... >
  <Parameters>
    <Parameter Name="MySecret" DefaultValue="" />
  </Parameters>
  <ServiceManifestImport>
    <ServiceManifestRef ServiceManifestName="Stateful1Pkg" ServiceManifestVersion="1.0.0" />
    <ConfigOverrides>
      <ConfigOverride Name="Config">
        <Settings>
          <Section Name="MySettings">
            <Parameter Name="MySecret" Value="[MySecret]" IsEncrypted="true" />
          </Section>
        </Settings>
      </ConfigOverride>
    </ConfigOverrides>
  </ServiceManifestImport>

A questo punto, il valore può essere specificato come un parametro dell'applicazione quando si crea un'istanza dell'applicazione.Now the value can be specified as an application parameter when creating an instance of the application. La creazione di un'istanza dell'applicazione può generare uno script con PowerShell o essere scritta in C#, per semplificare l'integrazione in un processo di compilazione.Creating an application instance can be scripted using PowerShell, or written in C#, for easy integration in a build process.

Tramite PowerShell, viene fornito il parametro del comando New-ServiceFabricApplication come tabella hash:Using PowerShell, the parameter is supplied to the New-ServiceFabricApplication command as a hash table:

PS C:\Users\vturecek> New-ServiceFabricApplication -ApplicationName fabric:/MyApp -ApplicationTypeName MyAppType -ApplicationTypeVersion 1.0.0 -ApplicationParameter @{"MySecret" = "I6jCCAeYCAxgFhBXABFxzAt ... gNBRyeWFXl2VydmjZNwJIM="}

Tramite C#, i parametri dell'applicazione vengono specificati in ApplicationDescription come NameValueCollection:Using C#, application parameters are specified in an ApplicationDescription as a NameValueCollection:

FabricClient fabricClient = new FabricClient();

NameValueCollection applicationParameters = new NameValueCollection();
applicationParameters["MySecret"] = "I6jCCAeYCAxgFhBXABFxzAt ... gNBRyeWFXl2VydmjZNwJIM=";

ApplicationDescription applicationDescription = new ApplicationDescription(
    applicationName: new Uri("fabric:/MyApp"),
    applicationTypeName: "MyAppType",
    applicationTypeVersion: "1.0.0",
    applicationParameters: applicationParameters)
);

await fabricClient.ApplicationManager.CreateApplicationAsync(applicationDescription);

Decrittografare i segreti dal codice del servizioDecrypt secrets from service code

I servizi di Service Fabric vengono eseguiti in NETWORK SERVICE per impostazione predefinita su Windows e non hanno accesso ai certificati installati nel nodo senza un'impostazione aggiuntiva.Services in Service Fabric run under NETWORK SERVICE by default on Windows and don't have access to certificates installed on the node without some extra setup.

Quando si usa un certificato di crittografia dati, è necessario assicurarsi che NETWORK SERVICE o qualsiasi account utente sia in esecuzione nel servizio disponga dell'accesso alla chiave privata del certificato.When using a data encipherment certificate, you need to make sure NETWORK SERVICE or whatever user account the service is running under has access to the certificate's private key. Service Fabric gestirà automaticamente la concessione dell'accesso per il servizio se viene configurato a tale scopo.Service Fabric will handle granting access for your service automatically if you configure it to do so. Questa configurazione può essere eseguita in ApplicationManifest definendo utenti e criteri di protezione per i certificati.This configuration can be done in ApplicationManifest.xml by defining users and security policies for certificates. Nell'esempio seguente, all'account NETWORK SERVICE viene concesso l'accesso in lettura a un certificato definito dalla relativa identificazione personale:In the following example, the NETWORK SERVICE account is given read access to a certificate defined by its thumbprint:

<ApplicationManifest … >
    <Principals>
        <Users>
            <User Name="Service1" AccountType="NetworkService" />
        </Users>
    </Principals>
  <Policies>
    <SecurityAccessPolicies>
      <SecurityAccessPolicy GrantRights=”Read” PrincipalRef="Service1" ResourceRef="MyCert" ResourceType="Certificate"/>
    </SecurityAccessPolicies>
  </Policies>
  <Certificates>
    <SecretsCertificate Name="MyCert" X509FindType="FindByThumbprint" X509FindValue="[YourCertThumbrint]"/>
  </Certificates>
</ApplicationManifest>

Nota

Quando si copia un'identificazione personale di un certificato dallo snap-in dell'archivio dei certificati su Windows, viene inserito un carattere invisibile all'inizio della stringa di identificazione personale.When copying a certificate thumbprint from the certificate store snap-in on Windows, an invisible character is placed at the beginning of the thumbprint string. Questo carattere invisibile può causare un errore durante il tentativo di individuare un certificato tramite identificazione personale. Accertarsi di eliminare questo carattere aggiuntivo.This invisible character can cause an error when trying to locate a certificate by thumbprint, so be sure to delete this extra character.

Usare i segreti dell'applicazione nel codice del servizioUse application secrets in service code

L'API per accedere ai valori di configurazione da Settings.xml in un pacchetto di configurazione consente di decrittografare facilmente i valori con l'attributo IsEncrypted impostato su true.The API for accessing configuration values from Settings.xml in a configuration package allows for easy decrypting of values that have the IsEncrypted attribute set to true. Poiché il testo crittografato contiene informazioni sul certificato usato per la crittografia, non è necessario individuare manualmente il certificato.Since the encrypted text contains information about the certificate used for encryption, you do not need to manually find the certificate. Il certificato deve essere solo installato sul nodo su cui è in esecuzione il servizio.The certificate just needs to be installed on the node that the service is running on. È sufficiente chiamare il metodo DecryptValue() per recuperare il valore del segreto originale:Simply call the DecryptValue() method to retrieve the original secret value:

ConfigurationPackage configPackage = this.Context.CodePackageActivationContext.GetConfigurationPackageObject("Config");
SecureString mySecretValue = configPackage.Settings.Sections["MySettings"].Parameters["MySecret"].DecryptValue()

Passaggi successiviNext Steps

Altre informazioni sull' esecuzione di applicazioni con autorizzazioni di sicurezza diverseLearn more about running applications with different security permissions