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

  • Artigo

Este artigo mostra como personalizar a API e as versões de runtime da autenticação e da autorização internas do Serviço de Aplicativo.

Há duas versões da API de gerenciamento para a 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 de slot fixas do aplicativo. Isso pode ser feito automaticamente na seção "Autenticação" do portal para seu aplicativo.

Atualizar a versão da configuração

Aviso

A migração para V2 desabilitará o gerenciamento do recurso de Autenticação/Autorização do Serviço de Aplicativo para seu aplicativo através de alguns clientes, tais como sua experiência existente no portal do Azure, CLI do Azure e Azure PowerShell. Isso não pode ser revertido.

A API C2 não dá suporte à criação ou edição da conta da Microsoft como um provedor distinto, como ocorreu na V1. Em vez disso, ele usa a plataforma de identidade convergente da Microsoft para conectar usuários com contas Microsoft pessoais e do Microsoft Entra. Ao trocar para a API V2, a configuração do Microsoft Entra V1 é usada para configurar o provedor da plataforma de Identidade da Microsoft. O provedor de Conta da Microsoft V1 será postergado no processo de migração e continuará funcionando normalmente, mas você deve ir para o modelo mais recente da plataforma de Identidade da Microsoft. Consulte suporte para registros de provedor de Conta da Microsoft para saber mais.

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

  1. Navegue até o seu aplicativo no portal e selecione a opção de menu Autenticação.
  2. Se o aplicativo for configurado usando o modelo V1, você verá um botão de Atualização.
  3. Examine a descrição no prompt de confirmação. Se você estiver pronto para realizar a migração, selecione Atualização quando solicitado.

Gerenciamento manual da migração

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

Transferência de 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>

    No conteúdo 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 compartilhe esses valores ou mantenha-os em um computador local.

  2. Crie configurações de slot fixas de aplicativo para cada valor secreto. Você pode escolher o nome de cada configuração de aplicativo. Seu valor deve corresponder ao que você obteve na etapa anterior ou em fazer referência a um segredo do Key Vault 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, X example
az functionapp config appsettings set -g <group_name> -n <site_name> --slot-settings TWITTER_PROVIDER_AUTHENTICATION_SECRET=<value_from_previous_step>

    Observação

    As configurações de aplicativo para essa configuração devem ser marcadas como fixas para o slot, o que significa que elas não serão movidas entre ambientes durante uma operação de troca de slot. Isso ocorre porque sua configuração de autenticação em si está vinculada ao ambiente.

  3. Crie um novo arquivo JSON denominado authsettings.json. Pegue a saída que você recebeu anteriormente e remova cada valor secreto da mesma. Grave a saída restante no arquivo, certificando-se de que nenhum segredo esteja incluído. Em alguns casos, a configuração pode ter matrizes com cadeias de caracteres vazias. Certifique-se de que microsoftAccountOAuthScopes não tenha, mas se tiver, mude esse valor para null.

  4. Adicione uma propriedade à authsettings.json, que aponta para o nome da configuração de aplicativo que você criou anteriormente para cada provedor:

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

    Um arquivo de exemplo após essa operação pode ser semelhante ao seguinte, neste caso, somente configurado 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": "00001111-aaaa-2222-bbbb-3333cccc4444",
        "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á operando conforme o esperado após essa ação.

  7. Exclua o arquivo usado nas etapas anteriores.

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

Suporte para registros de provedor de Conta da Microsoft

Se sua configuração existente contém um provedor de Conta da Microsoft e não um provedor Microsoft Entra, você poderá trocar a configuração para o provedor Microsoft Entra, então fazer a migração. Para fazer isso:

  1. Vá para Registros de Aplicativo no portal do Azure e localize o registro associado ao seu provedor de conta da Microsoft. Pode estar no cabeçalho "Aplicativos de conta pessoal".
  2. Navegue até a página "Autenticação" para o registro. Em "URIs de redirecionamento", você deverá ver uma entrada terminando em /.auth/login/microsoftaccount/callback. Copie esse URI.
  3. Adicione um novo URI que corresponda ao que você acabou de copiar, exceto em que ele termina 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 do 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 de segredo do cliente coletados na etapa anterior. Para a URL do Emissor, use <authentication-endpoint>/<tenant-id>/v2.0 e substitua <authentication-endpoint> pelo ponto de extremidade de autenticação do seu ambiente de nuvem (por exemplo, "https://login.microsoftonline.com"" para o Microsoft Entra ID global), também substituindo <tenant-id> pela sua ID de Diretório (locatário).
  7. Uma vez que você tenha salvo a configuração, teste o fluxo de logon navegando em seu navegador até o ponto de extremidade /.auth/login/aad em seu site e complete o fluxo de entrada.
  8. Neste ponto, você copiou com sucesso a configuração, mas a configuração existente do provedor da conta Microsoft permanece. Antes de removê-lo, verifique se todas as partes do seu aplicativo referenciam o provedor Microsoft Entra através de links de logon etc. Verifique se todas as partes do aplicativo funcionam como o esperado.
  9. Assim que você tiver validado se as coisas funcionam no provedor Microsoft Entra, poderá remover a configuração do provedor de Conta da Microsoft.

Aviso

É possível convergir os dois registros modificando os tipos de conta com suporte 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 dos usuários podem ser diferentes na estrutura, sub notavelmente alterando os valores, uma vez que uma nova ID do aplicativo está sendo usada. Essa abordagem não é recomendada a menos que seja totalmente compreendida. Em vez disso, você deve aguardar o suporte para os dois registros na superfície da API V2.

Alternando para V2

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

Como alternativa, você pode fazer uma solicitação PUT em relação ao recurso config/authsettingsv2 sob o recurso site. O esquema do conteúdo é o mesmo que foi capturado em Configuração baseada em arquivo.

Fixar seu aplicativo em uma versão de runtime de autenticação específica

Quando você habilita a autenticação/autorização, o middleware da plataforma é injetado em seu pipeline de solicitações HTTP, conforme descrito na visão geral de recurso. Esse middleware de plataforma é atualizado periodicamente com novos recursos e aprimoramentos como parte das atualizações de plataforma rotineiras. Por padrão, seu aplicativo Web ou de funções será executado na versão mais recente deste middleware de plataforma. Essas atualizações automáticas são sempre compatíveis com versões anteriores. No entanto, em raras ocasiões que essa atualização automática apresente um problema em runtime para seu aplicativo Web ou de funções, você poderá reverter temporariamente para a versão de middleware anterior. Este artigo explica como fixar temporariamente um aplicativo em uma versão específica do middleware de autenticação.

Atualizações de versão automática e manual

Você pode fixar seu aplicativo em uma versão específica do middleware da plataforma definindo uma configuração runtimeVersion para o aplicativo. Seu aplicativo sempre é executado na versão mais recente, a menos que você opte por fixá-lo explicitamente de volta a uma versão específica. Haverá algumas versões com suporte por vez. Se você fixar uma versão inválida que não tenha mais suporte, 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 de runtime atual

Você pode alterar a versão de runtime usada por você aplicativo de funções. A nova versão de runtime deve entrar em vigor após a reinicialização do aplicativo.

Exibir a versão de runtime atual

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

Na CLI do Azure

Com a CLI do Azure, exiba a versão de middleware atual com o comando az webapp auth show.

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

Nesse código, substitua <my_app_name> pelo nome de seu aplicativo de funções. Substitua também <my_resource_group> pelo nome do grupo de recursos para seu aplicativo de funções.

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

{
  "additionalLoginParams": null,
  "allowedAudiences": null,
    ...
  "runtimeVersion": "1.3.2",
    ...
}
Do ponto de extremidade de versão

Você também pode clicar em ponto de extremidade/.auth/version em um aplicativo também para exibir a versão de middleware atual em que o aplicativo está sendo executado. A saída será semelhante à seguinte:

{
"version": "1.3.2"
}

Atualizar a versão de runtime atual

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

Execute esse comando a partir 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 após a execução de az login para entrar.

Próximas etapas

Tutorial: autenticar e autorizar usuários de ponta a ponta