Compartilhar via

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

Aviso

Este conteúdo é destinado à versão mais antiga do Azure AD v1.0. Use a plataforma de identidade da Microsoft para obter novos projetos.

OpenID Connect é uma camada de identidade simples criada sobre o protocolo OAuth 2.0. O OAuth 2.0 define mecanismos para obter e usar tokens de acesso para acessar recursos protegidos, mas eles não definem métodos padrão para fornecer informações de identidade. O OpenID Connect implementa a autenticação como uma extensão para o 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.

O OpenID Connect será nossa recomendação se você estiver criando um aplicativo Web hospedado em um servidor e acessado por meio de um navegador.

Registre seu aplicativo com seu locatário do Azure Active Directory

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

  1. Entre no portal do Azure.

  2. Escolha sua locação do Azure AD selecionando sua conta no canto superior direito da página, depois selecione a navegação Switch Directory e, em seguida, selecione a locação apropriada.

    • 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, pesquise e selecione do Azure Active Directory.

  4. No menu esquerdo do Azure Active Directory, selecione Registro de Aplicativose, em seguida, selecione Novo registro.

  5. Siga os prompts e crie um novo aplicativo. Não importa se é um aplicativo Web ou um aplicativo de cliente público (mobile & desktop) para este tutorial, mas se você quiser exemplos específicos para aplicativos Web ou aplicativos cliente públicos, confira nossos inícios rápidos.

    • Name é o nome do aplicativo e descreve seu aplicativo para usuários finais.
    • Em Tipos de conta com suporte, selecione Contas em qualquer diretório organizacional e contas pessoais da Microsoft.
    • Forneça o URI de Redirecionamento . Para aplicativos Web, essa é a URL base do seu aplicativo em que os usuários podem entrar. Por exemplo, http://localhost:12345. Para cliente público (dispositivos móveis e desktops), o Azure AD utiliza para retornar respostas de token. Insira um valor específico ao seu aplicativo. Por exemplo, http://MyFirstAADApp.

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

  7. Para localizar seu aplicativo no portal do Azure, selecione registros de aplicativoe selecione Exibir todos os aplicativos.

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.

Fluxo de Autenticação OpenId Connect

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 um aplicativo realizar o login. Isto inclui informações como os URLs a utilizar e a localização 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. Consulte o snippet a seguir para obter um exemplo. O conteúdo do snippet é totalmente descrito na especificação OpenID Connect. Observe que fornecer uma ID de locatário em vez de common no lugar de {tenant} acima resultará em URIs específicas 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 o aplicativo tiver chaves de assinatura personalizadas como resultado do uso do recurso de mapeamento de declarações, você deverá acrescentar um parâmetro de consulta appid que contém a ID do aplicativo para obter uma jwks_uri apontando para as informações de chave de assinatura do aplicativo. 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 a solicitação de conexão

Quando seu aplicativo web precisa autenticar o usuário, ele deve direcionar o usuário para o endpoint /authorize. Essa solicitação é semelhante à primeira etapa do fluxo de código de autorização do OAuth 2.0, 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.

Portanto, uma solicitação de exemplo seria semelhante a esta:

// 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
Parâmetro Tipo Descrição
inquilino Necessário O valor de {tenant} no caminho da solicitação pode ser usado para controlar quem pode entrar no aplicativo. Os valores permitidos são identificadores de locatário, por exemplo, 8eaef023-2b34-4da1-9baa-8bc8c9d6a490 ou contoso.onmicrosoft.com ou common para tokens independentes de locatário
identificador_do_cliente Necessário A ID do aplicativo atribuída ao aplicativo quando você o registrou no Azure AD. Você pode encontrar isso no portal do Azure. Clique em Azure Active Directory, clique em Registros de Aplicativo, escolha o aplicativo e localize a ID da Aplicação na página do aplicativo.
tipo_de_resposta Necessário Deve incluir id_token para conexão do OpenID Connect. Também pode incluir outros response_types, como code ou token.
âmbito recomendado A especificação do OpenID Connect requer o escopo openid, que se traduz na permissão de login para a interface do usuário de consentimento. "Estes e outros escopos OIDC são ignorados no endpoint v1.0, mas ainda é uma prática recomendada para clientes compatíveis com padrões."
Nonce Necessário Um valor incluído na solicitação, gerado pelo aplicativo, que é incluído no id_token resultante como uma declaração. O aplicativo pode então verificar esse valor para prevenir ataques de reprodução de token. O valor normalmente é uma cadeia de caracteres aleatória, exclusiva ou GUID que pode ser usada para identificar a origem da solicitação.
URI de redirecionamento recomendado O redirect_uri do seu aplicativo, em que as respostas de autenticação podem ser enviadas e recebidas pelo aplicativo. Ele deve corresponder exatamente a uma das redirect_uris que você registrou no portal, exceto que ela deve ser codificada em URL. Se estiver ausente, o agente do usuário será enviado de volta para uma das URIs de redirecionamento registradas para o aplicativo, aleatoriamente. O comprimento máximo é de 255 bytes
modo_de_resposta opcional Especifica o método que deve ser usado para enviar o authorization_code resultante de volta ao seu aplicativo. Os valores com suporte são form_post para postagem de formulário HTTP e fragment para fragmento de URL. Para aplicativos Web, é recomendável usar response_mode=form_post para garantir a transferência mais segura de tokens para seu aplicativo. O padrão para qualquer fluxo, incluindo um id_token, é fragment.
estado recomendado Um valor incluído na solicitação retornada na resposta do token. Pode ser uma sequência de qualquer conteúdo que você desejar. Normalmente, é utilizado um valor exclusivo gerado aleatoriamente para impedir ataques de falsificação de pedidos entre sites. O estado também é usado para codificar informações sobre o estado do usuário no aplicativo antes que a solicitação de autenticação ocorra, como a página ou a exibição em que ele estava.
solicitação opcional Indica o tipo de interação do usuário que é necessário. Atualmente, os únicos valores válidos são 'login', 'none' e 'consent'. prompt=login força o usuário a inserir suas credenciais nessa solicitação, negando o logon único. prompt=none é o oposto– garante que o usuário não seja apresentado a nenhum prompt interativo. Se a solicitação não puder ser concluída automaticamente por meio da autenticação única, o ponto de extremidade retornará um erro. prompt=consent dispara a caixa de diálogo de consentimento OAuth depois que o usuário entra, solicitando que o usuário conceda permissões ao aplicativo.
login_hint opcional Pode ser usado para preencher previamente o campo nome de usuário/endereço de email da página de entrada do usuário, se você souber seu nome de usuário com antecedência. Geralmente, os aplicativos usam esse parâmetro durante a reautenticação, já tendo extraído o nome de usuário de uma sessão anterior usando o atributo de declaração preferred_username.

Nesse ponto, é solicitado que o usuário insira suas credenciais e conclua a autenticação.

Resposta de exemplo

Uma resposta de exemplo, enviada à redirect_uri especificada na solicitação de login após a autenticação do usuário, tem essa aparência:

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

id_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik1uQ19WWmNB...&state=12345
Parâmetro Descrição
id_token O id_token que o aplicativo solicitou. Você pode usar o id_token para verificar a identidade do usuário e iniciar uma sessão com o usuário.
estado Um valor incluído na solicitação que também retorna na resposta do token. Normalmente, é utilizado um valor exclusivo gerado aleatoriamente para impedir ataques de falsificação de pedidos entre sites. O estado também é usado para codificar informações sobre o estado do usuário no aplicativo antes que a solicitação de autenticação ocorra, como a página ou a exibição em que ele estava.

Resposta de erro

As respostas de erro também podem ser enviadas ao redirect_uri para que o aplicativo possa tratá-las 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
Parâmetro Descrição
erro Uma cadeia de caracteres de códigos de erro que pode ser usada para classificar tipos de erro que ocorrem e pode ser usada para responder aos erros.
descrição_do_erro Uma mensagem de erro específica que pode ajudar um desenvolvedor a identificar a causa raiz de um erro de autenticação.

Códigos de erro para erros de endpoint de autorização

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

Código de erro Descrição Ação do cliente
solicitação_inválida Erro de protocolo, como um parâmetro obrigatório ausente. Corrija e reenvie a solicitação. Esse é um erro de desenvolvimento e normalmente é capturado durante o teste inicial.
cliente_não_autorizado O aplicativo cliente não tem permissão para solicitar um código de autorização. Isso geralmente ocorre quando o aplicativo cliente não está registrado no Azure AD ou não é adicionado ao locatário do Azure AD do usuário. O aplicativo pode solicitar ao usuário instruções para instalar o aplicativo e adicioná-lo ao Azure AD.
acesso_negado Consentimento negado pelo proprietário do recurso O aplicativo cliente pode notificar o usuário de que ele não pode prosseguir, a menos que o usuário consenta.
tipo_de_resposta_não_suportado O servidor de autorização não dá suporte ao tipo de resposta na solicitação. Corrija e reenvie a solicitação. Esse é um erro de desenvolvimento e normalmente é capturado durante o teste inicial.
erro_do_servidor O servidor encontrou um erro inesperado. Tente novamente a solicitação. Esses erros podem resultar de condições temporárias. O aplicativo cliente pode explicar ao usuário que sua resposta está atrasada devido a um erro temporário.
temporariamente_indisponível O servidor está temporariamente muito ocupado para tratar da solicitação. Tente novamente a solicitação. O aplicativo cliente pode explicar ao usuário que sua resposta está atrasada devido a uma condição temporária.
recurso_inválido O recurso de destino é inválido porque ele não existe, o Azure AD não pode encontrá-lo ou não está configurado corretamente. Isso indica que o recurso, se ele existir, não foi configurado no locatário. O aplicativo pode solicitar ao usuário instruções para instalar o aplicativo e adicioná-lo ao Azure AD.

Validar 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 aplicativo. O ponto de extremidade do Azure AD usa JWTs (Tokens Web JSON) 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 de 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:

  • Garantindo que o usuário/organização tenha se inscrito no aplicativo.
  • Garantir que o usuário tenha autorização/privilégios adequados usando as declarações de wids ou roles.
  • Garantir que uma certa força de autenticação tenha ocorrido, como a autenticação multifator.

Depois de validar o id_token, você poderá 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 id_tokensdo AAD.

Enviar uma solicitação de saída

Quando você deseja desconectar o usuário 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 usuário para o end_session_endpoint para sair. Se você não fizer isso, o usuário poderá reautenticar no seu aplicativo sem inserir suas credenciais novamente, pois ele 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
Parâmetro Tipo Descrição
post_logout_redirect_uri recomendado A URL para a qual o usuário deve ser redirecionado após a saída bem-sucedida. Essa URL deve corresponder a uma das URIs de redirecionamento registradas para seu aplicativo no portal de registro do aplicativo. Se post_logout_redirect_uri não estiver incluído, o usuário verá uma mensagem genérica.

Logout único

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 desconectem o usuário simultaneamente, o Azure AD envia uma solicitação HTTP GET para o LogoutUrl registrado de todos os aplicativos aos quais o usuário está conectado no momento. Os aplicativos devem responder a essa solicitação limpando qualquer sessão que identifique o usuário e retornando uma resposta 200. Se você quiser dar suporte ao logon único em seu aplicativo, deverá implementar esse LogoutUrl no código do aplicativo. Você pode definir o LogoutUrl no portal do Azure:

  1. Entre no portal do Azure.
  2. Escolha seu Active Directory clicando em sua conta no canto superior direito da página.
  3. No painel de navegação esquerdo, escolha do Azure Active Directory, escolha registros de aplicativo e selecione seu aplicativo.
  4. Clique em Configurações, depois em Propriedades e encontre a caixa de texto URL de Logoff .

Aquisição de token

Muitos aplicativos Web precisam não apenas conectar o usuário, mas também acessar um serviço Web em nome desse usuário usando o OAuth. Esse cenário combina o OpenID Connect para autenticação de usuários a fim de adquirir simultaneamente um authorization_code que possa 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, você precisa modificar a solicitação de autenticação mencionada 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 ponto de extremidade authorize garante que o usuário tenha consentido com as permissões indicadas no parâmetro de consulta scope e retorna ao seu aplicativo um código de autorização para trocar por um token de acesso.

Resposta bem-sucedida

Uma resposta bem-sucedida, enviada ao 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
Parâmetro Descrição
token de identificação O id_token que o aplicativo solicitou. Você pode usar o id_token para verificar a identidade do usuário e iniciar uma sessão com o usuário.
código O código de autorização que o aplicativo solicitou. O aplicativo pode usar o código de autorização para solicitar um token de acesso ao recurso alvo. Authorization_codes são de curta duração e normalmente expiram após cerca de 10 minutos.
estado Se um parâmetro de estado estiver incluído no pedido, o mesmo valor deverá aparecer na resposta. A aplicação deve verificar se os valores de estado no pedido e na resposta são idênticos.

Resposta de erro

As respostas de erro também podem ser enviadas ao redirect_uri para que o aplicativo possa tratá-las 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
Parâmetro Descrição
erro Uma cadeia de caracteres de códigos de erro que pode ser usada para classificar tipos de erro que ocorrem e pode ser usada para responder aos erros.
descrição_do_erro Uma mensagem de erro específica que pode ajudar um desenvolvedor a identificar a causa raiz de um erro de autenticação.

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

Depois de obter uma autorização code e um id_token, você pode logar o usuário e obter tokens de acesso em nome dele. Para conectar o usuário, você deve validar o id_token exatamente conforme 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óximas etapas

  • Last updated on