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

  • Artigo

Este artigo mostra como personalizar as versões de API e tempo de execução da autenticação e autorização internas no Serviço de Aplicativo.

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 do Azure. Um aplicativo que já usa a API V1 pode atualizar para a versão V2 depois que algumas alterações forem feitas. Especificamente, a configuração secreta deve ser movida para as configurações do aplicativo adesivo de slot. Isso pode ser feito automaticamente na seção "Autenticação" do portal do seu aplicativo.

Atualizar a versão de configuração

Aviso

A migração para a V2 desabilitará o gerenciamento do recurso de Autenticação/Autorização do Serviço de Aplicativo para seu aplicativo por meio de alguns clientes, como sua experiência existente no portal do Azure, CLI do Azure e Azure PowerShell. Esta situação não pode ser revertida.

A API V2 não suporta a criação ou edição de Conta da Microsoft como um provedor distinto, como foi feito na V1. Em vez disso, ele usa a plataforma de identidade convergente da Microsoft para entrar usuários com ID do Microsoft Entra e contas pessoais da Microsoft. Ao alternar para a API V2, a configuração V1 do Microsoft Entra é usada para configurar o provedor de plataforma de identidade da Microsoft. O provedor de conta da Microsoft V1 será levado adiante no processo de migração e continuará a operar normalmente, mas você deve mudar para o modelo de plataforma de identidade Microsoft mais recente. Consulte Suporte para registos de fornecedores de contas Microsoft para saber mais.

O processo de migração automatizada moverá os segredos do provedor para as configurações do aplicativo e, em seguida, converterá o restante da configuração no novo formato. Para usar a migração automática:

  1. Navegue até seu aplicativo no portal e selecione a opção de menu Autenticação .
  2. Se o aplicativo estiver configurado usando o modelo V1, você verá um botão Atualizar .
  3. 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

As etapas a seguir permitirão que você migre manualmente o aplicativo para a API V2 se não desejar usar a versão automática mencionada acima.

Movendo segredos para as configurações do aplicativo

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

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

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

    • ID do Microsoft Entra: clientSecret
    • Google: googleClientSecret
    • Facebook: facebookAppSecret
    • Twitter: twitterConsumerSecret
    • Conta Microsoft: microsoftAccountClientSecret

    Importante

    Os valores secretos são credenciais de segurança importantes e devem ser tratados com cuidado. Não compartilhe esses valores ou persista-os em uma máquina local.

  2. Crie configurações de aplicativo com adesivo de slot para cada valor secreto. Você pode escolher o nome de cada configuração do aplicativo. Seu valor deve corresponder ao que você obteve na etapa anterior ou fazer referência a um segredo do Cofre de Chaves que você criou com esse valor.

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

    # For Web Apps, Google example    
az webapp config appsettings set -g <group_name> -n <site_name> --slot-settings GOOGLE_PROVIDER_AUTHENTICATION_SECRET=<value_from_previous_step>

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

    Nota

    As configurações do aplicativo para essa configuração devem ser marcadas como slot-sticky, o que significa que elas não se moverão entre ambientes durante uma operação de troca de slot. Isso ocorre porque a própria configuração de autenticação está vinculada 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. Escreva a saída restante no arquivo, certificando-se de que nenhum segredo esteja incluído. Em alguns casos, a configuração pode ter matrizes contendo cadeias de caracteres vazias. Certifique-se de que microsoftAccountOAuthScopes isso não aconteça e, se isso acontecer, mude esse valor para null.

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

    • ID do Microsoft Entra: clientSecretSettingName
    • Google: googleClientSecretSettingName
    • Facebook: facebookAppSecretSettingName
    • Twitter: twitterConsumerSecretSettingName
    • Conta Microsoft: microsoftAccountClientSecretSettingName

    Um arquivo de exemplo após essa operação pode ser semelhante ao seguinte, neste caso configurado apenas para o Microsoft Entra ID:

    {
    "id": "/subscriptions/00d563f8-5b89-4c6a-bcec-c1b9f6d607e0/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": "3197c8ed-2470-480a-8fae-58c25558ac9b",
        "clientSecret": "",
        "clientSecretSettingName": "MICROSOFT_IDENTITY_AUTHENTICATION_SECRET",
        "clientSecretCertificateThumbprint": null,
        "issuer": "https://sts.windows.net/0b2ef922-672a-4707-9643-9a5726eec524/",
        "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. Envie este arquivo como a nova configuração de Autenticação/Autorização para seu aplicativo:

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

  6. Valide se seu aplicativo ainda está funcionando conforme o esperado após esse gesto.

  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.

Suporte para registos de fornecedores de contas Microsoft

Se a configuração existente contiver um provedor de Conta da Microsoft e não contiver um provedor do Microsoft Entra, você poderá alternar a configuração para o provedor do Microsoft Entra e executar a migração. Para tal:

  1. Aceda a Registos de aplicações no portal do Azure e localize o registo associado ao fornecedor da sua Conta Microsoft. Pode estar sob o título "Aplicações de conta pessoal".
  2. Navegue até a página "Autenticação" para o registro. Em "Redirecionar URIs", você verá uma entrada terminando em /.auth/login/microsoftaccount/callback. Copie este URI.
  3. Adicione um novo URI que corresponda ao que você acabou de copiar, exceto que ele termine em /.auth/login/aad/callback. Isso permitirá que o registro seja usado pela configuração de Autenticação/Autorização do Serviço de Aplicativo.
  4. Navegue até a configuração de Autenticação/Autorização do Serviço de Aplicativo para seu aplicativo.
  5. Colete a configuração para o provedor de conta da Microsoft.
  6. Configure o provedor Microsoft Entra usando o modo de gerenciamento "Avançado", fornecendo a ID do cliente e os valores secretos do cliente coletados na etapa anterior. Para a URL do Emissor, use <authentication-endpoint>/<tenant-id>/v2.0e substitua <o ponto de extremidade de autenticação pelo ponto de extremidade> de autenticação para seu ambiente de nuvem (por exemplo, ";https://login.microsoftonline.com" para o Azure global), substituindo também o tenant-id> pelo seu Directory (tenant) ID.<
  7. Depois de salvar a configuração, teste o fluxo de login navegando no navegador até o ponto de extremidade no site e conclua o /.auth/login/aad fluxo de entrada.
  8. Neste ponto, você copiou com êxito a configuração, mas a configuração existente do provedor de conta da Microsoft permanece. Antes de removê-lo, certifique-se de que todas as partes do seu aplicativo façam referência ao provedor do Microsoft Entra por meio de links de login, etc. Verifique se todas as partes do seu aplicativo funcionam conforme o esperado.
  9. Depois de validar que as coisas funcionam contra o provedor Microsoft Entra, você pode remover a configuração do provedor de conta da Microsoft.

Aviso

É possível convergir os dois registros modificando os tipos de conta suportados para o registro do aplicativo Microsoft Entra. No entanto, isso forçaria um novo prompt de consentimento para os usuários da Conta da Microsoft, e as declarações de identidade desses usuários podem ser diferentes na estrutura, sub notavelmente alterando os valores desde que uma nova ID do aplicativo está sendo usada. Esta abordagem não é recomendada a menos que seja completamente compreendida. Em vez disso, você deve aguardar o suporte para os dois registros na superfície da API V2.

Mudar para V2

Depois que as etapas acima forem executadas, navegue até o aplicativo no portal do Azure. Selecione a seção "Autenticação (visualização)".

Como alternativa, você pode fazer uma solicitação PUT contra o config/authsettingsv2 recurso no recurso do site. O esquema para a carga útil é o mesmo capturado na configuração baseada em arquivo.

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

Quando você habilita a autenticação/autorização, o middleware da plataforma é injetado em seu 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, seu aplicativo Web ou funcional será executado na versão mais recente do middleware dessa plataforma. Essas atualizações automáticas são sempre compatíveis com versões anteriores. 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. Este artigo explica como fixar temporariamente um aplicativo a uma versão específica do middleware de autenticação.

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

Você pode fixar seu aplicativo em uma versão específica do middleware da plataforma definindo uma runtimeVersion configuração para o aplicativo. Seu aplicativo sempre é executado na versão mais recente, a menos que você opte por fixá-lo explicitamente em uma versão específica. Haverá algumas versões suportadas de cada vez. Se você fixar em uma versão inválida que não é mais suportada, seu aplicativo usará a versão mais recente. Para executar sempre a versão mais recente, defina runtimeVersion como ~1.

Exibir e atualizar a versão atual do tempo de execução

Você pode alterar a versão de tempo de execução usada pelo seu aplicativo. A nova versão do tempo de execução deve entrar em vigor após reiniciar o aplicativo.

Exibir a versão atual do tempo de execução

Você pode exibir a versão atual do middleware de autenticação da plataforma usando a CLI do Azure ou por meio de um dos pontos de extremidade HTTP da versão interna em seu aplicativo.

Da CLI do Azure

Usando a CLI do Azure, exiba a versão atual 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> também pelo nome do grupo de recursos do seu aplicativo.

Você verá o runtimeVersion campo na saída da CLI. Ele será semelhante ao seguinte exemplo de saída, que foi truncado para clareza:

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

Você também pode pressionar o ponto de extremidade /.auth/version em um aplicativo também para exibir a versão atual do middleware na qual o aplicativo está sendo executado. Ele será semelhante ao seguinte exemplo de saída:

{
"version": "1.3.2"
}

Atualizar a versão atual do tempo de execução

Usando a CLI do Azure, você pode atualizar a runtimeVersion configuração no aplicativo com 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> também pelo nome do grupo de recursos do seu aplicativo. Além disso, substitua <version> por uma versão válida do tempo de execução 1.x ou ~1 pela versão mais recente. Consulte as notas de versão sobre as diferentes versões de tempo de execução para ajudar a determinar a versão a ser fixada.

Você pode executar esse comando do Azure Cloud Shell escolhendo Experimentar no exemplo de código anterior. Você também pode usar a CLI do Azure localmente para executar esse comando depois de executar az login para entrar.

Próximos passos

Tutorial: Autenticar e autorizar utilizadores ponto a ponto