Search the documentation
Search the documentation...
SplitSecure documentation

On this page

Procedure · 7 steps

Microsoft Entra ID

Federate a Microsoft Entra ID domain with SplitSecure, so each sign-in of its users is approved by your Guardian Team.

Updated

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.com domain.
  • 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:

PowerShell
Connect-MgGraph -Scopes "Domain.ReadWrite.All", "Directory.AccessAsUser.All"
Get-MgDomain | Select-Object Id, IsRoot, IsVerified, AuthenticationType

A 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.

  1. Open Domain names (opens in a new tab) → Add custom domain.
  2. Enter the domain and click Add domain. Entra ID shows a TXT record.
  3. Add that TXT record to the domain at your DNS provider.
  4. 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.

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

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.

  1. Copy the SAML IdP Entity ID.
  2. Copy the SSO URL (HTTP-Post). Entra ID needs this one, not the SSO URL (HTTP-Redirect).
  3. 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.

PowerShell
# 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:

PowerShell
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.

PowerShell
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 $params

Check the user:

PowerShell
Get-MgUser -UserId "[email protected]" -Property UserPrincipalName, OnPremisesImmutableId, Id | Select-Object UserPrincipalName, OnPremisesImmutableId, Id

If OnPremisesImmutableId is empty, open the user in the Entra admin center under Users (opens in a new tab) and check Properties.

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.

  1. Click the Microsoft Entra ID (SAML2) card.
  2. Enter a Name, for example Entra ID [email protected].
  3. Enter the user’s UserPrincipalName as the User Principal Name (UPN).
  4. Enter the user’s OnPremisesImmutableId as the On-premises Immutable ID, exactly.
  5. Under Metadata File, upload the Microsoft XML file.
  6. 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.

  7. 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

  1. In the Web App, open Connected Apps, find the connected app and click Log in.
  2. 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.
  3. 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.

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.

  1. In the test profile, open entra.microsoft.com (opens in a new tab).
  2. Enter the user’s UPN, for example [email protected].
  3. 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.
  4. On the sign-in page, click Log in.
  5. When the Guardian Team’s vote passes, click Sign in to return to Microsoft.

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