Usar referências de Key Vault para o serviço de aplicativo e Azure FunctionsUse Key Vault references for App Service and Azure Functions

Observação

Key Vault referências não estão disponíveis atualmente nos planos de consumo do Linux.Key Vault references are not currently available in Linux consumption plans.

Este tópico mostra como trabalhar com segredos do Cofre de Chaves do Azure no seu aplicativo Serviço de Aplicativo ou no Aplicativo de Funções do Azure sem exigir alterações de código.This topic shows you how to work with secrets from Azure Key Vault in your App Service or Azure Functions application without requiring any code changes. Azure Key Vault é um serviço que fornece gerenciamento centralizado de segredos, com controle total sobre políticas de acesso e histórico de auditoria.Azure Key Vault is a service that provides centralized secrets management, with full control over access policies and audit history.

Concedendo o seu acesso ao aplicativo para o Google Key VaultGranting your app access to Key Vault

Para ler os segredos do Key Vault, você precisa criar um vault e conceder permissão ao aplicativo para acessá-lo.In order to read secrets from Key Vault, you need to have a vault created and give your app permission to access it.

  1. Crie um cofre de chaves seguindo o início rápido do Key Vault .Create a key vault by following the Key Vault quickstart.

  2. Crie uma Identidade gerenciada designada pelo sistema para seu aplicativo.Create a system-assigned managed identity for your application.

    Observação

    No momento, as referências do Key Vault suportam apenas identidades gerenciadas atribuídas pelo sistema.Key Vault references currently only support system-assigned managed identities. Identidades atribuídas pelo usuário não podem ser usadas.User-assigned identities cannot be used.

  3. Crie uma política de acesso no Key Vault para a identidade do aplicativo que você criou anteriormente.Create an access policy in Key Vault for the application identity you created earlier. Ative a permissão secreta "Obter" nesta política.Enable the "Get" secret permission on this policy. Não defina o "aplicativo autorizado" ou as configurações applicationId, pois isso não é compatível com uma identidade gerenciada.Do not configure the "authorized application" or applicationId settings, as this is not compatible with a managed identity.

    Observação

    Key Vault referências não estão atualmente capazes de resolver segredos armazenados em um cofre de chaves com restrições de rede.Key Vault references are not presently able to resolve secrets stored in a key vault with network restrictions.

Sintaxe de referênciaReference syntax

Uma referência do Key Vault é da forma @Microsoft.KeyVault({referenceString}), em que {referenceString} é substituído por uma das seguintes opções:A Key Vault reference is of the form @Microsoft.KeyVault({referenceString}), where {referenceString} is replaced by one of the following options:

Cadeia de caracteres de referênciaReference string DESCRIÇÃODescription
SecretUri = secretUriSecretUri=secretUri O SegredoUri deve ser o URI do plano de dados completo de um segredo no Key Vault, incluindo uma versão, por exemplo, https://myvault.vault.azure.net/secrets/mysecret/ec96f02080254f109c51a1f14cdb1931The SecretUri should be the full data-plane URI of a secret in Key Vault, including a version, e.g., https://myvault.vault.azure.net/secrets/mysecret/ec96f02080254f109c51a1f14cdb1931
VaultName = vaultName; SecretName = secretName; SecretVersion = secretVersionVaultName=vaultName;SecretName=secretName;SecretVersion=secretVersion O VaultName deve ser o nome do seu recurso Key Vault.The VaultName should the name of your Key Vault resource. O SecretName deve ser o nome do segredo de destino.The SecretName should be the name of the target secret. O SecretVersion deve ser a versão do segredo a ser usado.The SecretVersion should be the version of the secret to use.

Por exemplo, uma referência completa com a versão seria parecida com a seguinte:For example, a complete reference with Version would look like the following:

@Microsoft.KeyVault(SecretUri=https://myvault.vault.azure.net/secrets/mysecret/ec96f02080254f109c51a1f14cdb1931)

Como alternativa:Alternatively:

@Microsoft.KeyVault(VaultName=myvault;SecretName=mysecret;SecretVersion=ec96f02080254f109c51a1f14cdb1931)

Configurações de aplicativos de origem do cofre de chavesSource Application Settings from Key Vault

Key Vault referências podem ser usadas como valores para configurações do aplicativo, permitindo que você mantenha os segredos em Key Vault em vez da configuração do site. As configurações do aplicativo são criptografadas com segurança em repouso, mas se você precisar de recursos de gerenciamento secreto, elas deverão entrar em Key Vault.Key Vault references can be used as values for Application Settings, allowing you to keep secrets in Key Vault instead of the site config. Application Settings are securely encrypted at rest, but if you need secret management capabilities, they should go into Key Vault.

Para usar uma referência do Key Vault para uma configuração de aplicativo, defina a referência como o valor da configuração.To use a Key Vault reference for an application setting, set the reference as the value of the setting. Seu aplicativo pode fazer referência ao segredo por meio de sua chave normalmente.Your app can reference the secret through its key as normal. Nenhuma alteração de código é necessária.No code changes are required.

Dica

A maioria das configurações de aplicativos que usam referências do Key Vault deve ser marcada como configurações de slot, pois você deve ter cofres separados para cada ambiente.Most application settings using Key Vault references should be marked as slot settings, as you should have separate vaults for each environment.

Implantação do Azure Resource ManagerAzure Resource Manager deployment

Ao automatizar implantações de recursos por meio dos modelos do Azure Resource Manager, talvez seja necessário sequenciar suas dependências em uma ordem específica para que esse recurso funcione.When automating resource deployments through Azure Resource Manager templates, you may need to sequence your dependencies in a particular order to make this feature work. Observe que você precisará definir as configurações do aplicativo como seu próprio recurso, em vez de usar uma propriedade siteConfig na definição do site.Of note, you will need to define your application settings as their own resource, rather than using a siteConfig property in the site definition. Isso ocorre porque o site precisa ser definido primeiro para que a identidade atribuída pelo sistema seja criada com ele e possa ser usada na política de acesso.This is because the site needs to be defined first so that the system-assigned identity is created with it and can be used in the access policy.

Um exemplo de psuedo-template para um aplicativo de função pode ser semelhante ao seguinte:An example psuedo-template for a function app might look like the following:

{
    //...
    "resources": [
        {
            "type": "Microsoft.Storage/storageAccounts",
            "name": "[variables('storageAccountName')]",
            //...
        },
        {
            "type": "Microsoft.Insights/components",
            "name": "[variables('appInsightsName')]",
            //...
        },
        {
            "type": "Microsoft.Web/sites",
            "name": "[variables('functionAppName')]",
            "identity": {
                "type": "SystemAssigned"
            },
            //...
            "resources": [
                {
                    "type": "config",
                    "name": "appsettings",
                    //...
                    "dependsOn": [
                        "[resourceId('Microsoft.Web/sites', variables('functionAppName'))]",
                        "[resourceId('Microsoft.KeyVault/vaults/', variables('keyVaultName'))]",
                        "[resourceId('Microsoft.KeyVault/vaults/secrets', variables('keyVaultName'), variables('storageConnectionStringName'))]",
                        "[resourceId('Microsoft.KeyVault/vaults/secrets', variables('keyVaultName'), variables('appInsightsKeyName'))]"
                    ],
                    "properties": {
                        "AzureWebJobsStorage": "[concat('@Microsoft.KeyVault(SecretUri=', reference(variables('storageConnectionStringResourceId')).secretUriWithVersion, ')')]",
                        "WEBSITE_CONTENTAZUREFILECONNECTIONSTRING": "[concat('@Microsoft.KeyVault(SecretUri=', reference(variables('storageConnectionStringResourceId')).secretUriWithVersion, ')')]",
                        "APPINSIGHTS_INSTRUMENTATIONKEY": "[concat('@Microsoft.KeyVault(SecretUri=', reference(variables('appInsightsKeyResourceId')).secretUriWithVersion, ')')]",
                        "WEBSITE_ENABLE_SYNC_UPDATE_SITE": "true"
                        //...
                    }
                },
                {
                    "type": "sourcecontrols",
                    "name": "web",
                    //...
                    "dependsOn": [
                        "[resourceId('Microsoft.Web/sites', variables('functionAppName'))]",
                        "[resourceId('Microsoft.Web/sites/config', variables('functionAppName'), 'appsettings')]"
                    ],
                }
            ]
        },
        {
            "type": "Microsoft.KeyVault/vaults",
            "name": "[variables('keyVaultName')]",
            //...
            "dependsOn": [
                "[resourceId('Microsoft.Web/sites', variables('functionAppName'))]"
            ],
            "properties": {
                //...
                "accessPolicies": [
                    {
                        "tenantId": "[reference(concat('Microsoft.Web/sites/',  variables('functionAppName'), '/providers/Microsoft.ManagedIdentity/Identities/default'), '2015-08-31-PREVIEW').tenantId]",
                        "objectId": "[reference(concat('Microsoft.Web/sites/',  variables('functionAppName'), '/providers/Microsoft.ManagedIdentity/Identities/default'), '2015-08-31-PREVIEW').principalId]",
                        "permissions": {
                            "secrets": [ "get" ]
                        }
                    }
                ]
            },
            "resources": [
                {
                    "type": "secrets",
                    "name": "[variables('storageConnectionStringName')]",
                    //...
                    "dependsOn": [
                        "[resourceId('Microsoft.KeyVault/vaults/', variables('keyVaultName'))]",
                        "[resourceId('Microsoft.Storage/storageAccounts', variables('storageAccountName'))]"
                    ],
                    "properties": {
                        "value": "[concat('DefaultEndpointsProtocol=https;AccountName=', variables('storageAccountName'), ';AccountKey=', listKeys(variables('storageAccountResourceId'),'2015-05-01-preview').key1)]"
                    }
                },
                {
                    "type": "secrets",
                    "name": "[variables('appInsightsKeyName')]",
                    //...
                    "dependsOn": [
                        "[resourceId('Microsoft.KeyVault/vaults/', variables('keyVaultName'))]",
                        "[resourceId('Microsoft.Insights/components', variables('appInsightsName'))]"
                    ],
                    "properties": {
                        "value": "[reference(resourceId('microsoft.insights/components/', variables('appInsightsName')), '2015-05-01').InstrumentationKey]"
                    }
                }
            ]
        }
    ]
}

Observação

Neste exemplo, a implantação do controle de origem depende das configurações do aplicativo.In this example, the source control deployment depends on the application settings. Esse comportamento normalmente é inseguro, pois a atualização da configuração do aplicativo se comporta de maneira assíncrona.This is normally unsafe behavior, as the app setting update behaves asynchronously. No entanto, como incluímos a configuração do aplicativo WEBSITE_ENABLE_SYNC_UPDATE_SITE, a atualização é síncrona.However, because we have included the WEBSITE_ENABLE_SYNC_UPDATE_SITE application setting, the update is synchronous. Isso significa que a implantação do controle de origem só será iniciada quando as configurações do aplicativo tiverem sido totalmente atualizadas.This means that the source control deployment will only begin once the application settings have been fully updated.

Solucionando problemas de referências de Key VaultTroubleshooting Key Vault References

Se uma referência não for resolvida corretamente, o valor de referência será usado em seu lugar.If a reference is not resolved properly, the reference value will be used instead. Isso significa que, para as configurações do aplicativo, uma variável de ambiente seria criada cujo valor tem a sintaxe @Microsoft.KeyVault(...).This means that for application settings, an environment variable would be created whose value has the @Microsoft.KeyVault(...) syntax. Isso pode fazer com que o aplicativo gere erros, pois estava esperando um segredo de uma determinada estrutura.This may cause the application to throw errors, as it was expecting a secret of a certain structure.

Normalmente, isso se deve a uma configuração incorreta da política de acesso de Key Vault.Most commonly, this is due to a misconfiguration of the Key Vault access policy. No entanto, também pode ser devido a um segredo não mais existente ou a um erro de sintaxe na própria referência.However, it could also be due to a secret no longer existing or a syntax error in the reference itself.

Se a sintaxe estiver correta, você poderá exibir outras causas de erro verificando o status atual da resolução no Portal.If the syntax is correct, you can view other causes for error by checking the current resolution status in the portal. Navegue até configurações do aplicativo e selecione "Editar" para a referência em questão.Navigate to Application Settings and select "Edit" for the reference in question. Abaixo da configuração de configuração, você deve ver informações de status, incluindo quaisquer erros.Below the setting configuration, you should see status information, including any errors. A ausência deles implica que a sintaxe de referência é inválida.The absence of these implies that the reference syntax is invalid.

Você também pode usar um dos detectores internos para obter informações adicionais.You can also use one of the built-in detectors to get additional information.

Usando o detector para o serviço de aplicativoUsing the detector for App Service

  1. No portal, navegue até seu aplicativo.In the portal, navigate to your app.
  2. Selecione diagnosticar e resolver problemas.Select Diagnose and solve problems.
  3. Escolha disponibilidade e desempenho e selecione aplicativo Web inativo.Choose Availability and Performance and select Web app down.
  4. Encontre Key Vault diagnóstico de configurações do aplicativo e clique em mais informações.Find Key Vault Application Settings Diagnostics and click More info.

Usando o detector para Azure FunctionsUsing the detector for Azure Functions

  1. No portal, navegue até seu aplicativo.In the portal, navigate to your app.
  2. Navegue até recursos da plataforma.Navigate to Platform features.
  3. Selecione diagnosticar e resolver problemas.Select Diagnose and solve problems.
  4. Escolha disponibilidade e desempenho e selecione aplicativo de funções ou relatando erros.Choose Availability and Performance and select Function app down or reporting errors.
  5. Clique em Key Vault configurações do aplicativo diagnósticos.Click on Key Vault Application Settings Diagnostics.