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

Este artigo descreve como personalizar as versões de API e de runtime da autenticação e autorização internas no 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 são feitas. Especificamente, a configuração secreta deve ser movida para as configurações de slot fixas do aplicativo. Você pode mover a configuração secreta automaticamente da seção Autenticação do seu aplicativo no portal.

Atualizar a versão da configuração

Aviso

A migração para a V2 desativa o gerenciamento do recurso de autenticação/autorização do App Service para sua aplicação por meio de alguns clientes, como a interface atual no Portal do Azure, a CLI do Azure e o Azure PowerShell. Essa migração não pode ser revertida.

A API V2 não dá suporte à criação ou edição de uma conta da Microsoft como um provedor distinto como a V1. Em vez disso, ele usa a plataforma de identidade da Microsoft convergida para conectar usuários com o Microsoft Entra e contas pessoais da Microsoft. Quando você alterna 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 é levado adiante no processo de migração e continua operando normalmente, mas você deve migrar para o modelo mais recente da plataforma de identidade da Microsoft. Para obter mais informações, consulte Alternar uma configuração para um provedor do Microsoft Entra.

O processo de migração automatizado move os segredos do provedor para as configurações do aplicativo e converte o restante da configuração no novo formato. Para usar a migração automática:

Vá para o seu aplicativo no portal e selecione Configurações>Autenticação no painel esquerdo.
Se o aplicativo estiver configurado com o modelo V1, você verá um botão Atualizar .
Selecione o botão Atualizar. 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 permitem migrar manualmente um aplicativo para a API V2 se você não quiser 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.

Obtenha sua configuração existente usando a API V1:
```
az webapp auth show -g <group_name> -n <app_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 persista-os em um computador local.
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 referenciar um segredo do Azure 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 comando para cada provedor:
```
# 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>
```
Observação

As configurações de aplicativo para essa configuração devem ser marcadas como slot-sticky, o que significa que elas não serão movidas entre ambientes durante uma operação de troca de slot. Essa configuração é necessária porque sua configuração de autenticação está vinculada ao ambiente.
Crie um novo arquivo JSON denominado authsettings.json. Pegue a saída que você recebeu anteriormente e remova cada valor secreto da mesma. Adicione o restante da saída ao arquivo, certificando-se de que nenhum dado confidencial seja incluído. Em alguns casos, a configuração pode ter matrizes que contêm cadeias de caracteres vazias. Certifique-se de que microsoftAccountOAuthScopes não aconteça. Se isso acontecer, altere o valor para null.

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 da Microsoft: microsoftAccountClientSecretSettingName

Um arquivo de configurações após essa operação pode ser semelhante ao seguinte, nesse caso, configurado apenas para a ID do Microsoft Entra:

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

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/<app_name>/config/authsettings?api-version=2020-06-01" --body @./authsettings.json

Valide se seu aplicativo ainda está operando conforme o esperado depois de enviar o arquivo.
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.

Alterar uma configuração para um provedor Microsoft Entra

Se sua configuração existente contiver um provedor de conta da Microsoft e não contiver um provedor do Microsoft Entra, você poderá alterar a configuração para o provedor do Microsoft Entra e, em seguida, executar a migração:

Acesse registros de aplicativo no portal do Azure e localize o registro associado ao seu provedor de conta da Microsoft. Ele pode estar no cabeçalho aplicativos próprios.
Acesse a página Autenticação (Versão Prévia) do registro. Em URI de Redirecionamento, você deverá ver uma entrada terminando em /.auth/login/microsoftaccount/callback. Copie esse URI.
Adicione um novo URI que corresponda ao que você acabou de copiar, mas termine com /.auth/login/aad/callback. Esse URI permite que o registro seja usado pela configuração de autenticação/autorização do Serviço de Aplicativo.
Acesse seu aplicativo no portal. Selecione Configurações>Autenticação.
Colete a configuração do provedor de conta da Microsoft.
Configure o provedor do 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. Substitua <authentication-endpoint> pelo ponto de extremidade de autenticação do seu ambiente em nuvem (por exemplo, "https://login.microsoftonline.com"" para o Microsoft Entra ID global). Substitua <tenant-id> pela ID do seu Diretório (locatário).
Depois de salvar a configuração, teste o fluxo de login navegando no seu navegador até o endpoint /.auth/login/aad em seu site e concluindo o fluxo de login.
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, verifique se todas as partes do seu aplicativo fazem referência ao provedor do Microsoft Entra por meio de links de entrada e assim por diante. Verifique se todas as partes do aplicativo funcionam conforme o esperado.
Depois de validar que tudo funciona com o provedor do 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 com suporte para o registro do aplicativo Microsoft Entra. No entanto, essa configuração exigiria uma nova solicitação de consentimento para usuários com conta da Microsoft, e as reivindicações de identidade desses usuários poderiam apresentar uma estrutura diferente, sub com valores significativamente alterados devido ao uso de um novo ID de aplicativo. Não recomendamos essa abordagem, a menos que você a entenda completamente. Em vez disso, você deve aguardar o suporte para os dois registros na interface da API V2.

Alternar para V2

Depois de concluir as etapas anteriores, acesse o aplicativo no portal do Azure. Selecione a seção Autenticação (versão prévia ).

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

Fixe 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 é 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. Esta seção 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 ancorar seu aplicativo a uma versão específica do middleware da plataforma configurando uma runtimeVersion definiçã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. Há algumas versões suportadas ao mesmo tempo. Se você fixar uma versão inválida que não é mais compatível, seu aplicativo passará a usar a versão mais recente. Para sempre executar 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 tempo de execução usada pelo seu aplicativo. A nova versão de runtime deve entrar em vigor depois que você reiniciar o aplicativo.

Exibir a versão de runtime atual

Você pode verificar 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 de versão integrados ao seu aplicativo.

A partir 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>

Nesse código, substitua <my_app_name> pelo nome de seu aplicativo. Substitua <my_resource_group> pelo nome do grupo de recursos do aplicativo.

Você verá o campo runtimeVersion na saída da CLI. É semelhante ao exemplo de saída a seguir, que foi abreviado para maior clareza:

{
  "additionalLoginParams": null,
  "allowedAudiences": null,
    ...
  "runtimeVersion": "1.3.2",
    ...
}

Do ponto de extremidade de versão

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

{
"version": "1.3.2"
}

Atualizar a versão de runtime atual

Com a CLI do Azure, você pode atualizar a runtimeVersion configuração em um aplicativo 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 do aplicativo. Substitua <version> por uma versão válida do 1.x runtime ou use ~1 para a versão mais recente. Para determinar a versão a ser fixada no Azure Functions, consulte a visão geral das versões de runtime do Azure Functions.

Você pode executar esse comando no Azure Cloud Shell selecionando Open Cloud Shell 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 fazer login.

Próxima etapa

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

Comentários

Esta página foi útil?

Last updated on 2026-04-24