Connect to Microsoft Entra ID with WS-Federation

Use FoxIDs as a WS-Federation Security Token Service (STS) for Microsoft Entra ID.

This is the preferred and recommended method when FoxIDs replaces AD FS for Microsoft Entra ID domain federation.

This configuration replaces AD FS while keeping Microsoft Entra ID domain federation in an AD FS-compatible WS-Federation mode. Microsoft Entra ID then treats FoxIDs as an AD FS-style federation service, which gives the Microsoft and Windows sign-in flows the compatibility they expect from WS-Federation.

Compared with the SAML 2.0 Microsoft Entra ID guide, the important difference is that this configuration uses preferredAuthenticationProtocol = "wsFed" in Microsoft Entra ID and FoxIDs issues a WS-Federation response with a SAML token.

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

Select the Applications tab.
Click New application.
Click Show all options.
Click Web Application with the WS-Federation badge.
Add the Name, e.g. Microsoft Entra ID.
Choose manual configuration.
Set Application realm to urn:federation:MicrosoftOnline.
Set Reply URL to https://login.microsoftonline.com/login.srf.
Set Sign-out URL to https://login.microsoftonline.com/login.srf.
Keep Token type as SAML 1.1 unless Microsoft Entra ID is configured for another token type.
Click Create.

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.

Click Change application to open the application in edit mode.
Select the Claim Transforms tab.
Click Add claim transform and click Map.
Set New claim to http://schemas.microsoft.com/LiveID/Federation/2008/05/ImmutableID.
Set Select claim to http://schemas.foxids.com/ws/identity/claims/immutableid.
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:

Federation Metadata
Realm / issuer
Passive sign-in URL
Sign-out URL

Microsoft Entra ID reads the FoxIDs signing certificates from the Federation Metadata URL. Therefore, you can keep using the default rolling FoxIDs certificates.

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.

Open PowerShell as administrator.
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
```

Connect to Microsoft Graph:

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

Set up the configuration variables:

$domainId = "your-domain.com"
$displayName = "FoxIDs"
$issuerUri = "copied Realm / issuer from FoxIDs"
$metadataUrl = "copied Federation Metadata URL from FoxIDs"
$passiveSignInUri = "copied Passive sign-in URL from FoxIDs"
$signOutUri = "copied Sign-out URL from FoxIDs"

Configure the domain federation:

$params = @{
  "@odata.type" = "#microsoft.graph.internalDomainFederation"
  displayName = $displayName
  issuerUri = $issuerUri
  metadataExchangeUri = $metadataUrl
  passiveSignInUri = $passiveSignInUri
  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.

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. If your tenant requires activeSignInUri, add it to $params with the endpoint required by your Microsoft client estate. 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

Connect to Microsoft Graph:

Connect-MgGraph -Scopes "User.ReadWrite.All"

Set up the variables:

$userId = "user-id@your-domain.com"
$immutableId = "immutable-id"

Configure the user's Immutable ID:

Update-MgUser -UserId $userId -OnPremisesImmutableId $immutableId

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.

Connect to Microsoft Entra ID with WS-Federation

Configure FoxIDs

Configure Microsoft Entra ID

Configure the user's Immutable ID

Related documentation

Twoja prywatność