Konfigurieren von MicroProfile mit Azure Key Vault

In diesem Lernprogramm wird veranschaulicht, wie Sie eine MicroProfile-Anwendung so konfigurieren, dass geheime Schlüssel aus Azure Key Vault mithilfe der MicroProfile-Konfigurations-APIs abgerufen werden. Entwickler profitieren von der offenen MicroProfile Config-API zum Abrufen und Einfügen von Konfigurationsdaten in ihre Microservices.

Voraussetzungen

• Ein Azure-Abonnement. Wenn Sie noch kein Azure-Abonnement besitzen, können Sie Ihre MSDN-Abonnentenvorteile anwenden oder sich für ein kostenloses Konto registrieren
• Azure CLI für Unix-ähnliche Umgebungen. In diesem Artikel wird nur die Bash-Variante der Azure CLI benötigt.
  • Bash

    Installieren Sie Azure CLI, und melden Sie sich interaktiv mit dem Az-Anmeldebefehl an, um sich bei Azure anzumelden, bevor Sie den Code verwendenDefaultAzureCredential.

    az login
    

    PowerShell

    Führen Sie das Connect-AzAccount Cmdlet aus, um sich mit Azure PowerShell zu authentifizieren. Standardmäßig startet wie die Azure CLI den Standardwebbrowser, Connect-AzAccount um ein Benutzerkonto zu authentifizieren.

    Connect-AzAccount
    

    Visual Studio Code

    Wenn Sie Visual Studio Code verwenden, können Sie sich auch mit der Azure-Kontoerweiterung bei Azure anmelden.
  • Für diesen Artikel ist mindestens Version 2.61.0 der Azure CLI erforderlich. Bei Verwendung von Azure Cloud Shell ist die aktuelle Version bereits installiert.
• In Azure Cloud Shell sind diese Voraussetzungen bereits vorinstalliert. Weitere Informationen finden Sie unter Schnellstart für Azure Cloud Shell.
• Wenn Sie die in diesem Leitfaden beschriebenen Befehle lokal ausführen (und nicht Azure Cloud Shell verwenden), führen Sie die folgenden Schritte aus:
  • Bereiten Sie einen lokalen Computer mit einem installierten UNIX-ähnlichen Betriebssystem (z. B. Ubuntu, macOS, Windows-Subsystem für Linux) vor.
  • Installieren Sie eine Java SE-Implementierung, Version 17 oder höher (z . B. Microsoft Build von OpenJDK).
  • Installieren Sie Maven 3.9.8 oder höher.
  • Installieren Sie cURL.

Verbinden der MicroProfile-Konfiguration mit Azure Key Vault

Werfen wir einen schnellen Blick auf die Kombination von Azure Key Vault und der MicroProfile Config-API. Hier sehen Sie einen Codeausschnitt eines Felds in einer Klasse, die mit @Inject und .@ConfigProperty Die name angabe in der Anmerkung ist der Name des geheimen Schlüssels, der im Azure Key Vault nachschlagen soll, und wird defaultValue verwendet, wenn der geheime Schlüssel nicht ermittelt wird. Der geheime Wert, der in Azure Key Vault gespeichert ist, oder der Standardwert, wenn kein solcher Geheimschlüssel vorhanden ist, wird automatisch in das Feld zur Laufzeit eingefügt. Das Einfügen von Eigenschaftswerten auf diese Weise bietet zahlreiche Vorteile. Sie müssen beispielsweise keine Werte mehr in Konstruktoren und Settermethoden übergeben, und die Konfiguration wird aus dem Code externisiert. Einer der leistungsstärksten Vorteile besteht darin, separate Wertesätze für Entwicklungs-, Test- und Prod-Umgebungen zu haben.

@Inject
@ConfigProperty(name = "key-name", defaultValue = "Unknown")
String keyValue;

Es ist auch möglich, unbedingt auf die MicroProfile-Konfiguration zuzugreifen, wie im folgenden Beispiel gezeigt:

public class DemoClass {
    @Inject
    Config config;

    public void method() {
        System.out.println("Hello: " + config.getValue("key-name", String.class));
    }
}

In diesem Beispiel wird die Open Liberty-Implementierung von MicroProfile verwendet. Eine vollständige Liste der kompatiblen Implementierungen finden Sie unter MicroProfile-kompatible Implementierungen. Das Beispiel veranschaulicht außerdem, wie die Anwendung in Azure containerisiert und ausgeführt wird.

In diesem Beispiel wird die Azure-Erweiterung mit geringer Reibung für die benutzerdefinierte ConfigSource-Bibliothek von MicroProfile Key Vault verwendet. Weitere Informationen zu dieser Bibliothek finden Sie in der Bibliothek README.

Im Anschluss erfahren Sie, wie Sie diesen Code auf Ihrem lokalen Computer ausführen. Dabei erstellen Sie zunächst eine Azure Key Vault-Ressource.

Erstellen einer Azure Key Vault-Ressource

Sie verwenden die Azure CLI, um die Azure Key Vault-Ressource zu erstellen und sie mit zwei geheimen Schlüsseln aufzufüllen.

Melden Sie sich zunächst bei Azure an, und legen Sie ein Abonnement als aktuelles aktives Abonnement fest.

az login
az account set --subscription <subscription-id>

Erstellen Sie als Nächstes eine Ressourcengruppe mit einem eindeutigen Namen, z. B. mp-kv-rg-ejb010424.

export RESOURCE_GROUP_NAME=mp-kv-rg-ejb010424
az group create \
    --name ${RESOURCE_GROUP_NAME} \
    --location eastus

Erstellen Sie nun eine Azure Key Vault-Ressource mit einem eindeutigen Namen (z . B. kvejb010424), fügen Sie zwei geheime Schlüssel hinzu, und exportieren Sie den Key Vault-URI als Umgebungsvariable.

export KEY_VAULT_NAME=kv-ejb010424
az keyvault create \
    --resource-group "${RESOURCE_GROUP_NAME}" \
    --name "${KEY_VAULT_NAME}" \
    --location eastus \
    --enable-rbac-authorization false

az keyvault secret set \
    --vault-name "${KEY_VAULT_NAME}" \
    --name secret \
    --value 1234
az keyvault secret set \
    --vault-name "${KEY_VAULT_NAME}" \
    --name anotherSecret \
    --value 5678

export AZURE_KEYVAULT_URL=$(az keyvault show \
    --resource-group "${RESOURCE_GROUP_NAME}" \
    --name "${KEY_VAULT_NAME}" \
    --query properties.vaultUri \
    --output tsv)
echo $AZURE_KEYVAULT_URL

Die Umgebungsvariable AZURE_KEYVAULT_URL ist erforderlich, um die Bibliothek für die spätere Arbeit mit dem Beispiel zu konfigurieren. Lassen Sie das Terminal geöffnet, und verwenden Sie es für die lokale Ausführung der App später.

Das ist alles! Sie haben jetzt Key Vault in Azure mit zwei geheimen Schlüsseln ausgeführt. Sie können jetzt das Beispiel-Repository klonen und konfigurieren, um diese Ressource in Ihrer App zu verwenden.

Einrichten und Ausführen in der lokalen Umgebung

Dieses Beispiel basiert auf einer Beispielanwendung, die auf GitHub verfügbar ist. Wechseln Sie zum Terminal, das Sie zuvor geöffnet haben, und führen Sie die folgenden Befehle aus, um das Repository zu klonen und die App lokal auszuführen:

git clone https://github.com/Azure/azure-microprofile.git
cd azure-microprofile
git checkout 1.0.0-beta.3
cd integration-tests/open-liberty-sample
mvn clean package liberty:run

Wenn eine Meldung angezeigt You are in 'detached HEAD' statewird, ist diese Nachricht sicher zu ignorieren.

Hinweis

Die Bibliothek verwendet die Standardmäßigen Azure-Anmeldeinformationen, um sich in Azure zu authentifizieren .

Da Sie ein Konto über den Azure CLI-Befehl az login lokal authentifiziert haben, DefaultAzureCredential authentifiziert sich dieses Konto für den Zugriff auf den Azure Key Vault.

Warten Sie, bis die Ausgabe ähnlich wie The defaultServer server is ready to run a smarter planetangezeigt wird. Öffnen Sie ein neues Terminal, und führen Sie die folgenden Befehle aus, um das Beispiel zu testen:

# Get the value of secret "secret" stored in the Azure key vault. You should see 1234 in the response.
echo $(curl -s http://localhost:9080/config/value/secret -X GET)

# Get the value of secret "anotherSecret" stored in the Azure key vault. You should see 5678 in the response.
echo $(curl -s http://localhost:9080/config/value/anotherSecret -X GET)

# Get the names of secrets stored in the Azure key vault. You should see ["anotherSecret","secret"] in the response.
echo $(curl -s http://localhost:9080/config/propertyNames -X GET)

# Get the name-value paris of secrets stored in the Azure key vault. You should see {"anotherSecret":"5678","secret":"1234"} in the response.
echo $(curl -s http://localhost:9080/config/properties -X GET)

Die in den Kommentaren beschriebenen erwarteten Ausgaben sollten angezeigt werden. Wechseln Sie zurück zum Terminal, in dem die App ausgeführt wird. Drücken Sie STRG + C, um die App zu beenden.

Untersuchen der Beispiel-App

Lassen Sie uns ein tieferes Verständnis darüber gewinnen, wie MicroProfile Config im Allgemeinen funktioniert, und die Benutzerdefinierte ConfigSource-Bibliothek von MicroProfile Key Vault funktioniert insbesondere.

Bibliotheksabhängigkeit

Schließen Sie die benutzerdefinierte ConfigSource von MicroProfile Key Vault in Ihre App mit der folgenden Maven-Abhängigkeit ein:

<dependency>
  <groupId>com.azure.microprofile</groupId>
  <artifactId>azure-microprofile-config-keyvault</artifactId>
</dependency>

Herstellen einer Verbindung mit Azure Key Vault

Die azure-microprofile-config-keyvault Bibliothek verbindet Ihre App mit Azure Key Vault, ohne direkte Abhängigkeiten von Azure-APIs einzuführen. Die Bibliothek stellt eine Implementierung der ConfigSource-Schnittstelle der MicroProfile-Konfigurationsspezifikation bereit, die weiß, wie Sie aus Azure Key Vault lesen können. Der Rest der Implementierung von MicroProfile Config wird von der Open Liberty-Laufzeit bereitgestellt. Einen Link zur Spezifikation finden Sie in den nächsten Schritten.

Die Bibliothek definiert die azure.keyvault.url Konfigurationseigenschaft, um Ihre App an einen bestimmten Schlüsseltresor zu binden. Die MicroProfile Config-Spezifikation definiert die "Umgebungsvariablen-Zuordnungsregeln" für die Ermittlung des Werts für eine Konfigurationseigenschaft, z azure.keyvault.url. B. zur Laufzeit. Einer dieser Regeln gibt an, dass Eigenschaften in Umgebungsvariablen konvertiert werden. Die Eigenschaft azure.keyvault.url bewirkt, dass die Umgebungsvariable AZURE_KEYVAULT_URL konsultiert wird.

Wichtige Klassen in der Beispiel-App

Sehen wir uns die REST-Ressource an, die die vorherigen cURL-Befehle aufgerufen haben. Diese REST-Ressource wird in der Klasse ConfigResource.java im integration-tests/open-liberty-sample Projekt definiert.

@Path("/config")
public class ConfigResource {

    @Inject
    private Config config;

    @GET
    @Produces(MediaType.TEXT_PLAIN)
    @Path("/value/{name}")
    public String getConfigValue(@PathParam("name") String name) {
        return config.getConfigValue(name).getValue();
    }

    @GET
    @Produces(MediaType.APPLICATION_JSON)
    @Path("/propertyNames")
    public Set<String> getConfigPropertyNames() {
        ConfigSource configSource = getConfigSource(AzureKeyVaultConfigSource.class.getSimpleName());
        return configSource.getPropertyNames();
    }

    @GET
    @Produces(MediaType.APPLICATION_JSON)
    @Path("/properties")
    public Map<String, String> getConfigProperties() {
        ConfigSource configSource = getConfigSource(AzureKeyVaultConfigSource.class.getSimpleName());
        return configSource.getProperties();
    }

    private ConfigSource getConfigSource(String name) {
        return StreamSupport.stream(config.getConfigSources().spliterator(), false)
                .filter(source -> source.getName().equals(name))
                .findFirst()
                .orElseThrow(() -> new RuntimeException("ConfigSource not found: " + name));
    }
}

Die getConfigValue() Methode verwendet die injizierte Config Implementierung, um einen Wert aus den Anwendungskonfigurationsquellen nachzuschlagen. Alle Wertsuchvorgänge für die Config Implementierung werden über den suchalgorithmus gefunden, der durch die MicroProfile Config-Spezifikation definiert ist. Die azure-microprofile-config-keyvault Bibliothek fügt Azure Key Vault als Konfigurationsquelle hinzu.

Die getConfigSource() Methode vermeidet den Suchalgorithmus und wechselt direkt zu den AzureKeyVaultConfigSource Eigenschaften, um Eigenschaften aufzulösen. Diese Methode wird von den Methoden und getConfigProperties() den getConfigPropertyNames() Methoden verwendet.

Ausführen auf Azure-Container-Apps

In diesem Abschnitt containern Sie die App, konfigurieren eine vom Benutzer zugewiesene verwaltete Identität für den Zugriff auf den Azure Key Vault und stellen die containerisierte App in Azure-Container-Apps bereit.

Wechseln Sie zurück zum Terminal, in dem Sie die App lokal ausgeführt haben, und verwenden Sie sie in diesem Abschnitt.

Einrichten einer Azure-Containerregistrierung

Sie verwenden die Azure-Containerregistrierung, um die App zu containern und das App-Image zu speichern.

Erstellen Sie zunächst eine Azure-Containerregistrierung mit einem eindeutigen Namen, z. B. acrejb010424.

export ACR_NAME=acrejb010424
az acr create \
    --resource-group $RESOURCE_GROUP_NAME \
    --name $ACR_NAME \
    --sku Basic

Warten Sie einige Minuten, nachdem dieser Befehl zurückgegeben wird, bevor Sie fortfahren.

Containerisieren der App

Als Nächstes containern Sie die App, und übertragen Sie das App-Image in Ihre Azure-Containerregistrierung. Stellen Sie sicher, dass Sie sich im Pfad der Beispiel-App befinden, z. B. azure-microprofile/integration-tests/open-liberty-sample.

az acr build \
    --registry ${ACR_NAME} \
    --image open-liberty-mp-azure-keyvault:latest \
    .

Es sollte eine Buildausgabe angezeigt werden, die mit einer ähnlichen Meldung Run ID: ca1 was successful after 1m28sendet. Wenn eine ähnliche Meldung nicht angezeigt wird, beheben Sie das Problem, bevor Sie fortfahren.

Verwenden Sie die folgenden Befehle, um Verbindungsinformationen abzurufen, die für den Zugriff auf das Image erforderlich sind, wenn Sie die App später in Azure-Container-Apps bereitstellen.

export ACR_LOGIN_SERVER=$(az acr show \
    --name $ACR_NAME \
    --query 'loginServer' \
    --output tsv)

Einrichten einer benutzerseitig zugewiesenen verwalteten Identität

Wie bereits erwähnt, verwendet die Bibliothek standardmäßige Azure-Anmeldeinformationen , um sich in Azure zu authentifizieren. Wenn Sie die App in Azure-Container-Apps bereitstellen, legen Sie die Umgebungsvariable AZURE_CLIENT_ID so fest, dass DefaultAzureCredential so konfiguriert wird, dass sie als benutzerdefinierte verwaltete Identität authentifiziert wird, die über Berechtigungen für den Zugriff auf den Azure Key Vault verfügt und später Azure-Container-Apps zugewiesen wird.

Verwenden Sie zunächst die folgenden Befehle, um eine vom Benutzer zugewiesene verwaltete Identität mit einem eindeutigen Namen zu erstellen, z. B. uamiejb010424. Weitere Informationen finden Sie unter Erstellen einer benutzerseitig zugewiesenen verwalteten Identität.

export USER_ASSIGNED_IDENTITY_NAME=uamiejb010424
az identity create \
    --resource-group ${RESOURCE_GROUP_NAME} \
    --name ${USER_ASSIGNED_IDENTITY_NAME}

Verwenden Sie als Nächstes die folgenden Befehle, um ihm Berechtigungen zum Abrufen und Auflisten geheimer Schlüssel aus dem Azure Key Vault zu erteilen. Weitere Informationen finden Sie unter Zuweisen der Zugriffsrichtlinie.

export USER_ASSIGNED_IDENTITY_OBJECT_ID="$(az identity show \
    --resource-group "${RESOURCE_GROUP_NAME}" \
    --name "${USER_ASSIGNED_IDENTITY_NAME}" \
    --query 'principalId' \
    --output tsv)"

az keyvault set-policy --name "${KEY_VAULT_NAME}" \
    --resource-group "${RESOURCE_GROUP_NAME}" \
    --secret-permissions get list \
    --object-id "${USER_ASSIGNED_IDENTITY_OBJECT_ID}"

Die Ausgabe muss den folgenden JSON-Code enthalten, um als erfolgreich betrachtet zu werden:

"permissions": {
  "certificates": null,
  "keys": null,
  "secrets": [
    "list",
    "get"
  ],
  "storage": null
}

Wenn die Ausgabe diesen JSON-Code nicht enthält, beheben Sie das Problem, bevor Sie fortfahren.

Verwenden Sie dann die folgenden Befehle, um die ID und Client-ID der vom Benutzer zugewiesenen verwalteten Identität abzurufen, damit Sie sie Ihren Azure-Container-Apps später für den Zugriff auf den Azure Key Vault zuweisen können:

export USER_ASSIGNED_IDENTITY_ID="$(az identity show \
    --resource-group "${RESOURCE_GROUP_NAME}" \
    --name "${USER_ASSIGNED_IDENTITY_NAME}" \
    --query 'id' \
    --output tsv)"
export USER_ASSIGNED_IDENTITY_CLIENT_ID="$(az identity show \
    --name "${USER_ASSIGNED_IDENTITY_NAME}" \
    --resource-group "${RESOURCE_GROUP_NAME}" \
    --query 'clientId' \
    --output tsv)"
echo $USER_ASSIGNED_IDENTITY_ID
echo $USER_ASSIGNED_IDENTITY_CLIENT_ID

Bereitstellen der App in Azure-Container-Apps

Sie haben die App containerisiert und eine vom Benutzer zugewiesene verwaltete Identität für den Zugriff auf den Azure Key Vault konfiguriert. Jetzt können Sie die containerisierte App in Azure-Container-Apps bereitstellen.

Erstellen Sie zunächst eine Umgebung für Azure-Container-Apps. Eine Umgebung in Azure Container Apps erstellt eine sichere Grenze für eine Gruppe von Container-Apps. Container-Apps, die in derselben Umgebung bereitgestellt werden, werden im gleichen virtuellen Netzwerk bereitgestellt und schreiben Protokolle in denselben Log Analytics-Arbeitsbereich. Verwenden Sie den Befehl "az containerapp env create " zum Erstellen einer Umgebung mit einem eindeutigen Namen (z . B. acaenvejb010424), wie im folgenden Beispiel gezeigt:

export ACA_ENV=acaenvejb010424
az containerapp env create \
    --resource-group $RESOURCE_GROUP_NAME \
    --location eastus \
    --name $ACA_ENV

Verwenden Sie als Nächstes den Befehl "az containerapp create ", um eine Container-Apps-Instanz mit einem eindeutigen Namen (z . B. acaappejb010424) zu erstellen, um die App nach dem Abrufen des Images aus der Containerregistrierung auszuführen, wie im folgenden Beispiel gezeigt:

export ACA_NAME=acaappejb010424
az containerapp create \
    --resource-group ${RESOURCE_GROUP_NAME} \
    --name ${ACA_NAME} \
    --environment ${ACA_ENV} \
    --image ${ACR_LOGIN_SERVER}/open-liberty-mp-azure-keyvault:latest  \
    --registry-server $ACR_LOGIN_SERVER \
    --registry-identity system \
    --user-assigned ${USER_ASSIGNED_IDENTITY_ID} \
    --env-vars \
        AZURE_CLIENT_ID=${USER_ASSIGNED_IDENTITY_CLIENT_ID} \
        AZURE_KEYVAULT_URL=${AZURE_KEYVAULT_URL} \
    --target-port 9080 \
    --ingress 'external'

Hinweis

Sie weisen der Container-Apps-Instanz die vom Benutzer zugewiesene verwaltete Identität mit dem Parameter --user-assigned ${USER_ASSIGNED_IDENTITY_ID}zu.

Die Container-Apps-Instanz kann auf den Azure Key Vault mit zwei Umgebungsvariablen zugreifen, die in den Parametern --env-vars AZURE_CLIENT_ID=${USER_ASSIGNED_IDENTITY_CLIENT_ID} AZURE_KEYVAULT_URL=${AZURE_KEYVAULT_URL}bereitgestellt werden. Denken Sie daran, dass die AZURE_KEYVAULT_URL Umgebungsvariable aufgrund der durch die MicroProfile Config-Spezifikation definierten Umgebungsvariablenzuordnungsregeln konsultiert wird.

Rufen Sie dann eine vollqualifizierte URL für den Zugriff auf die App mithilfe des folgenden Befehls ab:

export APP_URL=https://$(az containerapp show \
    --resource-group ${RESOURCE_GROUP_NAME} \
    --name ${ACA_NAME} \
    --query properties.configuration.ingress.fqdn \
    --output tsv)

Führen Sie schließlich die folgenden Befehle erneut aus, um das Beispiel zu testen, das auf der Container-Apps-Instanz ausgeführt wird:

# Get the value of secret "secret" stored in the Azure key vault. You should see 1234 in the response.
echo $(curl -s ${APP_URL}/config/value/secret -X GET)

# Get the value of secret "anotherSecret" stored in the Azure key vault. You should see 5678 in the response.
echo $(curl -s  ${APP_URL}/config/value/anotherSecret -X GET)

# Get the names of secrets stored in the Azure key vault. You should see ["anotherSecret","secret"] in the response.
echo $(curl -s  ${APP_URL}/config/propertyNames -X GET)

# Get the name-value paris of secrets stored in the Azure key vault. You should see {"anotherSecret":"5678","secret":"1234"} in the response.
echo $(curl -s  ${APP_URL}/config/properties -X GET)

Die in den Kommentaren beschriebenen erwarteten Ausgaben sollten angezeigt werden. Wenn sie nicht angezeigt werden, kann die App noch gestartet werden. Warten Sie eine Weile, und versuchen Sie es erneut.

Bereinigen von Ressourcen

Zum Vermeiden von Azure-Gebühren sollten Sie nicht benötigte Ressourcen bereinigen. Wenn die Ressourcen nicht mehr benötigt werden, führen Sie die folgenden Befehle aus, um die Ressourcen zu bereinigen.

az keyvault delete \
    --resource-group "${RESOURCE_GROUP_NAME}" \
    --name "${KEY_VAULT_NAME}"

az keyvault purge \
    --name "${KEY_VAULT_NAME}" \
    --no-wait

az group delete \
    --name ${RESOURCE_GROUP_NAME} \
    --yes \
    --no-wait

Nächste Schritte

Weitere Informationen finden Sie in den folgenden Referenzen:

• Azure Container Apps
• Jakarta EE on Azure
• Azure-Erweiterungen für MicroProfile
• MicroProfile
• MicroProfile Config Specification
• MicroProfile Config-APIs
• Open Liberty
• Open Liberty-Serverkonfiguration
• Liberty Maven-Plug-In
• Open Liberty-Containerimages