Share via

Konfigurace služby Azure Key Vault pro MicroProfile

  • Článek

Tento kurz ukazuje, jak nakonfigurovat aplikaci MicroProfile tak, aby načítala tajné kódy ze služby Azure Key Vault pomocí rozhraní API konfigurace MicroProfile. Vývojáři můžou využít otevřené standardní rozhraní MicroProfile Config API pro načítání a vkládání konfiguračních dat do mikroslužeb.

Požadavky

  • Předplatné Azure; Pokud ještě nemáte předplatné Azure, můžete si aktivovat výhody předplatitele MSDN nebo si zaregistrovat bezplatný účet.
  • Azure CLI pro prostředí podobná unixovým systémům. Tento článek vyžaduje pouze variantu Bash Azure CLI.
    • Nainstalujte Azure CLI a přihlaste se interaktivně pomocí příkazu az login , abyste se před použitím DefaultAzureCredential kódu přihlásili k Azure. 
      az login
    • Tento článek vyžaduje aspoň verzi 2.55.0 Azure CLI. Pokud používáte Azure Cloud Shell, je už nainstalovaná nejnovější verze.
  • Služba Azure Cloud Shell má všechny tyto předpoklady předinstalované. Další informace najdete v rychlém startu pro Azure Cloud Shell.
  • Pokud příkazy v této příručce spouštíte místně (místo použití Azure Cloud Shellu), proveďte následující kroky:
    • Připravte místní počítač s nainstalovaným operačním systémem Unix (například Ubuntu, macOS nebo Subsystém Windows pro Linux).
    • Nainstalujte implementaci Java SE verze 17 nebo novější (například build Microsoftu openJDK).
    • Nainstalujte Maven 3.5.0 nebo novější.
    • Nainstalujte cURL.

Připojení konfigurace microProfile se službou Azure Key Vault

Pojďme se rychle podívat na možnosti kombinování služby Azure Key Vault a konfiguračního rozhraní API MicroProfile. Tady je fragment kódu pole ve třídě, která je opatřena poznámkami @Inject a @ConfigProperty. Zadaný name v poznámce je název tajného kódu, který se má vyhledat ve službě Azure Key Vault, a defaultValue použije se, pokud se tajný klíč nezjistí. Hodnota tajného kódu uložená ve službě Azure Key Vault nebo výchozí hodnota, pokud takový tajný klíč neexistuje, se automaticky vloží do pole za běhu. Vkládání hodnot vlastností tímto způsobem poskytuje řadu výhod. Například už nemusíte předávat hodnoty v konstruktorech a metodách setter a konfigurace se externalizuje z kódu. Jednou z nejvýkonnějších výhod je samostatná sada hodnot pro vývojová, testovací a produžovaná prostředí.

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

Je také možné získat imperativní přístup ke konfiguraci MicroProfile, jak je znázorněno v následujícím příkladu:

public class DemoClass {
    @Inject
    Config config;

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

Tato ukázka používá implementaci MicroProfile open liberty. Úplný seznam kompatibilních implementací naleznete v tématu MicroProfile Kompatibilní implementace. Ukázka také ukazuje, jak kontejnerizovat a spustit aplikaci v Azure.

Tato ukázka používá rozšíření Azure s nízkým třením pro knihovnu MicroProfile Key Vault Custom ConfigSource. Další informace o této knihovně naleznete v souboru README knihovny.

Tady jsou uvedené kroky potřebné ke spuštění tohoto kódu na místním počítači, počínaje vytvořením prostředku služby Azure Key Vault.

Vytvoření prostředku služby Azure Key Vault

Pomocí Azure CLI vytvoříte prostředek služby Azure Key Vault a naplníte ho dvěma tajnými kódy.

Nejprve se přihlaste k Azure a nastavte předplatné na aktuální aktivní předplatné.

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

Dále vytvořte skupinu prostředků s jedinečným názvem, například mp-kv-rg-ejb010424.

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

Teď vytvořte prostředek služby Azure Key Vault s jedinečným názvem (například kvejb010424), přidejte dva tajné kódy a exportujte identifikátor URI služby Key Vault jako proměnnou prostředí.

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

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

Proměnná AZURE_KEYVAULT_URL prostředí je nutná ke konfiguraci knihovny pro pozdější práci s ukázkou. Nechte terminál otevřený a používejte ho pro spuštění aplikace místně později.

A je to! Teď máte službu Key Vault spuštěnou v Azure se dvěma tajnými klíči. Teď můžete naklonovat ukázkové úložiště a nakonfigurovat ho tak, aby používal tento prostředek ve vaší aplikaci.

Zprovoznění v místním prostředí

Tento příklad vychází z ukázkové aplikace dostupné na GitHubu. Přepněte do terminálu, který jste otevřeli předtím, a spuštěním následujících příkazů naklonujte úložiště a spusťte aplikaci místně:

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

Pokud se zobrazí zpráva o You are in 'detached HEAD' statetéto zprávě, můžete ji ignorovat.

Poznámka:

Knihovna používá k ověřování v Azure výchozí přihlašovací údaje Azure.

Vzhledem k tomu, že jste účet ověřili prostřednictvím příkazu Azure CLI az login místně, DefaultAzureCredential ověřuje se pomocí daného účtu pro přístup ke službě Azure Key Vault.

Počkejte, dokud se nezobrazí výstup podobný The defaultServer server is ready to run a smarter planet. Otevřete nový terminál a spuštěním následujících příkazů otestujte ukázku:

# 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)

Měli byste vidět očekávané výstupy popsané v komentářích. Přepněte zpět na terminál, na kterém je aplikace spuštěná. Stisknutím kláves Ctrl + C aplikaci zastavte.

Prozkoumání ukázkové aplikace

Pojďme se podrobněji podívat na to, jak obecně funguje konfigurace MicroProfile, a konkrétně funguje knihovna MicroProfile Key Vault Custom ConfigSource.

Závislost knihovny

Do aplikace zahrňte vlastní configSource microProfile Key Vault s následující závislostí Mavenu:

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

Připojení do služby Azure Key Vault

Knihovna azure-microprofile-config-keyvault připojí vaši aplikaci ke službě Azure Key Vault, aniž by zavedla přímé závislosti na rozhraních API Azure. Knihovna poskytuje implementaci rozhraní ConfigSource konfigurace MicroProfile, které ví, jak číst ze služby Azure Key Vault. Zbývající část implementace Konfigurace MicroProfile je poskytována modulem Runtime Open Liberty. Odkaz na specifikaci najdete v části Další kroky.

Knihovna definuje vlastnost konfigurace pro vytvoření vazby azure.keyvault.url aplikace na konkrétní trezor klíčů. Specifikace konfigurace MicroProfile definuje pravidla mapování proměnných prostředí pro způsob zjištění hodnoty vlastnosti konfigurace, například azure.keyvault.url, za běhu. Jedno z těchto pravidel uvádí, že vlastnosti se převedou na proměnné prostředí. Vlastnost azure.keyvault.url způsobí, že se proměnná AZURE_KEYVAULT_URL prostředí bude konzultovat.

Klíčové třídy v ukázkové aplikaci

Pojďme se podívat na prostředek REST, který předchozí příkazy cURL volají. Tento prostředek REST je definován ve třídě ConfigResource.java v integration-tests/open-liberty-sample projektu.

@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));
    }
}

Metoda getConfigValue() používá vloženou Config implementaci k vyhledání hodnoty ze zdrojů konfigurace aplikace. Vyhledávání hodnot v Config implementaci se nachází prostřednictvím vyhledávacího algoritmu definovaného specifikací Konfigurace MicroProfile. Knihovna azure-microprofile-config-keyvault přidá Službu Azure Key Vault jako zdroj konfigurace.

Metoda getConfigSource() se vyhne vyhledávacímu algoritmu a přejde rovnou k překladu AzureKeyVaultConfigSource vlastností. Tato metoda je používána metodami getConfigPropertyNames() a getConfigProperties() metodami.

Spuštění v Azure Container Apps

V této části kontejnerizujete aplikaci, nakonfigurujete spravovanou identitu přiřazenou uživatelem pro přístup ke službě Azure Key Vault a nasadíte kontejnerizovanou aplikaci v Azure Container Apps.

Přepněte zpátky na terminál, ve kterém jste aplikaci spustili místně, a použijte ji v celé této části.

Nastavení služby Azure Container Registry

Pomocí služby Azure Container Registry kontejnerizujete aplikaci a uložíte image aplikace.

Nejprve vytvořte Azure Container Registry s jedinečným názvem, například acrejb010424.

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

Než budete pokračovat, počkejte několik minut po návratu tohoto příkazu.

Kontejnerizace aplikace

Dále kontejnerizujte aplikaci a nasdílejte image aplikace do služby Azure Container Registry. Ujistěte se, že jste v cestě ukázkové aplikace, například azure-microprofile/integration-tests/open-liberty-sample.

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

Měl by se zobrazit výstup sestavení, který končí zprávou podobnou Run ID: ca1 was successful after 1m28s. Pokud se vám podobná zpráva nezobrazí, před pokračováním problém vyřešte a vyřešte ho.

Následující příkazy použijte k načtení informací o připojení potřebných pro přístup k imagi při pozdějším nasazení aplikace v Azure Container Apps.

export ACR_LOGIN_SERVER=$(az acr show \
    --name $ACR_NAME \
    --query 'loginServer' \
    --output tsv)
export ACR_USER_NAME=$(az acr credential show \
    --name $ACR_NAME \
    --query 'username' \
    --output tsv)
export ACR_PASSWORD=$(az acr credential show \
    --name $ACR_NAME \
    --query 'passwords[0].value' \
    --output tsv)

Nastavení spravované identity přiřazené uživatelem

Jak jsme uvedli dříve, knihovna k ověřování v Azure používá výchozí přihlašovací údaje Azure. Když nasadíte aplikaci do Služby Azure Container Apps, nastavíte proměnnou AZURE_CLIENT_ID prostředí tak, aby nakonfigurovala DefaultAzureCredential tak, aby se ověřila jako uživatelem definovaná spravovaná identita, která má oprávnění pro přístup ke službě Azure Key Vault a která se později přiřadí ke službě Azure Container Apps.

Nejprve pomocí následujících příkazů vytvořte spravovanou identitu přiřazenou uživatelem s jedinečným názvem, například uamiejb010424. Další informace najdete v tématu Vytvoření spravované identity přiřazené uživatelem.

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

Pak pomocí následujících příkazů udělíte oprávnění k získání a výpisu tajných kódů ze služby Azure Key Vault. Další informace najdete v tématu Přiřazení zásad přístupu.

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

Aby byl výstup považován za úspěšný, musí obsahovat následující kód JSON:

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

Pokud výstup neobsahuje tento kód JSON, před pokračováním problém vyřešte a vyřešte ho.

Pak pomocí následujících příkazů načtěte ID a ID klienta spravované identity přiřazené uživatelem, abyste ho mohli později přiřadit ke službě Azure Container Apps pro přístup ke službě Azure Key Vault:

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

Nasazení aplikace v Azure Container Apps

Kontejnerizovali jste aplikaci a nakonfigurovali spravovanou identitu přiřazenou uživatelem pro přístup ke službě Azure Key Vault. Teď můžete nasadit kontejnerizovanou aplikaci v Azure Container Apps.

Nejprve vytvořte prostředí pro Azure Container Apps. Prostředí v Azure Container Apps vytvoří zabezpečenou hranici kolem skupiny kontejnerových aplikací. KontejnerOvé aplikace nasazené do stejného prostředí se nasazují ve stejné virtuální síti a zapisují protokoly do stejného pracovního prostoru služby Log Analytics. Pomocí příkazu az containerapp env create vytvořte prostředí s jedinečným názvem (například acaenvejb010424), jak je znázorněno v následujícím příkladu:

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

Dále pomocí příkazu az containerapp create vytvořte instanci Container Apps s jedinečným názvem (například acaappejb010424) a spusťte aplikaci po načtení image ze služby Container Registry, jak je znázorněno v následujícím příkladu:

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-username $ACR_USER_NAME \
    --registry-password $ACR_PASSWORD \
    --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'

Poznámka:

Spravovanou identitu přiřazenou uživatelem přiřadíte instanci Container Apps pomocí parametru --user-assigned ${USER_ASSIGNED_IDENTITY_ID}.

Instance Container Apps má přístup ke službě Azure Key Vault se dvěma proměnnými prostředí zadanými v parametrech --env-vars AZURE_CLIENT_ID=${USER_ASSIGNED_IDENTITY_CLIENT_ID} AZURE_KEYVAULT_URL=${AZURE_KEYVAULT_URL}. Nezapomeňte, že AZURE_KEYVAULT_URL proměnná prostředí se prohlížuje kvůli pravidlům mapování proměnných prostředí definovaným specifikací Konfigurace MicroProfile.

Pak pomocí následujícího příkazu načtěte plně kvalifikovanou adresu URL pro přístup k aplikaci:

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

Nakonec znovu spusťte následující příkazy a otestujte ukázku spuštěnou v instanci Container Apps:

# 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)

Měli byste vidět očekávané výstupy popsané v komentářích. Pokud je nevidíte, aplikace se stále může spustit. Chvíli počkejte a zkuste to znovu.

Vyčištění prostředků

Abyste se vyhnuli poplatkům za Azure, měli byste vyčistit nepotřebné prostředky. Pokud už prostředky nepotřebujete, vyčistíte prostředky spuštěním následujících příkazů.

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

Další kroky

Další informace najdete v následujících odkazech: