Conceitos de OpenID Connect/OAuth com o AD FS

Artigo
06/09/2023
Aplica-se a:

✅ Windows Server 2025, ✅ Windows Server 2022, ✅ Windows Server 2019, ✅ Windows Server 2016

Aplica-se ao AD FS (Serviços de Federação do Active Directory ) 2016 e versões posteriores

Atores de autenticação moderna

Ator	Descrição
Usuário final	A entidade de segurança (usuários, aplicativos, serviços e grupos) que acessa o recurso.
Cliente	Seu aplicativo Web, identificado pela ID de cliente dele. Geralmente, o cliente é a parte com a qual o usuário final interage, e que solicita os tokens do servidor de autorização.
Servidor de autorização/IdP (Provedor de Identidade)	Seu servidor do AD FS. Ele é responsável por verificar a identidade das entidades de segurança que existem no diretório de uma organização. Ele emite tokens de segurança (token de acesso do portador, token de ID e token de atualização) após a autenticação bem-sucedida dessas entidades de segurança.
Servidor de recursos/Provedor de recursos/Terceira parte confiável	Local em que o recurso ou os dados residem. Ele confia no servidor de autorização para autenticar e autorizar o cliente com segurança e usa tokens de acesso do portador para garantir que o acesso a um recurso possa ser concedido.

O seguinte diagrama fornece a relação mais básica entre os atores:

Tipos de aplicativos

Tipo de aplicativo	Descrição	Função
Aplicativo nativo	Às vezes chamado de cliente público. Destina-se a ser um aplicativo cliente executado em um PC ou em um dispositivo e com o qual o usuário interage.	Solicita tokens do servidor de autorização (AD FS) para acesso do usuário aos recursos. Envia solicitações HTTP para recursos protegidos, usando tokens como cabeçalhos HTTP.
Aplicativo servidor (aplicativo Web)	Um aplicativo Web que executa em um servidor e acessível aos usuários por meio de um navegador. Como ele pode manter a própria credencial ou segredo do cliente, às vezes é chamado de cliente confidencial.	Solicita tokens do servidor de autorização (AD FS) para acesso do usuário aos recursos. Antes de solicitar um token, o cliente (aplicativo Web) precisa se autenticar usando o segredo dele.
API Web	O recurso final que o usuário acessa. Pense nisso como a nova representação de terceiras partes confiáveis.	Consome tokens de acesso do portador obtidos pelos clientes.

Grupo de aplicativos

Você deve associar um grupo de aplicativos a cada cliente OAuth nativo ou aplicativo Web ou recurso de API Web configurado com o AD FS. Configure os clientes em um grupo de aplicativos para acessar os recursos do mesmo grupo. Um grupo de aplicativos pode conter vários clientes e recursos.

Tokens de segurança

A autenticação moderna usa os seguintes tipos de tokens:

id_token: um token JWT emitido pelo servidor de autorização (AD FS) e consumido pelo cliente. As declarações do token de ID contém informações sobre o usuário para que o cliente possa utilizar.
access_token: um token JWT emitido pelo servidor de autorização (AD FS) e destinado a ser consumido pelo recurso. A declaração de audiência ou "aud" desse token deve corresponder ao identificador do recurso ou à API Web.
refresh_token: emitido pelo AD FS para o cliente usar quando precisar atualizar id_token e access_token. O token é opaco para o cliente e só é consumido pelo AD FS.

Tempos de vida do token de atualização

Logon simples, sem KMSI, dispositivo não registrado: o AD FS aplica SsoLifetime e DeviceUsageWindowInDays. O primeiro token de atualização tem lifetime=DeviceUsageWindowInDays ou SsoLifetime, com base em qual campo é menor, mas nenhum outro token de atualização é emitido.
Logon KMSI, EnableKmsi=true na configuração do AD FS e kmsi=true passado como parâmetro: o AD FS aplica KmsiLifetimeMins com DeviceUsageWindowInDays. O primeiro token de atualização tem lifetime=DeviceUsageWindowInDays e cada solicitação grant_type=refresh_token subsequente obtém um novo token de atualização. Esse processo ocorre apenas com os clientes nativos ou os confidenciais, mais a autenticação do dispositivo.
Dispositivos registrados, autenticação de dispositivo: o AD FS usa PersistentSsoLifetimeMins e DeviceUsageWindowInDays semelhantes ao KMSI. Os clientes nativos e os confidenciais deverão obter novos tokens de atualização, com base na autenticação do dispositivo.

Para saber mais, confira Documentação de logon único do AD FS.

Escopos

Ao registrar um recurso no AD FS, você pode configurar escopos para permitir que o AD FS execute ações específicas. Além de configurar o escopo, você deve enviar o valor de escopo da solicitação para que o AD FS execute a ação. Por exemplo, um Administrador configura o escopo como openid durante o registro do recurso e o aplicativo (cliente) precisa enviar scope = openid na solicitação de autenticação ao AD FS para emitir o Token de ID. Confira os seguintes detalhes sobre os escopos disponíveis no AD FS:

aza – Se você usar extensões de protocolo OAuth 2.0 para clientes do agente e se o parâmetro de escopo contiver o escopo aza, o servidor emitirá um novo token de atualização primário. Ele define o token no campo refresh_token da resposta e define refresh_token_expires_in field com o tempo de vida do novo token de atualização primário se houver um imposto.
openid – Permite que o aplicativo solicite o uso do protocolo de autenticação de conexão openid.
logon_cert – Permite que um aplicativo solicite certificados de entrada, que você pode usar para fazer logon interativamente com usuários autenticados. O servidor do AD FS omite o parâmetro access_token da resposta e, em vez dele, fornece uma cadeia de certificados CMS codificada em base64 ou uma resposta de PKI completa de CMC. Para obter mais informações, confira MS-OAPX: extensões do protocolo OAuth 2.0.
user_impersonation – Solicita ao AD FS um token de acesso on-behalf-of. Para obter detalhes sobre como usar esse escopo, confira Criar um aplicativo de várias camadas usando o OBO (On-Behalf-Of) no OAuth com o AD FS 2016.
allatclaims – Permite que o aplicativo solicite que as declarações do token de acesso também sejam adicionadas ao token de ID.
vpn_cert – Permite que um aplicativo solicite certificados VPN, que estabelecem conexões VPN usando a autenticação EAP-TLS. Esse recurso não é mais compatível.
email – Permite que o aplicativo solicite uma declaração de email ao usuário conectado.
profile – Permite que o aplicativo solicite declarações relacionadas ao perfil ao usuário conectado.

Declarações

Os tokens de segurança (tokens de acesso e ID) emitidos pelo AD FS contêm declarações ou asserções de informações sobre a entidade que foi autenticada. Os aplicativos podem usar declarações para diversas tarefas, incluindo:

Validar o token
Identificar o locatário de diretório da entidade
Exibir informações do usuário
Determinar a autorização da entidade

As declarações presentes em qualquer token de segurança variam de acordo com o tipo de token, o tipo de credencial usada para autenticar o usuário e a configuração do aplicativo.

Fluxo de autenticação do AD FS de alto nível

Segue-se um diagrama do fluxo de alto nível.

O AD FS recebe uma solicitação de autenticação do cliente.
O AD FS valida a ID do cliente na solicitação de autenticação com a ID do cliente obtida durante o registro do cliente e do recurso no AD FS. Se estiver usando um cliente confidencial, o AD FS também validará o segredo do cliente fornecido na solicitação de autenticação. O AD FS também valida o URI de redirecionamento do Cliente.
O AD FS identifica o recurso que o cliente quer acessar por meio do parâmetro do recurso passado na solicitação de autenticação. Se você usar a biblioteca de clientes MSAL, o parâmetro do recurso não será enviado. Em vez disso, a URL do recurso será enviada como parte do parâmetro de escopo: escopo = [url do recurso]/[valores de escopo, por exemplo, openid].

Se o recurso não for passado usando os parâmetros de escopo ou recurso, o AD FS usará um recurso padrão urn:microsoft:userinfo cujas políticas (como MFA, emissão ou política de autorização) não podem ser configuradas.
Em seguida, o AD FS valida se o cliente tem as permissões para acessar o recurso. O AD FS também valida se os escopos passados como parâmetro na solicitação de autenticação correspondem aos escopos configurados ao registrar o recurso. Se o cliente não tiver as permissões ou se os escopos certos não forem enviados na solicitação de autenticação, o fluxo de autenticação será encerrado.
Depois que as permissões e os escopos são validados, o AD FS autentica o usuário por meio do método de autenticação configurado.
Se for necessário outro método de autenticação adicional de acordo com a política de recursos ou a política de autenticação global, o AD FS vai disparar a autenticação adicional.
O AD FS usa a Autenticação multifator do Microsoft Entra ou a Autenticação multifator de terceiros para fazer a autenticação.
Depois que o usuário é autenticado, o AD FS aplica as regras de declaração. As regras de declaração determinam as declarações enviadas ao recurso como parte dos tokens de segurança. O AD FS também aplica as políticas de controle de acesso que confirmam se o usuário atende às condições necessárias para acessar o recurso.
Em seguida, o AD FS gera o acesso e atualiza os Tokens. O AD FS também gera o token de ID.
O AD FS recebe a solicitação de autenticação.
Se você inclui scope = allatclaims na solicitação de autenticação, ele personaliza o Token de ID para incluir as declarações no token de acesso com base nas regras de declaração definidas.
Depois que os tokens necessários são gerados e personalizados, o AD FS responde ao cliente e inclui os tokens. A resposta do token de ID só será incluída na resposta se a solicitação de autenticação incluir scope = openid. O cliente sempre pode obter o token de ID após a autenticação usando o ponto de extremidade do token.

Tipos de bibliotecas

Use dois tipos de bibliotecas com o AD FS:

Bibliotecas de clientes: clientes nativos e aplicativos de servidor usam as bibliotecas de clientes para obter tokens de acesso para chamar um recurso como uma API Web. A MSAL (Biblioteca de Autenticação da Microsoft) é a biblioteca de clientes mais recente e recomendada ao usar o AD FS 2019.
Bibliotecas de middleware de servidor: os aplicativos Web usam bibliotecas de middleware de servidor para a entrada do usuário. As APIs Web usam bibliotecas de middleware de servidor para validar tokens enviados por clientes nativos ou por outros servidores. OWIN (Open Web Interface para .NET) é a biblioteca de middleware recomendada.

Personalizar token de ID (declarações adicionais no token de ID)

Em determinados cenários, é possível que o aplicativo Web cliente precise de declarações adicionais em um token de ID para ajudar na funcionalidade. Configure declarações adicionais em um token de ID usando uma das seguintes opções:

Opção 1: use esta opção quando tiver um cliente público e o aplicativo Web não tiver o recurso que está tentando acessar. Essa opção requer:

response_mode é definido como form_post
O identificador de terceira parte confiável (identificador de API Web) é o mesmo que o identificador do cliente

Diagram of AD FS customize token option one.

Opção 2: use esta opção quando o aplicativo Web tiver um recurso que está tentando acessar e precisar passar declarações adicionais por meio do token de ID. Você pode usar clientes públicos e clientes confidenciais. Essa opção requer:

response_mode é definido como form_post
KB4019472 está instalado nos servidores do AD FS
O escopo allatclaims é atribuído ao cliente – par do RP. Você pode atribuir o escopo usando Grant-ADFSApplicationPermission. Use Set-AdfsApplicationPermission se ele já tiver sido concedido uma vez. O cmdlet do PowerShell é indicado no seguinte exemplo:
```
Grant-AdfsApplicationPermission -ClientRoleIdentifier "https://my/privateclient" -ServerRoleIdentifier "https://rp/fedpassive" -ScopeNames "allatclaims","openid"
```

Diagram of AD FS customize token option two.

Para entender melhor como configurar um aplicativo Web no AD FS para obter um token de ID personalizado, confira Tokens de ID personalizados no AD FS 2016 ou versão posterior.

Logoff único

O logoff único encerra todas as sessões de cliente que usam a ID da sessão. O AD FS 2016 e posterior dá suporte a logoff único para OpenID Connect/OAuth. Para obter mais informações, consulte Logoff único para OpenID Connect com o AD FS.

Pontos de extremidade do AD FS

Ponto de extremidade do AD FS	Descrição
/authorize	O AD FS retorna um código de autorização que você pode usar para obter o token de acesso.
/token	O AD FS retorna um token de acesso que você pode usar para acessar o recurso, como na API Web.
/userinfo	O AD FS retorna a declaração da entidade.
/devicecode	O AD FS retorna o código do dispositivo e o código do usuário.
/logout	O AD FS desconecta o usuário.
/keys	Chaves públicas do AD FS utilizadas para assinar respostas.
/.well-known/openid-configuration	O AD FS retorna metadados do OAuth/OpenID Connect.

Compartilhar via