KeyVaultReference-ondersteuning voor Door Azure geïmplementeerde Service Fabric-toepassingen

  • Artikel

Een veelvoorkomende uitdaging bij het bouwen van cloudtoepassingen is het veilig distribueren van geheimen naar uw toepassingen en het beheren ervan. Ondersteuning voor Service Fabric KeyVaultReference maakt het eenvoudig. Zodra dit is geconfigureerd, kunt u verwijzen naar de URL van het geheim dat is opgeslagen in Key Vault in uw toepassingsdefinitie. Service Fabric verwerkt het ophalen van dat geheim en het activeren van uw toepassing ermee. Wanneer u de door SF beheerde versie van de functie gebruikt, kan Service Fabric ook uw Key Vault bewaken en automatisch rolling toepassingsparameterupgrades activeren wanneer uw geheimen in de kluis draaien.

Opties voor het leveren van geheimen aan toepassingen in Service Fabric

De klassieke manier om geheimen aan een Service Fabric-toepassing te leveren, was om versleutelde parameters te declareren. Dit betreft het versleutelen van geheimen op basis van een versleutelingscertificaat en het doorgeven van deze versleutelde geheimen aan uw toepassing. Deze methode heeft enkele nadelen: het moet het versleutelingscertificaat beheren, de geheimen in de implementatiepijplijn blootleggen en een gebrek aan zichtbaarheid in de metagegevens van de geheimen die zijn gekoppeld aan een geïmplementeerde toepassing. Op dezelfde manier vereist het roteren van geheimen een toepassingsimplementatie. Tenzij u een zelfstandig cluster uitvoert, raden we u niet meer aan versleutelde parameters te gebruiken.

Een andere optie is het gebruik van verwijzingen naar het geheimarchief. Deze ervaring biedt centraal beheer van uw toepassingsgeheimen, betere zichtbaarheid van de metagegevens van geïmplementeerde geheimen en maakt centraal beheer van het versleutelingscertificaat mogelijk. Sommigen geven mogelijk de voorkeur aan deze stijl voor geheimbeheer bij het uitvoeren van zelfstandige Service Fabric-clusters.

De aanbeveling is om de afhankelijkheid van geheimen waar mogelijk te verminderen door beheerde identiteiten voor Service Fabric-toepassingen te gebruiken. Beheerde identiteiten kunnen worden gebruikt om rechtstreeks te verifiëren bij Azure Storage, Azure SQL en meer. Dit betekent dat u geen afzonderlijke referentie hoeft te beheren bij het openen van Azure-services die ondersteuning bieden voor Microsoft Entra-verificatie.

Als het niet mogelijk is om Beheerde identiteit als client te gebruiken, raden we u aan KeyVaultReferences te gebruiken. U moet KeyVaultReferences gebruiken in plaats van beheerde identiteit te gebruiken om rechtstreeks naar Key Vault te gaan. KeyVaultReferences helpen de beschikbaarheid van uw toepassing te vergroten, omdat hiermee wordt afgedwongen dat er geheime wijzigingen optreden tijdens rolling upgrades. Het schaalt ook beter naarmate geheimen in de cache worden opgeslagen en vanuit het cluster worden geleverd. Als uw toepassing momenteel versleutelde parameters gebruikt, zijn er slechts minimale wijzigingen nodig in uw toepassingscode om KeyVaultReferences te gebruiken. Uw toepassing kan verwachten dat er één geheim wordt geleverd en dat het geheim voor de levensduur van het proces hetzelfde is.

Vereisten

  • Beheerde identiteit voor Service Fabric-toepassingen

    Service Fabric KeyVaultReference-ondersteuning maakt gebruik van de beheerde identiteit van een toepassing om geheimen op te halen namens de toepassing. U moet uw toepassing implementeren via ARM en deze een beheerde identiteit toewijzen. Volg dit document om beheerde identiteit voor uw toepassing in te schakelen.

  • Central Secrets Store (CSS).

    Central Secrets Store (CSS) is de versleutelde lokale geheimencache van Service Fabric. Deze functie maakt gebruik van CSS om geheimen te beveiligen en te behouden nadat ze zijn opgehaald uit Key Vault. Het inschakelen van deze systeemservice is vereist voor het gebruik van KeyVaultReferences. Volg dit document om CSS in te schakelen en te configureren.

  • Toegang tot de beheerde identiteit van de toepassing verlenen aan key vault

    Raadpleeg dit document om te zien hoe u beheerde identiteit toegang verleent tot Key Vault. Als u een door het systeem toegewezen beheerde identiteit gebruikt, wordt de beheerde identiteit pas gemaakt na de implementatie van de toepassing. Dit kan racevoorwaarden creëren waarbij de toepassing toegang probeert te krijgen tot het geheim voordat de identiteit toegang kan krijgen tot de kluis. De naam van de door het systeem toegewezen identiteit is {cluster name}/{application name}/{service name}.

KeyVaultReferences versus Beheerde KeyVaultReferences

Het basisidee van KeyVaultReferences is in plaats van de waarde van uw toepassingsparameter in te stellen als uw geheim. U stelt deze in op de Key Vault-URL, die vervolgens wordt omgezet in de geheime waarde bij de activering van uw toepassing. In Key Vault kan één geheim bijvoorbeeld https://my.vault.azure.net/secrets/MySecret/ meerdere versies hebben, https://my.vault.azure.net/secrets/MySecret/<oid1> en <oid2>. Wanneer u een KeyVaultReference gebruikt, moet de waarde een versiereferentie (https://my.vault.azure.net/secrets/MySecret/<oid1>) zijn. Als u dat geheim bijvoorbeeld <oid2>in de kluis roteert, moet u een toepassingsupgrade naar de nieuwe verwijzing activeren. Wanneer u een ManagedKeyVaultReference gebruikt, moet de waarde een versieloze verwijzing (https://my.vault.azure.net/secrets/MySecret/) zijn. Service Fabric lost het meest recente exemplaar <oid1> op en activeert de toepassing met dat geheim. Als u het geheim in de kluis roteert naar <oid2>, activeert Service Fabric automatisch een upgrade van de toepassingsparameter om namens u naartoe <oid2> te gaan.

Notitie

Ondersteuning voor KeyVaultReference (versiegeheimen) voor Service Fabric-toepassingen is algemeen beschikbaar vanaf Service Fabric versie 7.2 CU5. Het wordt aanbevolen om een upgrade uit te voeren naar deze versie voordat u deze functie gebruikt.

Notitie

Ondersteuning voor beheerde KeyVaultReference (versieloze geheimen) voor Service Fabric-toepassingen is algemeen beschikbaar vanaf Service Fabric-versie 9.0.

KeyVaultReferences gebruiken in uw toepassing

KeyVaultReferences kunnen worden gebruikt

Als omgevingsvariabele

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

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

Gekoppeld als een bestand in uw container

  • Een sectie toevoegen aan settings.xml

    Parameter definiëren MySecret met Type KeyVaultReference en Waarde <KeyVaultURL>

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

  • Verwijzen naar de nieuwe sectie in ApplicationManifest.xml in <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>

  • De geheimen van servicecode gebruiken

    Elke parameter die hieronder <Section Name=MySecrets> wordt vermeld, is een bestand onder de map waarnaar wordt verwezen door EnvironmentVariable SecretPath. In het onderstaande C#-codefragment ziet u hoe u MySecret kunt lezen vanuit uw toepassing.

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

    Notitie

    MountPoint bepaalt de map waarin de bestanden met geheime waarden worden gekoppeld.

Als verwijzing naar een wachtwoord voor een containeropslagplaats

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

Beheerde KeyVaultReferences gebruiken in uw toepassing

Eerst moet u geheime bewaking inschakelen door uw clusterdefinitie te upgraden om de EnableSecretMonitoring instelling toe te voegen, naast de andere vereiste CSS-configuraties:

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

Notitie

De standaardwaarde kan in de toekomst worden true

Nadat de clusterupgrade is voltooid, kan uw gebruikerstoepassing worden bijgewerkt. Overal waar een KeyVaultReference kan worden gebruikt, kan een ManagedKeyVaultReference ook worden gebruikt, bijvoorbeeld

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

Het belangrijkste verschil in het opgeven van ManagedKeyVaultReferences is dat ze niet kunnen worden vastgelegd in uw toepassingstypemanifest. Ze moeten worden gedeclareerd als parameters op toepassingsniveau en verder moeten ze worden overschreven in uw ARM-toepassingsdefinitie.

Hier volgt een fragment uit een goed gevormd manifest

<?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>

en een fragment van de definitie van de toepassingsresource:

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

Zowel het declareren van de ManagedKeyVaultReference als een toepassingsparameter als het overschrijven van die parameter bij de implementatie is nodig voor Service Fabric om de levenscyclus van het geïmplementeerde geheim te beheren.

Volgende stappen