Connect to Microsoft Entra ID with WS-Federation

Use FoxIDs as a WS-Federation Security Token Service (STS) for a federated Microsoft Entra ID domain and federated Windows sign-in.

FoxIDs can be used as the federated identity provider for Microsoft Entra joined and Microsoft Entra hybrid joined Windows devices.

In a federated environment, Microsoft Entra ID requires WS-Federation and WS-Trust support for Windows sign-in. FoxIDs exposes the MEX endpoint and active WS-Trust UsernameMixed endpoint required by these Microsoft Entra ID and Windows flows. FoxIDs does not join or register devices; device registration is handled by Microsoft Entra ID and Windows.

Organisations using AD FS for Microsoft Entra ID domain federation can use FoxIDs for the federated identity provider role described in this guide.

Configure FoxIDs

This guide describes how to configure FoxIDs as the STS for a federated Microsoft Entra ID domain. Users are connected to Microsoft Entra ID users with their Immutable ID.

1 - Create a WS-Federation application in FoxIDs Control Client

  1. Select the Applications tab.
  2. Click New application.
  3. Click Show all options.
  4. Click Web Application with the WS-Federation badge.
  5. Add the Name, e.g. Microsoft Entra ID.
  6. Choose manual configuration.
  7. Set Application realm to urn:federation:MicrosoftOnline.
  8. Set Reply URL to https://login.microsoftonline.com/login.srf.
  9. Set Sign-out URL to https://login.microsoftonline.com/login.srf.
  10. Keep Token type as SAML 1.1 unless Microsoft Entra ID is configured for another token type.
  11. Click Create.
  12. Open the application and enable Microsoft Entra ID Windows sign-in under the advanced WS-Federation settings.

2 - Configure the 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.

  1. Click Change application to open the application in edit mode.
  2. Select the Claim Transforms tab.
  3. Click Add claim transform and click Map.
  4. Set New claim to http://schemas.microsoft.com/LiveID/Federation/2008/05/ImmutableID.
  5. Set Select claim to http://schemas.foxids.com/ws/identity/claims/immutableid.
  6. Click Update.

If Microsoft Entra ID requires a UPN claim in your configuration, issue:

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

from the user's UPN claim.

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.

3 - Copy the WS-Federation values from FoxIDs

Open the WS-Federation application registration and copy the values needed for Microsoft Entra ID domain federation:

  • Realm / issuer
  • Passive sign-in URL
  • Sign-out URL
  • MEX endpoint
  • Active WS-Trust endpoint

For federated Windows sign-in, use the MEX endpoint as metadataExchangeUri and the active WS-Trust endpoint as activeSignInUri. When automatic Microsoft Entra ID sync is enabled, FoxIDs keeps the Microsoft Entra ID domain federation signing certificates updated.

Configure automatic Microsoft Entra ID sync for self-hosting

For self-hosted FoxIDs deployments, automatic Microsoft Entra ID federation sync requires a Microsoft Entra ID app registration. FoxIDs uses the app registration with the client credentials flow to call Microsoft Graph and create or update the domain federationConfiguration.

The app registration must be created in Microsoft Entra ID and granted application permission to manage internal domain federation.

  1. Open the Microsoft Entra admin centre.

  2. In the left menu, expand Entra ID and select App registrations.

  3. Click New registration.

  4. Enter a name, for example FoxIDs federation sync.

  5. Select the supported account type:

    • Single tenant only for a self-hosted FoxIDs deployment that only synchronises domains in the same Microsoft Entra tenant.
    • Multiple Entra ID tenants if the same FoxIDs deployment and sync app registration must synchronise domains in more than one Microsoft Entra tenant.

  6. Click Register.

  7. Copy the Application (client) ID.

  8. Go to Certificates & secrets.

  9. Create a new client secret and copy the secret value.

  10. Go to API permissions.

  11. Add Microsoft Graph Application permissions:

    • Domain-InternalFederation.ReadWrite.All

Request Microsoft Graph application permission for internal federation configuration

Configure the FoxIDs deployment with:

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

In environment variable form:

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

Add the same values to both the FoxIDs runtime configuration and the FoxIDs Control configuration if they are hosted as separate applications. The runtime uses the configuration when automatic sync is triggered during WS-Federation sign-in, and FoxIDs Control uses it when an administrator starts sync manually from the application registration.

After this configuration is deployed, the Microsoft Entra ID template in FoxIDs Control shows automatic federation as available. Create one WS-Federation Microsoft Entra ID application registration per verified domain. A Microsoft Entra administrator grants admin consent from the template for the Microsoft Entra tenant whose domain is synchronised. Consent is required once per Microsoft Entra tenant, not once per domain.

Configure Microsoft Entra ID

It is not possible to configure this type of Microsoft Entra ID domain federation in the Microsoft Entra ID admin centre. Use Microsoft Graph PowerShell or Microsoft Graph API.

The Microsoft Graph internalDomainFederation resource supports both SAML and WS-Federation. For WS-Federation, set preferredAuthenticationProtocol to wsFed. See Microsoft's Create internalDomainFederation documentation.

  1. Open PowerShell as administrator.

  2. Install the Microsoft Graph PowerShell module if not already installed:

    Install-Module -Name Microsoft.Graph

    Optionally install for current user:

    Install-Module Microsoft.Graph -Scope CurrentUser -Force

  3. Connect to Microsoft Graph:

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

  4. Set up the configuration variables:

    $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"

  5. Configure the domain federation:

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

New-MgDomainFederationConfiguration -DomainId $domainId -BodyParameter $params

    federatedIdpMfaBehavior can be set to:

    • acceptIfMfaDoneByFederatedIdp - Microsoft Entra ID accepts MFA from FoxIDs; if FoxIDs did not do MFA, Microsoft Entra ID can do it.
    • enforceMfaByFederatedIdp - If a policy needs MFA, Microsoft Entra ID sends the user back to FoxIDs to complete MFA.
    • rejectMfaByFederatedIdp - Microsoft Entra ID always does MFA itself; MFA at FoxIDs is ignored.

  6. Validate the configuration:

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

Microsoft Entra ID uses passiveSignInUri for web-based clients and activeSignInUri for active clients such as Microsoft Entra joined and Microsoft Entra hybrid joined Windows devices. See Microsoft's internalDomainFederation resource documentation for the full property list.

Configure the user's Immutable ID

The user's onPremisesImmutableId in Microsoft Entra ID must match the http://schemas.microsoft.com/LiveID/Federation/2008/05/ImmutableID claim issued by FoxIDs.

Microsoft describes the AD FS Immutable ID claim in the AD FS management and customisation documentation.

Configure the user's Immutable ID with PowerShell

  1. Connect to Microsoft Graph: 
    Connect-MgGraph -Scopes "User.ReadWrite.All"
  2. Set up the variables: 
    $userId = "user-id@your-domain.com"
$immutableId = "immutable-id"
  3. Configure the user's Immutable ID: 
    Update-MgUser -UserId $userId -OnPremisesImmutableId $immutableId
  4. Validate the value: 
    Get-MgUser -UserId $userId | Format-List Id, UserPrincipalName, OnPremisesImmutableId

If the user already has an Immutable ID set, you may need to move the user away from the federated domain, update the Immutable ID, and then move the user back to the federated domain.

Your Privacy

Your Privacy

We use cookies to make your experience of our websites better. Click the 'Accept all cookies' button to agree to the use of cookies. To opt out of non-essential cookies, click 'Necessary cookies only'.

Visit our Privacy Policy page for more