Before you start
- Administrator access to Microsoft Entra ID, with the Global Administrator or Domain Administrator role.
- A domain for the users who sign in through SplitSecure: a custom domain you can verify in DNS, or a new subdomain of a federated domain your tenant already has. It cannot be a domain another identity provider already federates, nor the default
.onmicrosoft.comdomain. - The Microsoft Graph PowerShell module, on a Windows machine.
A SplitSecure identity provider, created in a threshold vault and approved by its Guardian Team. See Create an identity provider.
A second browser profile, signed in to the Web App, for the test sign-in. Start and finish the test in that same profile.
This guide makes a Microsoft Entra ID domain a connected app of your SplitSecure identity provider, so its users sign in only when your Guardian Team, the group of devices that together approve each proposal, approves it. You federate the domain with PowerShell, create a user in it, and register Entra ID in the Web App.
Values you exchange
| Value | Where to find it | Where to paste it |
|---|---|---|
| SAML IdP Entity ID | The identity provider’s SAML endpoints card in the Web App | PowerShell, $IssuerUri, in Federate the domain |
| SSO URL (HTTP-Post) | The same card | PowerShell, $PassiveSignInUri, in the same step |
| Signing certificate (DER) | The same card, Download Certificate → DER format | PowerShell, the certificate path, in the same step |
| Entra ID federation metadata (XML) | Microsoft’s metadata URL, in Create the connected app | The Web App, Metadata File, in the same step |
| UPN and immutable ID | The user, in Create a federated user | The Web App, User Principal Name (UPN) and On-premises Immutable ID, in Create the connected app |
Verify your domain
In PowerShell
List the tenant’s domains:
Connect-MgGraph -Scopes "Domain.ReadWrite.All", "Directory.AccessAsUser.All"
Get-MgDomain | Select-Object Id, IsRoot, IsVerified, AuthenticationTypeA domain that shows Federated already signs in through another identity provider, such as Google Workspace. A domain holds one federation at a time, so leave it as it is. If your domain already shows IsRoot and IsVerified as True, and Managed, skip the rest of this step. If it shows IsVerified as False, open it under Domain names and click Verify instead of adding it again.
Otherwise, add a domain of its own, such as yourdomain.com, or a new subdomain of a federated domain, such as entra.yourdomain.com.
A domain of its own. Add it in the Microsoft Entra admin center. Microsoft’s Add your custom domain (opens in a new tab) article shows each screen.
- Open Domain names (opens in a new tab) → Add custom domain.
- Enter the domain and click Add domain. Entra ID shows a TXT record.
- Add that TXT record to the domain at your DNS provider.
- Click Verify. If Entra ID does not find the record yet, wait for DNS to propagate and click Verify again.
A subdomain of a federated domain. The subdomain inherits its parent’s federation, so the admin center refuses to add it. Add it in PowerShell, then make it a root domain of its own, so it no longer follows the parent. It needs no DNS record, because a subdomain of a verified domain is verified with it. Microsoft’s Change subdomain authentication type (opens in a new tab) article explains the promotion.
Entra ID refuses to promote a subdomain that already has users. Promote a new subdomain, before you create any user in it.
$Subdomain = "<entra.yourdomain.com>"
New-MgDomain -Id $Subdomain -AuthenticationType "Federated"
Invoke-MgPromoteDomain -DomainId $Subdomain
Update-MgDomain -DomainId $Subdomain -BodyParameter @{ AuthenticationType = "Managed" }Run Get-MgDomain again. Your domain shows IsRoot and IsVerified as True, and Managed. A federated parent domain and its users keep their identity provider.
Federate the domain with SplitSecure
Federation applies to every user of the domain. Once it is in place, each of them signs in through SplitSecure, with a Guardian Team vote, and needs a connected app of their own. Federate a domain that only your SplitSecure admin users use, or plan the change with every user of the domain.
In the Web App
In the Web App, open Vaults, then your vault, then the identity provider. The SAML endpoints card shows three values:
- SAML IdP Entity ID
- SSO URL (HTTP-Redirect)
- SSO URL (HTTP-Post)
Under them, Download metadata XML saves the metadata file and Download Certificate offers the certificate in PEM format or DER format.
- Copy the SAML IdP Entity ID.
- Copy the SSO URL (HTTP-Post). Entra ID needs this one, not the SSO URL (HTTP-Redirect).
- Click Download Certificate → DER format and save the file. Its name is
certificate-<name>.crt, where<name>is the identity provider’s name.
In PowerShell
An identity provider federates one domain, because Entra ID refuses an IssuerUri that another domain already uses. For a second domain or tenant, create another identity provider.
Replace the placeholders with your domain, the two copied values and the certificate path. See Microsoft’s federation guide (opens in a new tab) for the details. Unlike Microsoft’s example, the command sets no -SignOutUri: SplitSecure has no sign-out endpoint, and Entra ID refuses an empty one.
# Connect with the required permissions
Connect-MgGraph -Scopes "Domain.ReadWrite.All"
# Your values
$Domain = "<yourdomain.com>"
$IssuerUri = "<SAML IdP Entity ID from the SAML endpoints card>"
$PassiveSignInUri = "<SSO URL (HTTP-Post) from the SAML endpoints card>"
# Load the signing certificate (DER) and encode it as base64
$idptokensigningcert = [System.Security.Cryptography.X509Certificates.X509Certificate2]("C:\temp\certificate-<name>.crt")
$SigningCert = [system.convert]::tobase64string($idptokensigningcert.rawdata)
# Create the federation configuration
New-MgDomainFederationConfiguration `
-DomainId $Domain `
-IssuerUri $IssuerUri `
-PassiveSignInUri $PassiveSignInUri `
-SigningCertificate $SigningCert `
-PreferredAuthenticationProtocol "saml" `
-FederatedIdpMfaBehavior "acceptIfMfaDoneByFederatedIdp" `
-DisplayName "SplitSecure SAML IdP"Check the federation:
Get-MgDomainFederationConfiguration -DomainId $Domain | Format-List *The output shows your IssuerUri and PassiveSignInUri, identical to the values on the SAML endpoints card.
Create a federated user
In PowerShell
A user must exist in Entra ID before they can sign in through federation. SplitSecure sends the user’s immutable ID as the SAML subject (NameID) and the user’s UPN as the IDPEmail attribute. Entra ID finds the user by OnPremisesImmutableId, and the UPN must belong to the same user.
Connect-MgGraph -Scopes "User.ReadWrite.All"
$Password = "P@ssw0rd!" + (-join ((65..90) + (97..122) + (48..57) | Get-Random -Count 8 | % {[char]$_}))
$PasswordProfile = @{ Password = "$Password" }
$params = @{
UserPrincipalName = "[email protected]"
DisplayName = "User Name"
AccountEnabled = $true
MailNickName = "username"
OnPremisesImmutableId = "unique-immutable-id-001"
PasswordProfile = $PasswordProfile
UsageLocation = "US"
}
New-MgUser -BodyParameter $paramsCheck the user:
Get-MgUser -UserId "[email protected]" -Property UserPrincipalName, OnPremisesImmutableId, Id | Select-Object UserPrincipalName, OnPremisesImmutableId, IdIf OnPremisesImmutableId is empty, open the user in the Entra admin center under Users (opens in a new tab) and check Properties.
Keep the UserPrincipalName and the OnPremisesImmutableId. You enter both in the connected app.
Connect Entra ID to SplitSecure
In the Web App
Download Microsoft’s federation metadata from https://nexus.microsoftonline-p.com/federationmetadata/saml20/federationmetadata.xml (opens in a new tab) and save the XML file.
In the Web App, open Vaults, then your vault, then the identity provider. Click New Connected App and pick the service provider’s card. Name is required, and the Threshold Identity Provider field is fixed to this provider.
- Click the Microsoft Entra ID (SAML2) card.
- Enter a Name, for example
Entra ID [email protected]. - Enter the user’s UserPrincipalName as the User Principal Name (UPN).
- Enter the user’s OnPremisesImmutableId as the On-premises Immutable ID, exactly.
- Under Metadata File, upload the Microsoft XML file.
Optionally, under Advanced Options, turn on Selective notifications so members can choose who gets notified for the Guardian Team’s proposals, set the Account Sensitivity banner shown on this connected app’s proposals (None, Low, Medium, High or Critical), and enter a Description or a Reason for creation.
Click Propose connected app. The Web App opens the proposal under Requests. The members of the Guardian Team approve it on their devices, in the mobile app. When the vote passes, the connected app appears under Connected Apps.
The connected app fixes the UPN and the immutable ID, so every sign-in through it is the same Entra ID user. Create one connected app for each user.
Test the sign-in
In the Web App
- In the Web App, open Connected Apps, find the connected app and click Log in.
- On the sign-in page, click Log in. The page needs no input, because the connected app carries the UPN and the immutable ID. To leave a note for the Guardian Team, add a Reason for access under Advanced Options.
- The members of the Guardian Team approve the sign-in on their devices, in the mobile app. When the vote passes, click Sign in on the proposal page.
Only the browser profile that requested the sign-in can click Sign in, and only once.
The sign-in starts at Microsoft because Entra ID asks for a second sign-in after one it did not request, which would take a second vote. To land in another Microsoft app, start from that app, as in Sign in from Microsoft’s side.
The Microsoft Entra admin center opens, signed in as the federated user. Entra ID asked for no password.
To check that Microsoft sees the domain as federated, open https://login.microsoftonline.com/[email protected]&json=1 with your user’s UPN.
- In the test profile, open entra.microsoft.com (opens in a new tab).
- Enter the user’s UPN, for example
[email protected]. - Microsoft sends you to the Web App, which opens the connected app that signs in as the user you entered. If several connected apps sign in as that user, pick one.
- On the sign-in page, click Log in.
- When the Guardian Team’s vote passes, click Sign in to return to Microsoft.
The Entra admin center opens, signed in as the federated user.
Troubleshooting
| Issue | Solution |
|---|---|
| The Entra admin center refuses the subdomain: “One or more properties contains invalid values” | Its parent domain is federatedAdd it in PowerShell, as in Add the domain |
New-MgDomain reports “domain.LiveType must follow the root domain” | A subdomain was added without its parent’s authentication typeAdd it with -AuthenticationType "Federated", as in Add the domain |
New-MgDomainFederationConfiguration reports “Subdomain cannot be federated” | The subdomain is not a root domain yet: IsRoot is FalsePromote it, as in Add the domain, then federate it again |
AADSTS50107: “The requested federation realm object … does not exist” | No domain is federated with this identity provider’s entity IDCheck the federation as in Federate the domain, and federate the domain with this identity provider’s SAML IdP Entity ID |
| “No tenant-identifying information found” | $IssuerUri differs from the SAML IdP Entity IDCopy the entity ID again, with no extra space, and update the federation |
| Microsoft does not send you to the Web App | $PassiveSignInUri is not the SSO URL (HTTP-Post)Set it to the SSO URL (HTTP-Post) from the SAML endpoints card |
| Microsoft reports that the user was not found | The user does not exist in the federated domainCreate the user with a UPN in that domain |
AADSTS51004: “The user account … does not exist in the … directory” after the vote | No user’s OnPremisesImmutableId equals the connected app’s immutable ID, which the error quotesCheck the user as in Create the user, and create the connected app again with that user’s OnPremisesImmutableId |
New-MgDomainFederationConfiguration reports Request_MultipleObjectsWithSameKeyValue | Another domain already uses this identity provider’s entity ID as its IssuerUriCreate another identity provider for this domain |
| Microsoft rejects the signature | The certificate in the federation is not the identity provider’sDownload the DER format certificate again and update the federation |
External resources
- Use a SAML 2.0 identity provider for single sign-on (opens in a new tab): Federation configuration guide
- Add your custom domain (opens in a new tab): Add and verify a domain in the admin center
- Change subdomain authentication type (opens in a new tab): Make a subdomain a root domain
- Configure adaptive session lifetime policies (opens in a new tab): Shorten how long Entra ID keeps a session after the vote
- Entra ID federation metadata (opens in a new tab): Service provider metadata file
- Microsoft Graph PowerShell (opens in a new tab): PowerShell module for Graph API