Autorizar o acesso a aplicativos Web usando o OpenID Connect e o Azure Ative Directory

OpenID Connect é uma camada de identidade simples construída sobre o protocolo OAuth 2.0. O OAuth 2.0 define mecanismos para obter e usar tokens de acesso para acessar recursos protegidos, mas não define métodos padrão para fornecer informações de identidade. O OpenID Connect implementa a autenticação como uma extensão do processo de autorização do OAuth 2.0. Ele fornece informações sobre o usuário final na forma de um id_token que verifica a identidade do usuário e fornece informações básicas de perfil sobre o usuário.

OpenID Connect é a nossa recomendação se estiver a criar uma aplicação web alojada num servidor e acedida através de um browser.

Registre a sua aplicação com o seu inquilino do AD

Primeiro, registre seu aplicativo com seu locatário do Azure Ative Directory (Azure AD). Isso lhe dará uma ID de aplicativo para seu aplicativo, bem como permitirá que ele receba tokens.

1. Inicie sessão no portal Azure.

2. Escolha o seu inquilino do Azure AD selecionando a sua conta no canto superior direito da página, seguido pela seleção da navegação Alternar Diretório e, em seguida, selecione o inquilino apropriado.

   • Ignore esta etapa se você tiver apenas um locatário do Azure AD em sua conta ou se já tiver selecionado o locatário apropriado do Azure AD.

3. No portal do Azure, procure e selecione Azure Ative Directory.

4. No menu esquerdo Azure Ative Directory, selecione Registos de Aplicações e, em seguida, selecione Novo registo.

5. Siga as instruções e crie um novo aplicativo. Não importa se é uma aplicação web ou uma aplicação cliente público (móvel & desktop) para este tutorial, mas se pretender exemplos específicos para aplicações web ou aplicações cliente público, confira os nossos guias de início rápido.

   • Nome é o nome do aplicativo e descreve seu aplicativo para os usuários finais.
   • Em Tipos de conta suportados, selecione Contas em qualquer diretório organizacional e contas pessoais da Microsoft.
   • Forneça o URI de redirecionamento . Para aplicações Web, este é o URL base da sua aplicação onde os utilizadores podem iniciar sessão. Por exemplo, http://localhost:12345. Para cliente público (móvel & desktop), o Azure AD o usa para retornar respostas de token. Insira um valor específico para seu aplicativo. Por exemplo, http://MyFirstAADApp.

6. Depois de concluir o registro, o Azure AD atribuirá ao seu aplicativo um identificador de cliente exclusivo (o ID do Aplicativo). Você precisa desse valor nas próximas seções, portanto, copie-o da página do aplicativo.

7. Para localizar a sua aplicação no portal do Azure, selecione Registos de aplicaçõese, em seguida, selecione Ver todas as aplicações.

Fluxo de autenticação usando o OpenID Connect

O fluxo de entrada mais básico contém as seguintes etapas - cada uma delas é descrita em detalhes abaixo.

Documento de metadados do OpenID Connect

O OpenID Connect descreve um documento de metadados que contém a maioria das informações necessárias para que um aplicativo execute o login. Isso inclui informações como as URLs a serem usadas e o local das chaves de assinatura públicas do serviço. O documento de metadados do OpenID Connect pode ser encontrado em:

https://login.microsoftonline.com/{tenant}/.well-known/openid-configuration

Os metadados são um documento JSON (JavaScript Object Notation) simples. Veja o trecho a seguir para obter um exemplo. O conteúdo do trecho está totalmente descrito na especificação OpenID Connect. Observe que fornecer um ID de locatário em vez de common no lugar de {tenant} acima resultará em URIs específicos do locatário no objeto JSON retornado.

{
    "authorization_endpoint": "https://login.microsoftonline.com/{tenant}/oauth2/authorize",
    "token_endpoint": "https://login.microsoftonline.com/{tenant}/oauth2/token",
    "token_endpoint_auth_methods_supported":
    [
        "client_secret_post",
        "private_key_jwt",
        "client_secret_basic"
    ],
    "jwks_uri": "https://login.microsoftonline.com/common/discovery/keys"
    "userinfo_endpoint":"https://login.microsoftonline.com/{tenant}/openid/userinfo",
    ...
}

Se a sua aplicação tiver chaves de assinatura personalizadas como resultado do uso do recurso de mapeamento de declarações, deverá acrescentar um parâmetro de consulta appid contendo a ID da aplicação para obter uma jwks_uri apontando para as informações da chave de assinatura da aplicação. Por exemplo: https://login.microsoftonline.com/{tenant}/.well-known/openid-configuration?appid=6731de76-14a6-49ae-97bc-6eba6914391e contém uma jwks_uri de https://login.microsoftonline.com/{tenant}/discovery/keys?appid=6731de76-14a6-49ae-97bc-6eba6914391e.

Enviar o pedido de início de sessão

Quando a sua aplicação web precisa autenticar o utilizador, deve direcioná-lo para o endpoint /authorize. Esta solicitação é semelhante à primeira etapa do OAuth 2.0 Authorization Code Flow, com algumas distinções importantes:

• A solicitação deve incluir o escopo openid no parâmetro scope.
• O parâmetro response_type deve incluir id_token.
• A solicitação deve incluir o parâmetro nonce.

Assim, um pedido de exemplo ficaria assim:

// Line breaks for legibility only

GET https://login.microsoftonline.com/{tenant}/oauth2/authorize?
client_id=6731de76-14a6-49ae-97bc-6eba6914391e
&response_type=id_token
&redirect_uri=http%3A%2F%2Flocalhost%3a12345
&response_mode=form_post
&scope=openid
&state=12345
&nonce=7362CAEA-9CA5-4B43-9BA3-34D7C303EBA7

Neste ponto, o usuário é solicitado a inserir suas credenciais e concluir a autenticação.

Resposta da amostra

Uma resposta de exemplo, enviada para o redirect_uri especificado na solicitação de entrada após a autenticação do usuário, pode ter esta aparência:

POST / HTTP/1.1
Host: localhost:12345
Content-Type: application/x-www-form-urlencoded

id_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik1uQ19WWmNB...&state=12345

Resposta de erro

As respostas de erro também podem ser enviadas para o redirect_uri para que a aplicação possa lidar com elas adequadamente.

POST / HTTP/1.1
Host: localhost:12345
Content-Type: application/x-www-form-urlencoded

error=access_denied&error_description=the+user+canceled+the+authentication

Códigos de erro do endpoint de autorização

A tabela a seguir descreve os vários códigos de erro que podem ser retornados no error parâmetro da resposta de erro.

Valide o id_token

Apenas receber um id_token não é suficiente para autenticar o usuário; Você deve validar a assinatura e verificar as declarações no id_token de acordo com os requisitos do seu aplicativo. O ponto de extremidade do Azure AD usa JSON Web Tokens (JWTs) e criptografia de chave pública para assinar tokens e verificar se eles são válidos.

Você pode optar por validar o id_token no código do cliente, mas uma prática comum é enviar o id_token para um servidor back-end e executar a validação lá.

Você também pode querer validar declarações adicionais, dependendo do seu cenário. Algumas validações comuns incluem:

• Garantir que o usuário/organização se inscreveu no aplicativo.
• Garantir que o usuário tenha autorização/privilégios adequados usando as wids ou roles declarações.
• Garantir que ocorreu um determinado nível de segurança na autenticação, como a autenticação multifator.

Depois de validar o id_token, você pode iniciar uma sessão com o usuário e usar as declarações no id_token para obter informações sobre o usuário em seu aplicativo. Essas informações podem ser usadas para exibição, registros, personalização, etc. Para obter mais informações sobre id_tokens e reivindicações, leia AAD id_tokens.

Enviar uma solicitação de saída

Quando você deseja sair do aplicativo, não é suficiente limpar os cookies do aplicativo ou encerrar a sessão com o usuário. Você também deve redirecionar o utilizador para o end_session_endpoint para terminar sessão. Se não o conseguir fazer, o utilizador poderá efetuar nova autenticação na sua aplicação sem inserir as suas credenciais novamente, porque terá uma sessão de logon único válida com o ponto de extremidade do Azure AD.

Você pode simplesmente redirecionar o usuário para o end_session_endpoint listado no documento de metadados do OpenID Connect:

GET https://login.microsoftonline.com/common/oauth2/logout?
post_logout_redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F

Terminação única de sessão

Quando você redireciona o usuário para o end_session_endpoint, o Azure AD limpa a sessão do usuário do navegador. No entanto, o usuário ainda pode estar conectado a outros aplicativos que usam o Azure AD para autenticação. Para permitir que esses aplicativos terminem a sessão do utilizador simultaneamente, o Azure AD envia uma solicitação HTTP GET para a LogoutUrl registrada de todos os aplicativos nos quais o utilizador está atualmente conectado. Os aplicativos devem responder a essa solicitação limpando qualquer sessão que identifique o usuário e retornando uma resposta 200. Se você deseja oferecer suporte ao logon único em seu aplicativo, você deve implementar esse LogoutUrl no código do seu aplicativo. Você pode definir o LogoutUrl no portal do Azure:

1. Inicie sessão no portal Azure.
2. Escolha o seu Ative Directory clicando na sua conta no canto superior direito da página.
3. No painel de navegação à esquerda, escolha Azure Active Directory, depois escolha Registros de Aplicativos e selecione a sua aplicação.
4. Clique em Configurações, em seguida, em Propriedades e encontre a caixa de texto URL de Logout.

Aquisição de Tokens

Muitos aplicativos Web precisam não apenas fazer login no usuário, mas também acessar um serviço Web em nome desse usuário usando OAuth. Este cenário combina o OpenID Connect para autenticação do usuário, enquanto simultaneamente adquire um authorization_code que pode ser usado para obter access_tokens usando o fluxo de código de autorização OAuth .

Obter tokens de acesso

Para adquirir tokens de acesso, precisas modificar a solicitação de início de sessão acima.

// Line breaks for legibility only

GET https://login.microsoftonline.com/{tenant}/oauth2/authorize?
client_id=6731de76-14a6-49ae-97bc-6eba6914391e        // Your registered Application ID
&response_type=id_token+code
&redirect_uri=http%3A%2F%2Flocalhost%3a12345          // Your registered Redirect Uri, url encoded
&response_mode=form_post                              // `form_post' or 'fragment'
&scope=openid
&resource=https%3A%2F%2Fservice.contoso.com%2F        // The identifier of the protected resource (web API) that your application needs access to
&state=12345                                          // Any value, provided by your app
&nonce=678910                                         // Any value, provided by your app

Ao incluir escopos de permissão na solicitação e usar response_type=code+id_token, o endpoint authorize garante que o utilizador consentiu com as permissões indicadas no parâmetro de consulta scope e retorna à sua aplicação um código de autorização para trocar por um token de acesso.

Resposta com êxito

Uma resposta bem-sucedida, enviada para o redirect_uri usando response_mode=form_post, tem a seguinte aparência:

POST /myapp/ HTTP/1.1
Host: localhost
Content-Type: application/x-www-form-urlencoded

id_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik1uQ19WWmNB...&code=AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrq...&state=12345

Resposta de erro

As respostas de erro também podem ser enviadas para o redirect_uri para que a aplicação possa lidar com elas adequadamente.

POST /myapp/ HTTP/1.1
Host: localhost
Content-Type: application/x-www-form-urlencoded

error=access_denied&error_description=the+user+canceled+the+authentication

Para obter uma descrição dos possíveis códigos de erro e sua ação recomendada do cliente, consulte Códigos de erro para erros de ponto de extremidade de autorização.

Depois de obter uma code de autorização e um id_token, você pode autenticar o utilizador e obter tokens de acesso, em nome dele. Para iniciar sessão do utilizador, tem de validar o id_token exatamente como descrito acima. Para obter tokens de acesso, você pode seguir as etapas descritas na seção "Usar o código de autorização para solicitar um token de acesso" de nossa documentação de fluxo de código OAuth .

Próximos passos

• Saiba mais sobre os tokens de acesso .
• Saiba mais sobre os eid_token e as reclamações.