Gerenciar a API e as versões de tempo de execução da autenticação do Serviço de Aplicativo

Este artigo descreve como personalizar a API e as versões em tempo de execução da autenticação e autorização incorporadas no App Service.

Há duas versões da API de gerenciamento para autenticação do Serviço de Aplicativo. A versão V2 é necessária para a experiência de autenticação no portal Azure. Uma aplicação que já utilize a API V1 pode atualizar para a versão V2 após algumas alterações. Especificamente, a configuração secreta deve ser movida para as configurações de aplicação slot-sticky. Pode mover automaticamente a configuração secreta a partir da secção de Autenticação da sua aplicação no portal.

Atualizar a versão de configuração

Aviso

A migração para a V2 desativa a gestão da funcionalidade de autenticação/autorização do App Service para a sua aplicação através de alguns clientes, como a sua experiência existente no portal Azure, Azure CLI e Azure PowerShell. Esta migração não pode ser revertida.

A API do V2 não suporta a criação ou edição de uma conta Microsoft como um fornecedor distinto, como o faz o V1. Em vez disso, utiliza a plataforma de identidade convergente da Microsoft para iniciar sessão de utilizadores tanto com Microsoft Entra como com contas pessoais da Microsoft. Quando você alterna para a API V2, a configuração V1 Microsoft Entra é usada para configurar o provedor de plataforma de identidade da Microsoft. O fornecedor de contas Microsoft V1 é mantido no processo de migração e continua a funcionar normalmente, mas deve passar para o modelo mais recente da Microsoft Identity Platform. Para mais informações, consulte Mudar uma configuração para um fornecedor Microsoft Entra.

O processo de migração automatizada move os segredos do fornecedor para as definições da aplicação e depois converte o resto da configuração para o novo formato. Para usar a migração automática:

  1. Vai à tua aplicação no portal e seleciona Definições>Autenticação no painel esquerdo.
  2. Se a aplicação estiver configurada com o modelo V1, vê um botão de Atualizar .
  3. Selecione o botão Atualizar . Revise a descrição no prompt de confirmação. Se você estiver pronto para executar a migração, selecione Atualizar no prompt.

Gerenciando manualmente a migração

Os passos seguintes permitem-lhe migrar manualmente uma aplicação para a API V2 caso não queira usar a versão automática descrita anteriormente.

Mover segredos para as configurações do aplicativo

Para mover segredos do provedor de identidade para as configurações do aplicativo, conclua estas etapas.

  1. Obtenha sua configuração existente usando a API V1:

    az webapp auth show -g <group_name> -n <app_name>

    Na carga JSON resultante, anote o valor secreto usado para cada provedor que você configurou:

    • Microsoft Entra: clientSecret
    • Google: googleClientSecret
    • Facebook: facebookAppSecret
    • X: twitterConsumerSecret
    • Conta Microsoft: microsoftAccountClientSecret

    Importante

    Os valores secretos são credenciais de segurança importantes e devem ser tratados com cuidado. Não partilhe estes valores nem os mantenha numa máquina local.

  2. Crie definições de aplicação do tipo slot-sticky para cada valor secreto. Pode escolher o nome de cada configuração de aplicação. O seu valor deve corresponder ao que obteve no passo anterior ou referir-se a um segredo do Azure Key Vault que criou com esse valor.

    Para criar a configuração, pode usar o portal Azure ou executar uma variação do seguinte comando para cada fornecedor:

    # For web apps, Google example    
az webapp config appsettings set -g <group_name> -n <app_name> --slot-settings GOOGLE_PROVIDER_AUTHENTICATION_SECRET=<value_from_previous_step>

# For Azure Functions, X example
az functionapp config appsettings set -g <group_name> -n <app_name> --slot-settings TWITTER_PROVIDER_AUTHENTICATION_SECRET=<value_from_previous_step>

    Nota

    As definições da aplicação para esta configuração devem ser marcadas como aderentes ao slot, o que significa que não se moverão entre ambientes durante uma operação de troca de slot. Esta configuração é necessária porque a sua configuração de autenticação está ligada ao ambiente.

  3. Crie um novo arquivo JSON chamado authsettings.json. Pegue a saída que você recebeu anteriormente e remova cada valor secreto dela. Adicione a saída restante ao ficheiro, certificando-se de que não há segredos incluídos. Em alguns casos, a configuração pode ter arrays que contêm strings vazias. Certifica-te que isso microsoftAccountOAuthScopes não acontece. Se sim, altere o valor para null.

  4. Adicione uma propriedade ao authsettings.json que aponte para o nome da configuração de aplicativo que você criou previamente para cada provedor:

    • Microsoft Entra: clientSecretSettingName
    • Google: googleClientSecretSettingName
    • Facebook: facebookAppSecretSettingName
    • X: twitterConsumerSecretSettingName
    • Conta Microsoft: microsoftAccountClientSecretSettingName

    Um ficheiro de definições após esta operação pode parecer semelhante ao seguinte, neste caso apenas configurado para o Microsoft Entra ID:

    {
    "id": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/myresourcegroup/providers/Microsoft.Web/sites/mywebapp/config/authsettings",
    "name": "authsettings",
    "type": "Microsoft.Web/sites/config",
    "location": "Central US",
    "properties": {
        "enabled": true,
        "runtimeVersion": "~1",
        "unauthenticatedClientAction": "AllowAnonymous",
        "tokenStoreEnabled": true,
        "allowedExternalRedirectUrls": null,
        "defaultProvider": "AzureActiveDirectory",
        "clientId": "00001111-aaaa-2222-bbbb-3333cccc4444",
        "clientSecret": "",
        "clientSecretSettingName": "MICROSOFT_IDENTITY_AUTHENTICATION_SECRET",
        "clientSecretCertificateThumbprint": null,
        "issuer": "https://sts.windows.net/aaaabbbb-0000-cccc-1111-dddd2222eeee/",
        "allowedAudiences": [
            "https://mywebapp.azurewebsites.net"
        ],
        "additionalLoginParams": null,
        "isAadAutoProvisioned": true,
        "aadClaimsAuthorization": null,
        "googleClientId": null,
        "googleClientSecret": null,
        "googleClientSecretSettingName": null,
        "googleOAuthScopes": null,
        "facebookAppId": null,
        "facebookAppSecret": null,
        "facebookAppSecretSettingName": null,
        "facebookOAuthScopes": null,
        "gitHubClientId": null,
        "gitHubClientSecret": null,
        "gitHubClientSecretSettingName": null,
        "gitHubOAuthScopes": null,
        "twitterConsumerKey": null,
        "twitterConsumerSecret": null,
        "twitterConsumerSecretSettingName": null,
        "microsoftAccountClientId": null,
        "microsoftAccountClientSecret": null,
        "microsoftAccountClientSecretSettingName": null,
        "microsoftAccountOAuthScopes": null,
        "isAuthFromFile": "false"
    }   
}

  5. Submeta este ficheiro como a nova configuração de autenticação/autorização para a sua aplicação:

    az rest --method PUT --url "/subscriptions/<subscription_id>/resourceGroups/<group_name>/providers/Microsoft.Web/sites/<app_name>/config/authsettings?api-version=2020-06-01" --body @./authsettings.json

  6. Valida que a tua aplicação continua a funcionar como esperado depois de submeteres o ficheiro.

  7. Exclua o arquivo usado nas etapas anteriores.

Agora você migrou o aplicativo para armazenar segredos do provedor de identidade como configurações do aplicativo.

Mudar a configuração para um fornecedor do Microsoft Entra

Se a sua configuração atual contiver um fornecedor de conta Microsoft e não um fornecedor Microsoft Entra, pode alterar a configuração para o fornecedor Microsoft Entra e depois realizar a migração:

  1. Vá a Registos de Aplicações no portal Azure e encontre o registo associado ao seu fornecedor de conta Microsoft. Pode estar na secção Aplicações Próprias .
  2. Vá à página de Autenticação (Pré-visualização) para o registo. Em URI de Redirecionamento, deverá ver uma entrada terminada em /.auth/login/microsoftaccount/callback. Copie este URI.
  3. Adicione um novo URI que corresponda ao que acabou de copiar, mas termine com /.auth/login/aad/callback. Este URI permite que o registo seja utilizado pela configuração de autenticação/autorização do App Service.
  4. Vai à tua aplicação no portal. Selecione Configurações>Autenticação.
  5. Recolha a configuração para o fornecedor da conta Microsoft.
  6. Configure o fornecedor Microsoft Entra usando o modo de gestão avançada , fornecendo o ID do cliente e os valores secretos do cliente que recolheu na etapa anterior. Para a URL do Emissor, use <authentication-endpoint>/<tenant-id>/v2.0. Substitua <authentication-endpoint> pelo endpoint de autenticação do seu ambiente cloud (por exemplo, "https://login.microsoftonline.com" para o Microsoft Entra ID global). Substitua <tenant-id> pelo seu ID de Diretório (inquilino).
  7. Depois de guardar a configuração, teste o fluxo de início de sessão navegando no seu navegador até ao /.auth/login/aad endpoint do seu site e completando o fluxo de iniciação de sessão.
  8. Neste ponto, copiaste com sucesso a configuração, mas a configuração existente do fornecedor de conta Microsoft mantém-se. Antes de o remover, certifique-se de que todas as partes da sua aplicação fazem referência ao fornecedor Microsoft Entra através de links de login e afins. Verifica se todas as partes da tua aplicação funcionam como esperado.
  9. Depois de validares que tudo funciona com o fornecedor Microsoft Entra, podes remover a configuração do fornecedor de contas Microsoft.

Aviso

É possível convergir os dois registos modificando os tipos de conta suportados para o registo da aplicação Microsoft Entra. No entanto, esta configuração forçaria uma nova solicitação de consentimento para os utilizadores da conta Microsoft, e as alegações de identidade desses utilizadores poderiam ter uma estrutura diferente, sub notavelmente alterando os valores porque um novo ID de aplicação está a ser utilizado. Não recomendamos esta abordagem a menos que a compreenda completamente. Em vez disso, você deve aguardar o suporte para os dois registros na superfície da API V2.

Mudar para V2

Depois de completares os passos anteriores, vai à aplicação no portal Azure. Selecione a secção de Autenticação (pré-visualização ).

Alternativamente, pode fazer um pedido PUT ao recurso config/authsettingsv2 no recurso do site. O esquema da carga útil é o mesmo que o capturado na configuração baseada em ficheiros.

Afixar o seu aplicativo a uma versão específica do runtime de autenticação

Quando o utilizador habilita a autenticação/autorização, o middleware da plataforma é injetado no pipeline de solicitação HTTP, conforme descrito na visão geral do recurso. Este middleware de plataforma é atualizado periodicamente com novos recursos e melhorias como parte das atualizações de rotina da plataforma. Por padrão, a sua aplicação web ou de funções corre na versão mais recente da plataforma de middleware. Estas atualizações automáticas são sempre retrocompatíveis. No entanto, no caso raro de essa atualização automática introduzir um problema de tempo de execução para seu aplicativo Web ou funcional, você pode reverter temporariamente para a versão anterior do middleware. Esta secção explica como fixar temporariamente uma aplicação a uma versão específica do middleware de autenticação.

Atualizações automáticas e manuais de versões

Pode fixar a sua aplicação a uma versão específica do middleware da plataforma configurando uma runtimeVersion definição para a aplicação. A tua aplicação corre sempre na versão mais recente, a menos que escolhas fixá-la explicitamente numa versão específica. Existem algumas versões que são suportadas ao mesmo tempo. Se fixares numa versão não válida que já não é suportada, a tua aplicação usa a versão mais recente. Para correr sempre a versão mais recente, defina runtimeVersion para ~1.

Ver e atualizar a versão atual do ambiente de execução

Você pode alterar a versão de tempo de execução usada pelo seu aplicativo. A nova versão de runtime deverá entrar em vigor depois de reiniciares a aplicação.

Ver a versão atual do runtime

Pode visualizar a versão atual do middleware de autenticação da plataforma usando o Azure CLI ou através de um dos endpoints HTTP incorporados na sua aplicação.

Na CLI do Azure

Ao usar a CLI do Azure, visualize a versão do middleware com o comando az webapp auth show.

az webapp auth show --name <my_app_name> \
--resource-group <my_resource_group>

Neste código, substitua <my_app_name> pelo nome do seu aplicativo. Substitua <my_resource_group> pelo nome do grupo de recursos da sua aplicação.

Você verá o runtimeVersion campo na saída da CLI. Semelha-se ao seguinte resultado de exemplo, que é truncado para melhor compreensão.

{
  "additionalLoginParams": null,
  "allowedAudiences": null,
    ...
  "runtimeVersion": "1.3.2",
    ...
}
A partir do ponto de extremidade da versão

Também podes aceder ao endpoint /.auth/version numa aplicação para ver a versão atual do middleware em que a aplicação está a correr. A saída será semelhante à seguinte:

{
"version": "1.3.2"
}

Atualizar a versão do runtime atual

Com o Azure CLI, pode atualizar a runtimeVersion definição numa aplicação usando o comando az webapp auth update :

az webapp auth update --name <my_app_name> \
--resource-group <my_resource_group> \
--runtime-version <version>

Substitua <my_app_name> pelo nome do seu aplicativo. Substitua <my_resource_group> pelo nome do grupo de recursos da sua aplicação. Substitua <version> por uma versão válida do runtime 1. X , ou use ~1 para a versão mais recente. Para determinar a versão a fixar para o Azure Functions, veja a visão geral das versões em tempo de execução do Azure Functions.

Pode executar este comando a partir do Azure Cloud Shell selecionando Open Cloud Shell no exemplo de código anterior. Também podes usar o Azure CLI localmente para executar este comando depois de executares o az login para iniciar sessão.

Próximo passo

Tutorial: Autenticar e autorizar utilizadores ponto a ponto

  • Last updated on