Conecte-se ao Microsoft Entra ID com WS-Federation

Use FoxIDs como um WS-Federation Security Token Service (STS) para um domínio federado do Microsoft Entra ID e login federado do Windows.

FoxIDs podem ser usados como o provedor de identidade federado para dispositivos Windows ingressados no Microsoft Entra e no Microsoft Entra híbrido.

Em um ambiente federado, o Microsoft Entra ID requer suporte WS-Federation e WS-Trust para entrada no Windows. FoxIDs expõe os metadados WS-Federation, o ponto final MEX e o ponto final WS-Trust UsernameMixed ativo exigidos por estes fluxos Microsoft Entra ID e Windows. FoxIDs não ingressa ou registra dispositivos; o registro do dispositivo é feito pelo Microsoft Entra ID e pelo Windows.

As organizações que usam o AD FS para a federação de domínio do Microsoft Entra ID podem usar FoxIDs para a função de provedor de identidade federado descrita neste guia.

Configurar FoxIDs

Este guia descreve como configurar FoxIDs como STS para um domínio federado do Microsoft Entra ID. Os usuários estão conectados aos usuários do Microsoft Entra ID com seu Immutable ID.

1 - Create the Microsoft Entra ID WS-Federation application in FoxIDs Control Client

The recommended setup is to use the Connect to Microsoft Entra ID application template. The template enables Microsoft Entra ID Windows sign-in, configures the WS-Federation metadata URL, adds the required issue claim and claim transforms, and uses an application-specific issuer.

  1. Select the Applications tab.
  2. Click Add application.
  3. Select Connect to Microsoft Entra ID with the WS-Federation badge.
  4. Add the display name, e.g. Microsoft Entra ID.
  5. Select Automatic federation (recommended).
  6. Add the verified Microsoft Entra domain to synchronise. Creating the Microsoft Entra ID template with Automatic federation and domain input
  7. Click Create.
  8. Click Set up Microsoft Entra federation.

If automatic federation is not available in a self-hosted deployment, configure the automatic Microsoft Entra ID sync app registration first or select Manual federation and configure Microsoft Entra ID manually.

2 - Grant consent and synchronise Microsoft Entra federation

Automatic federation uses Microsoft Graph to create or update the Microsoft Entra ID domain internalDomainFederation configuration. FoxIDs synchronises the WS-Federation endpoints, the MEX endpoint, the active WS-Trust endpoint, the primary signing certificate and the secondary signing certificate if one exists.

Microsoft Entra federation setup with Grant Microsoft admin consent and Synchronise federation

  1. In the Microsoft Entra ID template, click Grant Microsoft admin consent.
  2. Sign in as a Microsoft Entra administrator for the tenant that owns the domain and accept the consent.
  3. Return to FoxIDs Control.
  4. Click Synchronise federation.
  5. Verify that the synchronisation status is successful.

After the first successful synchronisation, Microsoft Entra ID trusts the FoxIDs WS-Federation application registration for the configured domain. FoxIDs also checks the federation during federated Windows sign-in and synchronises again if the signing certificate has changed or the previous synchronisation was not successful.

If synchronisation reports that the existing Microsoft Entra federation issuer does not match this FoxIDs application registration, review the domain ownership before choosing to take over the federation. Taking over changes the Microsoft Entra domain to trust this FoxIDs application registration.

3 - Configure the users' Immutable ID claims

Microsoft Entra ID expects an Immutable ID claim in the WS-Federation token. The claim value must match the user's onPremisesImmutableId in Microsoft Entra ID.

The Microsoft Entra ID template adds the required issue claims and claim transforms. You still need to make sure each user has an immutable_id claim with the base64 value that matches the user in Microsoft Entra ID.

Internal user with the immutable_id claim configured

Microsoft Entra ID documentation lists the UPN claim as part of the expected WS-Federation token claims. FoxIDs issues:

  • http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn

from the user's upn claim. User matching is normally based on the Immutable ID, but adding the UPN claim keeps the token aligned with Microsoft's expected WS-Federation claim set.

You need to set the user's Immutable ID as a claim in FoxIDs. To set the Immutable ID on an internal user, select the Users tab and then the Internal Users tab, find the user, and add a claim with the claim type immutable_id and the value of the Immutable ID in Microsoft Entra ID. It should be base64 encoded. The immutable_id claim type is mapped to the SAML claim URI http://schemas.foxids.com/ws/identity/claims/immutableid in FoxIDs. To issue the UPN claim for an internal user, add a claim with the claim type upn and the user's Microsoft Entra ID user principal name, e.g. user@your-domain.com. FoxIDs maps the internal upn claim to http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn. Manual FoxIDs configuration

Use manual configuration only if you do not use the Microsoft Entra ID template.

  1. Selecione a guia Aplicativos.
  2. Clique em Novo aplicativo.
  3. Clique em Mostrar todas as opções.
  4. Clique em Aplicativo Web com o selo WS-Federation.
  5. Adicione o Nome, por exemplo Microsoft Entra ID.
  6. Escolha a configuração manual.
  7. Configure Reino do aplicativo como urn:federation:MicrosoftOnline.
  8. Defina URL de resposta como https://login.microsoftonline.com/login.srf.
  9. Defina URL de saída como https://login.microsoftonline.com/login.srf.
  10. Mantenha Tipo de token como SAML 1.1, a menos que o Microsoft Entra ID esteja configurado para outro tipo de token.
  11. Clique em Criar.
  12. Abra o aplicativo e habilite o Login do Microsoft Entra ID do Windows nas configurações avançadas do WS-Federation.

Manual Immutable ID claim transform

O Microsoft Entra ID espera uma declaração de Immutable ID no token WS-Federation. O valor da declaração deve corresponder ao onPremisesImmutableId do usuário na Microsoft Entra ID.

  1. Clique em Alterar aplicativo para abrir o aplicativo no modo de edição.
  2. Selecione a guia Transformações de reivindicação.
  3. Clique em Adicionar transformação de declaração e clique em Mapa.
  4. Defina Nova declaração como http://schemas.microsoft.com/LiveID/Federation/2008/05/ImmutableID.
  5. Defina Selecionar reivindicação como http://schemas.foxids.com/ws/identity/claims/immutableid.
  6. Clique em Atualizar.

A documentação do Microsoft Entra ID lista a declaração UPN como parte do conjunto de declarações esperado do token WS-Federation. FoxIDs emite:

  • http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn

a partir da declaração upn do utilizador. A correspondência do utilizador baseia-se normalmente no Immutable ID, mas adicionar a declaração UPN mantém o token alinhado com o conjunto de declarações WS-Federation esperado pela Microsoft.

Você precisa definir o Immutable ID do usuário como uma declaração nos FoxIDs. Para definir a Immutable ID em um usuário interno, selecione a guia Usuários e, em seguida, a guia Usuários internos, encontre o usuário e adicione uma declaração com o tipo de declaração immutable_id e o valor da Immutable ID no Microsoft Entra ID. Deve ser codificado em base64. O tipo de declaração immutable_id é mapeado para o URI de declaração SAML http://schemas.foxids.com/ws/identity/claims/immutableid em FoxIDs. Para emitir a declaração UPN para um utilizador interno, adicione uma declaração com o tipo upn e o user principal name do Microsoft Entra ID do utilizador, por exemplo user@your-domain.com. O FoxIDs mapeia a declaração interna upn para http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn.

Manual Microsoft Entra ID federation values

Abra o registo da aplicação WS-Federation e copie os valores necessários para a federação de domínio Microsoft Entra ID:

  • Metadados da Federação
  • Reino / emissor
  • URL de login passivo
  • URL de saída
  • Ponto final MEX
  • Endpoint WS-Trust ativo

O Microsoft Entra ID lê os certificados de assinatura de FoxIDs da URL de metadados de federação. Portanto, você pode continuar usando os certificados FoxIDs contínuos padrão. Para login federado do Windows, use o terminal MEX como metadataExchangeUri e o terminal WS-Trust ativo como activeSignInUri.

Configure o Immutable ID do usuário

O onPremisesImmutableId do usuário no Microsoft Entra ID deve corresponder à declaração http://schemas.microsoft.com/LiveID/Federation/2008/05/ImmutableID emitida pelos FoxIDs.

A Microsoft descreve a declaração de Immutable ID do AD FS na documentação Gerenciamento e personalização do AD FS.

Configure o Immutable ID do usuário com PowerShell

  1. Conecte-se ao Microsoft Graph: 
    Connect-MgGraph -Scopes "User.ReadWrite.All"
  2. Configure as variáveis: 
    $userId = "user-id@your-domain.com"
$immutableId = "immutable-id"
  3. Configure o Immutable ID do usuário: 
    Update-MgUser -UserId $userId -OnPremisesImmutableId $immutableId
  4. Valide o valor: 
    Get-MgUser -UserId $userId | Format-List Id, UserPrincipalName, OnPremisesImmutableId

Se o usuário já tiver um Immutable ID definido, talvez seja necessário movê-lo para fora do domínio federado, atualizar o Immutable ID e, em seguida, mover o usuário de volta para o domínio federado.

Configurar Microsoft Entra ID

Não é possível configurar este tipo de federação de domínio Microsoft Entra ID no Centro de administração do Microsoft Entra ID. Use o Microsoft Graph PowerShell ou a API do Microsoft Graph.

O recurso internalDomainFederation do Microsoft Graph dá suporte a SAML e WS-Federation. Para WS-Federation, configure preferredAuthenticationProtocol como wsFed. Consulte a documentação Criar internalDomainFederation da Microsoft.

  1. Abra o PowerShell como administrador.

  2. Instale o módulo Microsoft Gráfico PowerShell se ainda não estiver instalado:

    Install-Module -Name Microsoft.Graph

    Opcionalmente, instale para o usuário atual:

    Install-Module Microsoft.Graph -Scope CurrentUser -Force

  3. Conecte-se ao Microsoft Graph:

    Connect-MgGraph -Scopes "Domain.ReadWrite.All,Directory.AccessAsUser.All"

  4. Configure as variáveis de configuração:

    $domainId = "your-domain.com"
$displayName = FoxIDs
$issuerUri = "copied Realm / issuer from FoxIDs"
$metadataExchangeUri = "copied MEX endpoint from FoxIDs"
$passiveSignInUri = "copied Passive sign-in URL from FoxIDs"
$activeSignInUri = "copied Active WS-Trust endpoint from FoxIDs"
$signOutUri = "copied Sign-out URL from FoxIDs"
$signingCertificate = "copied IdP signing certificate from FoxIDs"

  5. Configure a federação de domínio:

    $params = @{
  "@odata.type" = "#microsoft.graph.internalDomainFederation"
  displayName = $displayName
  issuerUri = $issuerUri
  metadataExchangeUri = $metadataExchangeUri
  passiveSignInUri = $passiveSignInUri
  activeSignInUri = $activeSignInUri
  preferredAuthenticationProtocol = "wsFed"
  signOutUri = $signOutUri
  federatedIdpMfaBehavior = "acceptIfMfaDoneByFederatedIdp"
}

New-MgDomainFederationConfiguration -DomainId $domainId -BodyParameter $params

    federatedIdpMfaBehavior pode ser definido como:

    • acceptIfMfaDoneByFederatedIdp - Microsoft Entra ID aceita MFA de FoxIDs; se os FoxIDs não fizeram MFA, o Microsoft Entra ID poderá fazê-lo.
    • enforceMfaByFederatedIdp – Se uma política precisar de MFA, o Microsoft Entra ID enviará o usuário de volta aos FoxIDs para concluir a MFA.
    • rejectMfaByFederatedIdp - O Microsoft Entra ID sempre faz o próprio MFA; A MFA em FoxIDs é ignorada.

  6. Valide a configuração:

    Get-MgDomainFederationConfiguration -DomainId $domainId | Format-List
Get-MgDomain -DomainId $domainId | Format-List Id, AuthenticationType

O Microsoft Entra ID usa passiveSignInUri para clientes baseados na Web e activeSignInUri para clientes ativos, como dispositivos Windows ingressados no Microsoft Entra e híbridos do Microsoft Entra. Consulte a documentação recurso internalDomainFederation da Microsoft para obter a lista completa de propriedades.

If you configure Microsoft Entra ID manually, update the Microsoft Entra ID signingCertificate and nextSigningCertificate values when FoxIDs signing certificates roll over. Automatic federation handles this for you.

Configurar a sincronização automática do Microsoft Entra ID para self-hosting

Para deployments FoxIDs self-hosted, a Microsoft Entra ID federation sync automática requer uma Microsoft Entra ID app registration configurada tanto na configuração do deployment FoxIDs runtime como na do FoxIDs Control. O FoxIDs usa a app registration com o client credentials flow para chamar o Microsoft Graph e criar ou atualizar a federationConfiguration do domínio.

A app registration deve ter a Microsoft Graph application permission Domain-InternalFederation.ReadWrite.All. Prefira certificate authentication carregando o certificado público na app registration e configurando o FoxIDs com o mesmo certificado incluindo a chave privada.

Request Microsoft Graph application permission for internal federation configuration

PFX é prático para sistemas de deployment que guardam secrets como valores de uma só linha. A password do PFX é opcional; omita CertificatePfxPassword se o PFX não estiver protegido por password:

{
  "Settings": {
    "Modules": {
      "MicrosoftEntraIdSync": {
        "ClientId": "<application-client-id>",
        "CertificatePfx": "<base64-encoded-pfx>",
        "CertificatePfxPassword": "<optional-pfx-password>"
      }
    }
  }
}

Como environment variables:

Settings__Modules__MicrosoftEntraIdSync__ClientId=<application-client-id>
Settings__Modules__MicrosoftEntraIdSync__CertificatePfx=<base64-encoded-pfx>
Settings__Modules__MicrosoftEntraIdSync__CertificatePfxPassword=<optional-pfx-password>

Para criar o valor PFX codificado em base64 a partir de um certificado PFX sem password:

$pfxPath = "C:\path\to\certificate.pfx"
$base64Pfx = [Convert]::ToBase64String([IO.File]::ReadAllBytes($pfxPath))
$base64Pfx | Set-Clipboard

Também pode ser usado certificado PEM e texto da private key:

{
  "Settings": {
    "Modules": {
      "MicrosoftEntraIdSync": {
        "ClientId": "<application-client-id>",
        "CertificatePemCrt": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----",
        "CertificatePemKey": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----"
      }
    }
  }
}

Se nenhum certificado estiver configurado, o FoxIDs usa client secret authentication:

{
  "Settings": {
    "Modules": {
      "MicrosoftEntraIdSync": {
        "ClientId": "<application-client-id>",
        "ClientSecret": "<client-secret>"
      }
    }
  }
}

Como environment variables:

Settings__Modules__MicrosoftEntraIdSync__ClientId=<application-client-id>
Settings__Modules__MicrosoftEntraIdSync__ClientSecret=<client-secret>

Se um certificado estiver configurado, o FoxIDs usa sempre certificate authentication e não volta para ClientSecret se certificate authentication falhar. Configure CertificatePfx ou ambos CertificatePemCrt e CertificatePemKey; não configure ao mesmo tempo definições de certificado PFX e PEM.

A sua privacidade

A sua privacidade

Usamos cookies para melhorar a sua experiência nos nossos sites. Clique no botão 'Aceitar todos os cookies' para concordar com a utilização de cookies. Para recusar cookies não essenciais, clique em 'Apenas cookies necessários'.

Visite a nossa página de Política de Privacidade para saber mais