Conceitos do AD FS OpenID Connect/OAuth

2025-04-30
Aplica-se a: ✅ Windows Server 2025, ✅ Windows Server 2022, ✅ Windows Server 2019, ✅ Windows Server 2016

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

Atores de autenticação modernos

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 do cliente. O cliente geralmente é a parte com a qual o usuário final interage e o cliente solicita tokens do servidor de autorização.
Servidor de autorização/provedor de identidade (IdP)	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	Onde 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 diagrama a seguir fornece a relação mais básica entre os atores:

Tipo de aplicativos

Tipo de aplicativo	Descrição	Função
Aplicativo nativo	Às vezes chamado de cliente público. Ele se destina a ser um aplicativo cliente que é executado em um computador ou 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 os tokens como cabeçalhos HTTP.
Aplicativo de servidor (aplicativo Web)	Um aplicativo Web que é executado em um servidor e é acessível aos usuários por meio de um navegador. Como ele é capaz de manter seu próprio segredo do cliente ou credencial, à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 seu segredo.
API Web	O recurso final que o usuário acessa. Pense nisso como a nova representação das partes dependentes.	Consome tokens de acesso do portador obtidos pelos clientes.

Grupo de aplicativos

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

Tokens de segurança

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

id_token: um token JWT emitido pelo servidor de autorização (AD FS) e consumido pelo cliente. As declarações no token de ID contêm informações sobre o usuário para que o cliente possa usá-lo.
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 que o cliente use quando precisar atualizar o id_token e o 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 subsequente grant_type=refresh_token obtém um novo token de atualização. Esse processo ocorre apenas com clientes nativos ou cliente confidencial mais autenticação de dispositivo.
Dispositivos registrados, autenticação de dispositivo: AD FS usa PersistentSsoLifetimeMins e DeviceUsageWindowInDays semelhantes ao KMSI. Os clientes nativos e confidenciais devem obter novos tokens de atualização, com base na autenticação do dispositivo.

Para saber mais, consulte a 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. Juntamente com a configuração do escopo, você deve enviar o valor de escopo na solicitação para que o AD FS execute a ação. Por exemplo, um administrador configura o escopo como openid durante o registro de recursos e o aplicativo (cliente) deve enviar scope = openid na solicitação de autenticação para que o AD FS emita o Token de ID. Veja a seguir os 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ária. Ele define o token no refresh_token campo da resposta e define o refresh_token_expires_in field tempo de vida do novo token de atualização primária se um for imposto.
openid - Permite que o aplicativo solicite o uso do openid protocolo de autenticação de conexão.
logon_cert - Permite que um aplicativo solicite certificados de entrada que você pode usar para fazer logon interativamente em usuários autenticados. O servidor do AD FS omite o access_token parâmetro da resposta e, em vez disso, fornece uma cadeia de certificados CMS codificada em base64 ou uma resposta PKI completa do CMC. Para obter mais informações, consulte MS-OAPX: extensões de 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, consulte Criar um aplicativo de várias camadas usando o OBO (On-Behalf-Of) usando OAuth com o AD FS 2016.
allatclaims – Permite que o aplicativo solicite que as declarações no 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 EAP-TLS autenticação. Esse recurso não tem mais suporte.
email - Permite que o aplicativo solicite uma declaração de email para o usuário conectado.
profile - Permite que o aplicativo solicite declarações relacionadas ao perfil para o usuário conectado.

Declarações

Os tokens de segurança (tokens de acesso e ID) emitidos pelo AD FS contêm declarações sobre o usuário autenticado. Os aplicativos podem usar declarações para várias tarefas, incluindo:

Validar o token
Identificar o inquilino do diretório do sujeito
Exibir informações do usuário
Determinar a autorização do sujeito

As declarações presentes em qualquer token de segurança são dependentes do tipo de token, do tipo de credencial usado para autenticar o usuário e da 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 a 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 de cliente e recurso no AD FS. Se estiver usando o cliente confidencial, o AD FS também valida 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 deseja acessar por meio do parâmetro de recurso passado na solicitação de autenticação. Se você usar a biblioteca de clientes MSAL, o parâmetro de recurso não será enviado. Em vez disso, a URL do recurso é enviada como parte do parâmetro de escopo: scope = [url de recurso]/[valores de escopo, por exemplo, openid].

Se o recurso não for passado usando os parâmetros de recurso ou escopo, o AD FS usará um recurso urn:microsoft:userinfo padrão cujas políticas, como MFA, emissão ou política de autorização, não poderão ser configuradas.
O Próximo AD FS valida se o cliente tem permissões para acessar o recurso. O AD FS também valida se os escopos passados na solicitação de autenticação correspondem aos escopos configurados ao registrar o recurso. Se o cliente não tiver as permissões ou 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 escopos são validados, o AD FS autentica o usuário usando o método de autenticação configurado.
Se outro método de autenticação for necessário de acordo com a política de recurso ou a política de autenticação global, o AD FS disparará a autenticação extra.
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 que 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ê incluir o scope = allatclaims na solicitação de autenticação, ele personalizará o token de ID para incluir afirmações no token de acesso com base nas regras de afirmaçã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 ID token após a autenticação usando o endpoint do token.

Tipos de bibliotecas

Use dois tipos de bibliotecas com o AD FS:

Bibliotecas de cliente: os clientes nativos e os aplicativos de servidor usam bibliotecas de cliente 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 quando você usa o AD FS 2019.
Bibliotecas de middleware do servidor: os aplicativos Web usam bibliotecas de middleware de servidor para entrada do usuário. As APIs Web usam bibliotecas de middleware de servidor para validar tokens enviados por clientes nativos ou por outros servidores. Open Web Interface for .NET (OWIN) é a biblioteca de middleware recomendada.

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

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

Opção 1: Use essa opção quando você tiver um cliente público e o aplicativo Web não tiver um recurso que ele esteja tentando acessar. Essa opção requer:

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

Diagrama da opção um do token de personalização do AD FS.

Opção 2: Use essa opção quando o aplicativo Web tiver um recurso que ele está tentando acessar e precisar passar declarações extras 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 em seus servidores do AD FS
O escopo allatclaims é atribuído ao cliente – par do RP. Você pode atribuir o escopo usando o Grant-ADFSApplicationPermission. Use Set-AdfsApplicationPermission se ele já tiver sido concedido uma vez. O cmdlet do PowerShell é indicado no exemplo a seguir:
```
Grant-AdfsApplicationPermission -ClientRoleIdentifier "https://my/privateclient" -ServerRoleIdentifier "https://rp/fedpassive" -ScopeNames "allatclaims","openid"
```

Diagrama da opção dois do token de personalização do AD FS.

Para entender melhor como configurar um aplicativo Web no AD FS para obter um token de ID personalizado, consulte tokens de ID personalizados no AD FS 2016 ou posterior.

Logon único

O logon único encerra todas as sessões de cliente que usam a ID da sessão. O AD FS 2016 e posterior dá suporte ao logon ú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
/autorizar	O AD FS retorna um código de autorização que você pode usar para obter o token de acesso.
/símbolo	O AD FS retorna um token de acesso que você pode usar para acessar o recurso, como na API Web.
/informações do usuário	O AD FS retorna a declaração da entidade.
/código do dispositivo	O AD FS retorna o código do dispositivo e o código do usuário.
/Logout	O AD FS desconecta o usuário.
/Chaves	Chaves públicas do AD FS usadas para assinar respostas.
/.well-known/openid-configuration	O AD FS retorna metadados do OAuth/OpenID Connect.

Compartilhar via