Partilhar via

Autorizar o acesso a aplicações Web com o OpenID Connect e o Azure Active Directory

  • Artigo

Aviso

Este conteúdo destina-se ao ponto final Azure AD v1.0 mais antigo. Utilize o plataforma de identidades da Microsoft para novos projetos.

O OpenID Connect é uma camada de identidade simples criada sobre o protocolo OAuth 2.0. O OAuth 2.0 define mecanismos para obter e utilizar tokens de acesso para aceder a 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. Fornece informações sobre o utilizador final sob a forma de um id_token que verifica a identidade do utilizador e fornece informações básicas sobre o perfil do utilizador.

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

Registar a aplicação com o inquilino do AD

Primeiro, registe a aplicação no inquilino do Azure Active Directory (Azure AD). Esta ação dar-lhe-á um ID de Aplicação para a aplicação e ativá-lo-á para receber tokens.

  1. Inicie sessão no portal do Azure.

  2. Selecione o seu inquilino Azure AD ao selecionar a sua conta no canto superior direito da página, seguido de selecionar a navegação Mudar de Diretório e, em seguida, selecionar o inquilino adequado.

    • Ignore este passo se tiver apenas um inquilino Azure AD na sua conta ou se já tiver selecionado o inquilino Azure AD adequado.

  3. Na portal do Azure, procure e selecione Azure Active Directory.

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

  5. Siga as instruções e crie uma nova aplicação. Não importa se é uma aplicação Web ou uma aplicação de cliente público (mobile & desktop) para este tutorial, mas se quiser exemplos específicos para aplicações Web ou aplicações cliente públicas, consulte os nossos inícios rápidos.

    • Nome é o nome da aplicação e descreve a sua aplicação aos utilizadores finais.
    • Em Tipos de conta suportados, selecione Contas em qualquer diretório organizacional e contas Microsoft pessoais.
    • Indique 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 o cliente público (móvel & ambiente de trabalho), o Azure AD utiliza-o para devolver respostas de tokens. Introduza um valor específico na aplicação. Por exemplo, http://MyFirstAADApp.

  6. Depois de concluir o registo, Azure AD atribuirá à sua aplicação um identificador de cliente exclusivo (o ID da Aplicação). Precisa deste valor nas secções seguintes, por isso, copie-o a partir da página da aplicação.

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

Fluxo de autenticação com o OpenID Connect

O fluxo de início de sessão mais básico contém os seguintes passos. Cada um deles é descrito em detalhe abaixo.

Fluxo de Autenticação do 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 uma aplicação efetuar o início de sessão. 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. Veja o fragmento seguinte para obter um exemplo. Os conteúdos do fragmento estão totalmente descritos na especificação do OpenID Connect. Tenha em atenção que fornecer um ID de inquilino em vez common de {tenant} acima resultará em URIs específicos do inquilino no objeto JSON devolvido.

{
    "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 da utilização da funcionalidade de mapeamento de afirmações , tem de acrescentar um appid parâmetro de consulta que contenha o ID da aplicação para obter um jwks_uri apontamento para as informações da chave de assinatura da sua aplicação. Por exemplo: https://login.microsoftonline.com/{tenant}/.well-known/openid-configuration?appid=6731de76-14a6-49ae-97bc-6eba6914391e contém um 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 precisar de autenticar o utilizador, tem de direcionar o utilizador para o /authorize ponto final. Este pedido é semelhante à primeira etapa do Fluxo de Código de Autorização OAuth 2.0, com algumas distinções importantes:

  • O pedido tem de incluir o âmbito openid no scope parâmetro .
  • O response_type parâmetro tem de incluir id_token.
  • O pedido tem de incluir o nonce parâmetro .

Assim, um pedido de exemplo teria o seguinte aspeto:

// 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 Description
inquilino obrigatório O {tenant} valor no caminho do pedido pode ser utilizado para controlar quem pode iniciar sessão na aplicação. Os valores permitidos são identificadores de inquilino, por exemplo, 8eaef023-2b34-4da1-9baa-8bc8c9d6a490 ou contoso.onmicrosoft.comcommon para tokens independentes de inquilinos
client_id obrigatório O ID da Aplicação atribuído à sua aplicação quando a registou com Azure AD. Pode encontrá-lo no portal do Azure. Clique em Azure Active Directory, clique em Registos de Aplicações, escolha a aplicação e localize o ID da Aplicação na página da aplicação.
response_type obrigatório Tem de incluir id_token para o início de sessão do OpenID Connect. Também pode incluir outros response_types, como code ou token.
scope recomendado A especificação do OpenID Connect requer o âmbito openid, que se traduz na permissão "Iniciar sessão" na IU de consentimento. Este e outros âmbitos OIDC são ignorados no ponto final v1.0, mas continua a ser uma melhor prática para clientes em conformidade com normas.
nonce obrigatório Um valor incluído no pedido, gerado pela aplicação, que está incluído no resultado id_token como uma afirmação. Em seguida, a aplicação pode verificar este valor para mitigar os ataques de repetição de tokens. Normalmente, o valor é uma cadeia aleatória, exclusiva ou GUID que pode ser utilizada para identificar a origem do pedido.
redirect_uri recomendado A redirect_uri da sua aplicação, onde as respostas de autenticação podem ser enviadas e recebidas pela sua aplicação. Tem de corresponder exatamente a uma das redirect_uris que registou no portal, exceto que tem de estar codificada com URL. Se estiver em falta, o agente de utilizador será enviado de volta para um dos URIs de redirecionamento registados para a aplicação, aleatoriamente. O comprimento máximo é de 255 bytes
response_mode opcional Especifica o método que deve ser utilizado para enviar os authorization_code resultantes de volta para a sua aplicação. Os valores suportados destinam-se form_post à mensagem de formulário HTTP e fragment ao fragmento de URL. Para aplicações Web, recomendamos que utilize response_mode=form_post para garantir a transferência mais segura de tokens para a sua aplicação. A predefinição para qualquer fluxo, incluindo uma id_token é fragment.
state recomendado Um valor incluído no pedido que é devolvido na resposta do token. Pode ser uma cadeia de qualquer conteúdo que pretenda. Normalmente, é utilizado um valor exclusivo gerado aleatoriamente para impedir ataques de falsificação de pedidos entre sites. O estado também é utilizado para codificar informações sobre o estado do utilizador na aplicação antes do pedido de autenticação ocorrer, como a página ou vista em que se encontravam.
pedido de aviso opcional Indica o tipo de interação do utilizador que é necessário. Atualmente, os únicos valores válidos são "login", "none" e "consent". prompt=login força o utilizador a introduzir as respetivas credenciais nesse pedido, anulando o início de sessão único. prompt=none é o oposto – garante que o utilizador não é apresentado com qualquer pedido interativo. Se não for possível concluir o pedido automaticamente através do início de sessão único, o ponto final devolve um erro. prompt=consent aciona a caixa de diálogo consentimento do OAuth após o utilizador iniciar sessão, pedindo ao utilizador que conceda permissões à aplicação.
login_hint opcional Pode ser utilizado para pré-preencher o campo nome de utilizador/endereço de e-mail da página de início de sessão do utilizador, se souber o nome de utilizador com antecedência. Muitas vezes, as aplicações utilizam este parâmetro durante a reautenção, tendo já extraído o nome de utilizador de um início de sessão anterior com a preferred_username afirmação.

Neste momento, é pedido ao utilizador que introduza as credenciais e conclua a autenticação.

Resposta de amostra

Uma resposta de exemplo, enviada para o redirect_uri especificado no pedido de início de sessão após a autenticação do utilizador, pode ter o seguinte aspeto:

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

id_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik1uQ19WWmNB...&state=12345
Parâmetro Description
id_token O id_token que a aplicação pediu. Pode utilizar o id_token para verificar a identidade do utilizador e iniciar uma sessão com o utilizador.
state Um valor incluído no pedido que também é devolvido 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 é utilizado para codificar informações sobre o estado do utilizador na aplicação antes do pedido de autenticação ter ocorrido, como a página ou vista em que se encontravam.

Resposta a erros

As respostas de erro também podem ser enviadas para a aplicação redirect_uri para que a aplicação possa processá-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 código de erro que pode ser utilizada para classificar tipos de erros que ocorrem e pode ser utilizada para reagir a erros.
error_description Uma mensagem de erro específica que pode ajudar um programador a identificar a causa raiz de um erro de autenticação.

Códigos de erro para erros de ponto final de autorização

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

Código de Erro Description Ação do Cliente
invalid_request Erro de protocolo, como um parâmetro necessário em falta. Corrija e volte a submeter o pedido. Trata-se de um erro de desenvolvimento e é normalmente apanhado durante os testes iniciais.
unauthorized_client A aplicação cliente não está autorizada a pedir um código de autorização. Normalmente, isto ocorre quando a aplicação cliente não está registada no Azure AD ou não é adicionada ao inquilino Azure AD do utilizador. A aplicação pode pedir ao utilizador instruções para instalar a aplicação e adicioná-la ao Azure AD.
access_denied O proprietário do recurso negou o consentimento A aplicação cliente pode notificar o utilizador de que não pode continuar, a menos que o utilizador consenta.
unsupported_response_type O servidor de autorização não suporta o tipo de resposta no pedido. Corrija e volte a submeter o pedido. Trata-se de um erro de desenvolvimento e é normalmente apanhado durante os testes iniciais.
server_error O servidor encontrou um erro inesperado. Repita o pedido. Estes erros podem resultar de condições temporárias. A aplicação cliente pode explicar ao utilizador que a resposta está atrasada devido a um erro temporário.
temporarily_unavailable O servidor está temporariamente demasiado ocupado para processar o pedido. Repita o pedido. A aplicação cliente pode explicar ao utilizador que a resposta está atrasada devido a uma condição temporária.
invalid_resource O recurso de destino é inválido porque não existe, Azure AD não consegue encontrá-lo ou não está configurado corretamente. Isto indica que o recurso, se existir, não foi configurado no inquilino. A aplicação pode pedir ao utilizador instruções para instalar a aplicação e adicioná-la ao Azure AD.

Validar o id_token

Apenas receber um id_token não é suficiente para autenticar o utilizador; tem de validar a assinatura e verificar as afirmações nos id_token requisitos da sua aplicação. O ponto final Azure AD utiliza Os Tokens Web JSON (JWTs) e a criptografia de chaves públicas para assinar tokens e verificar se são válidos.

Pode optar por validar o no código de id_token cliente, mas uma prática comum é enviar o id_token para um servidor de back-end e efetuar a validação aí.

Também pode querer validar afirmações adicionais consoante o seu cenário. Algumas validações comuns incluem:

  • Garantir que o utilizador/organização se inscreveu na aplicação.
  • Garantir que o utilizador tem autorização/privilégios adequados com as wids afirmações ou roles .
  • A garantia de uma determinada força de autenticação ocorreu, como a autenticação multifator.

Depois de validar o id_token, pode iniciar uma sessão com o utilizador e utilizar as afirmações no id_token para obter informações sobre o utilizador na sua aplicação. Estas informações podem ser utilizadas para apresentação, registos, personalização, etc. Para obter mais informações sobre id_tokens afirmações e afirmações, leia id_tokens do AAD.

Enviar um pedido de início de sessão

Quando pretender terminar a sessão do utilizador na aplicação, não é suficiente limpar os cookies da sua aplicação ou terminar a sessão com o utilizador. Também tem de redirecionar o utilizador para o para terminar end_session_endpoint sessão. Se não conseguir fazê-lo, o utilizador poderá reautilizar novamente à sua aplicação sem introduzir as respetivas credenciais novamente, uma vez que terá uma sessão de início de sessão único válida com o ponto final Azure AD.

Pode simplesmente redirecionar o utilizador 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 Description
post_logout_redirect_uri recomendado O URL para o qual o utilizador deve ser redirecionado após terminar sessão com êxito. Este URL tem de corresponder a um dos URIs de redirecionamento registados para a sua aplicação no portal de registo de aplicações. Se post_logout_redirect_uri não estiver incluída, é apresentada uma mensagem genérica ao utilizador.

Fim de sessão único

Quando redireciona o utilizador para o end_session_endpoint, Azure AD limpa a sessão do utilizador a partir do browser. No entanto, o utilizador ainda pode ter sessão iniciada noutras aplicações que utilizam Azure AD para autenticação. Para permitir que essas aplicações terminem sessão do utilizador em simultâneo, Azure AD envia um pedido HTTP GET para o registo LogoutUrl de todas as aplicações nas quais o utilizador tem sessão iniciada atualmente. As aplicações têm de responder a este pedido desmarcando qualquer sessão que identifique o utilizador e devolvendo uma 200 resposta. Se quiser suportar o fim de sessão único na sua aplicação, tem de implementar tal LogoutUrl no código da sua aplicação. Pode definir a LogoutUrl partir do portal do Azure:

  1. Inicie sessão no portal do Azure.
  2. Selecione o Seu Active Directory clicando na sua conta no canto superior direito da página.
  3. No painel de navegação esquerdo, selecione Azure Active Directory e, em seguida, selecione Registos de aplicações e selecione a sua aplicação.
  4. Clique em Definições e, em seguida, em Propriedades e localize a caixa de texto URL de Fim de Sessão.

Aquisição de Tokens

Muitas aplicações Web precisam não só de iniciar sessão do utilizador, mas também de aceder a um serviço Web em nome desse utilizador através do OAuth. Este cenário combina o OpenID Connect para autenticação de utilizadores ao adquirir simultaneamente um authorization_code que pode ser utilizado para utilizar access_tokens o Fluxo de Código de Autorização OAuth.

Obter Tokens de Acesso

Para adquirir tokens de acesso, tem de modificar o pedido 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 âmbitos de permissão no pedido e ao utilizar response_type=code+id_tokeno , o authorize ponto final garante que o utilizador consentiu com as permissões indicadas no scope parâmetro de consulta e devolve à sua aplicação um código de autorização para trocar por um token de acesso.

Resposta bem-sucedida

Uma resposta bem-sucedida, enviada para o redirect_uri com response_mode=form_post, tem o seguinte aspeto:

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

id_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik1uQ19WWmNB...&code=AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrq...&state=12345
Parâmetro Description
id_token O id_token que a aplicação pediu. Pode utilizar o id_token para verificar a identidade do utilizador e iniciar uma sessão com o utilizador.
code A authorization_code que a aplicação pediu. A aplicação pode utilizar o código de autorização para pedir um token de acesso para o recurso de destino. Authorization_codes são de curta duração e normalmente expiram após cerca de 10 minutos.
state 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 a erros

As respostas de erro também podem ser enviadas para o redirect_uri para que a aplicação possa processá-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 código de erro que pode ser utilizada para classificar tipos de erros que ocorrem e pode ser utilizada para reagir a erros.
error_description Uma mensagem de erro específica que pode ajudar um programador a identificar a causa raiz de um erro de autenticação.

Para obter uma descrição dos possíveis códigos de erro e da ação de cliente recomendada, veja Códigos de erro para erros de pontos finais de autorização.

Depois de obter uma autorização code e um id_token, pode iniciar sessão do utilizador e obter tokens de acesso em nome deles. Para iniciar sessão do utilizador, tem de validar exatamente como id_token descrito acima. Para obter tokens de acesso, pode seguir os passos descritos na secção "Utilizar o código de autorização para pedir um token de acesso" da nossa documentação do fluxo de código OAuth.

Passos seguintes