Partilhar via

Gerenciar tokens OAuth no Serviço de Aplicativo do Azure

Este artigo mostra como gerenciar tokens OAuth para autenticação e autorização internas no Serviço de Aplicativo do Azure.

Recuperar tokens no código da aplicação

O Serviço de Aplicativo do Azure injeta seus tokens específicos do provedor no cabeçalho da solicitação para que você possa acessá-los facilmente. Para obter os tokens específicos do provedor, o armazenamento de tokens deve estar habilitado para o aplicativo.

Envie um pedido HTTP GET a partir do código do cliente /.auth/me, como de uma aplicação móvel ou JavaScript no navegador. O JSON retornado tem os tokens específicos do provedor.

Nota

Os tokens de acesso são para acessar recursos do provedor, portanto, estão presentes somente se você configurar seu provedor com um segredo do cliente.

A tabela a seguir lista os nomes de cabeçalho de token OAuth para vários provedores incorporados do App Service:

Fornecedor Nomes de cabeçalhos
Microsoft Entra X-MS-TOKEN-AAD-ID-TOKEN
X-MS-TOKEN-AAD-ACCESS-TOKEN
X-MS-TOKEN-AAD-EXPIRES-ON
X-MS-TOKEN-AAD-REFRESH-TOKEN
Facebook X-MS-TOKEN-FACEBOOK-ACCESS-TOKEN
X-MS-TOKEN-FACEBOOK-EXPIRES-ON
Google X-MS-TOKEN-GOOGLE-ID-TOKEN
X-MS-TOKEN-GOOGLE-ACCESS-TOKEN
X-MS-TOKEN-GOOGLE-EXPIRES-ON
X-MS-TOKEN-GOOGLE-REFRESH-TOKEN
X X-MS-TOKEN-TWITTER-ACCESS-TOKEN
X-MS-TOKEN-TWITTER-ACCESS-TOKEN-SECRET

Nota

Diferentes estruturas de linguagem podem apresentar esses cabeçalhos ao código do aplicativo em formatos diferentes, como minúsculas ou minúsculas.

Atualizar tokens de autenticação

As informações a seguir referem-se a tokens de provedor. Para tokens de sessão, consulte Estender o período de carência de expiração do token de sessão.

Se o token de acesso do seu provedor expirar, você deverá autenticar novamente o usuário antes de poder usá-lo novamente. Você pode evitar a expiração do token fazendo uma GET chamada para o /.auth/refresh endpoint da sua aplicação.

Para atualizar seu token de acesso a qualquer momento, ligue /.auth/refresh em qualquer idioma. O trecho a seguir usa jQuery para atualizar seus tokens de acesso de um cliente JavaScript.

function refreshTokens() {
  let refreshUrl = "/.auth/refresh";
  $.ajax(refreshUrl) .done(function() {
    console.log("Token refresh completed successfully.");
  }) .fail(function() {
    console.log("Token refresh failed. See application logs for details.");
  });
}

Quando é chamado, o App Service atualiza automaticamente os tokens de acesso no repositório de tokens para o utilizador autenticado. Solicitações subsequentes de tokens obtêm os tokens atualizados. Você pode ver os tokens de atualização e o tempo de expiração dos tokens usando os cabeçalhos listados em Recuperar tokens no código do aplicativo.

Nota

Se um utilizador revogar as permissões concedidas à sua aplicação, a chamada para /.auth/me poderá falhar com uma resposta 403 Forbidden. Para diagnosticar erros, verifique os logs do aplicativo para obter detalhes.

Configurar provedores para fornecer tokens de atualização

Para que a atualização de token funcione, o armazenamento de tokens deve conter tokens de atualização do seu provedor. Cada provedor documenta como obter seus tokens de atualização. A tabela a seguir fornece um breve resumo:

Fornecedor Atualizar tokens
Microsoft Siga o procedimento em Configurar o provedor do Microsoft Entra para fornecer tokens de atualização.
Facebook Não fornece tokens de atualização. Os tokens de longa duração expiram em 60 dias. Para obter mais informações, consulte Long-Lived Tokens de acesso.
Google Anexe um parâmetro de string de consulta access_type=offline à chamada de API /.auth/login/google. Para obter mais informações, consulte Google Refresh Tokens.
X Os tokens de acesso não expiram. Para obter mais informações, consulte Perguntas frequentes do OAuth.

Configurar o provedor Microsoft Entra para fornecer tokens de atualização

  1. No portal do Azure, vá para o API Playground (visualização) e selecione Nova solicitação , se necessário.
  2. No campo Introduza o caminho relativo do ARM aqui, incluindo a versão da API, insira a seguinte cadeia, substituindo os espaços reservados pelos ID da assinatura, nome do grupo de recursos e nome do aplicativo:
    subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.Web/sites/<app-name>/config/authsettingsV2?api-version=2024-11-01
  3. Selecione Executar.
  4. Selecione PUT no canto superior esquerdo e selecione a guia Corpo da solicitação .
  5. Copie o GET conteúdo da resposta do campo Corpo da resposta e cole-o na guia Corpo da solicitação .
  6. No código, localize a "identityProviders":>>"azureActiveDirectory":"login": seção e adicione a seguinte linha:
    "loginParameters": ["scope=openid profile email offline_access"]
  7. Selecione Executar. O campo Corpo da resposta mostra as alterações.

Offline_access é o escopo que fornece tokens de atualização. O Serviço de Aplicativo já solicita os outros escopos por padrão. Para obter mais informações, consulte OpenID Connect Scopes e Web Apps - Update Auth Settings V2.

Estender o período de carência de expiração do token de sessão

A sessão autenticada expira após 8 horas e segue-se um período de carência predefinido de 72 horas. Dentro desse período de carência, você pode atualizar o token de sessão com o Serviço de Aplicativo sem autenticar novamente o usuário. Pode simplesmente chamar /.auth/refresh quando o seu token de sessão se tornar inválido, e não precisa acompanhar a expiração do token por conta própria.

Quando o período de carência de 72 horas expira, o usuário deve entrar novamente para obter um token de sessão válido. Se você precisar de uma janela de expiração maior do que 72 horas, poderá estendê-la, mas estender a expiração por um longo período pode ter implicações significativas de segurança se um token de autenticação for vazado ou roubado. É melhor deixar a configuração nas 72 horas padrão ou definir o período de extensão para o menor valor possível.

Para estender a janela de expiração padrão, execute o seguinte comando da CLI do Azure no Azure Cloud Shell:

az webapp auth update --resource-group <group_name> --name <app_name> --token-refresh-extension-hours <hours>

Nota

O período de carência aplica-se apenas à sessão autenticada do Serviço de Aplicativo, não aos tokens de acesso dos provedores de identidade. Não existe período de carência para tokens de provedor expirados.

Conteúdo relacionado