WS-Fed Integration Guide
Overview
This guide is for delegating authentication to Beyond Identity for your Entra environment through WS-Fed. Integrating Beyond Identity with your Entra environment through WS-Fed allows your users to authenticate with Beyond Identity, a passwordless, phishing-resistant, multi-factor authentication solution.
This guide covers the steps required to complete the integration.
Stage summary
The integration setup consists of the five stages below. Each stage covers the initial set up for continuing the integration process on each respective platform. Follow the guide in linear order to complete the integration.
Stage | Summary | Microsoft Entra ID | Beyond Identity |
---|---|---|---|
I | Initial set up | - (Optional) Set up Beyond Identity Group in Entra ID | - Set up WS-Fed application in Beyond Identity |
II | System for Cross-domain Identity Management (SCIM) implementation | - Create SCIM application in Microsoft Entra ID - Enter SCIM credentials in Microsoft Entra ID - Update Attribute Mappings for SCIM in Microsoft Entra ID - Provision users in Beyond Identity using the Entra ID SCIM application | - Set up SCIM application in Beyond Identity |
III | User Enrollment | - N/A | - Assign application to users - Create Entra ID Bookmark App - Enroll users with passkeys |
IV | Domain Federation | - Executing Powershell Script for Domain Federation | - Get Powershell Script from WS-Fed Application |
V | Add New Users to Entra ID | - Add new users after federation | - N/A |
Prerequisites
To get started with the integration, view the following prerequisites.
Microsoft Entra ID
This information contains the necessary items for integrating with Beyond Identity.
- Microsoft Entra ID Global Administrator privileges
- Active Entra ID P1 license
- Domain added to Entra, must not be federated
- NOTE: If the domain is already federated, complete the unfederating process before continuing.
- Powershell configurations for administrators
Beyond Identity requirements
The list below covers the basic Beyond Identity requirements for the integration.
- Secure Access Tenant with Super Administrator Role
- Use an existing account, or sign up here to create a new Beyond Identity account
- Have at least two devices and two Super Admin roles configured*
- *Recommended, optional
Steps
Follow the steps in the sections below to complete your integration for Beyond Identity and Microsoft Entra ID.
Legend
The sections below use these two color codings to identify the steps for separate platforms. Use a separate browser window when following instructions for each platform.
🔵 Beyond Identity - Beyond Identity platform tasks are highlighted in blue.
🟠 Microsoft Entra ID - Microsoft Entra ID platform and Powershell tasks are highlighted in orange.
Stage I
The sections here are for the initial setup between Beyond Identity and Microsoft Entra ID. This is for setting up the WS-Fed application in the Beyond Identity Console. Optionally, you can set up a Beyond Identity Group in your Entra ID instance.
🟠 (Optional) Set up Beyond Identity Group in Entra ID
This section explains how to set up a Beyond Identity group in your Entra ID instance. While having a Beyond Identity group containing all your Beyond Identity users can be useful later in this guide, it is optional.
- Navigate to your Entra ID Admin Console at https://portal.azure.com.
- Navigate to Microsoft Entra ID.
- On the left-hand navigation, click Manage → Groups.
- Click + New group.
- For the Group name field, input
Beyond Identity Users
. - For the Group description field, input
Beyond Identity Users Group
. - Under Members, click No members selected.
- Search for the users that you want to add to the group.
- Select the users and click Select.
- Click Create.
🔵 Set up WS-Fed application in Beyond Identity
The following section covers setting up a WS-Fed application in the Beyond Identity console. This WS-Fed application is the configuration on the Beyond Identity side for delegating authentication to Beyond Identity.
- Navigate to your Beyond Identity Admin Console.
- On the left-hand navigation under Access Control, click Applications.
- Select the Browse Applications tab.
- Click the WS-Fed tile to proceed.
- Click Add WS-FED.
- Under General → Display Name, input
Microsoft Entra ID
into the text field. - Under the Configuration section, input the following information into the respective fields.
- ACS URL (SSO URL)* -
https://login.microsoftonline.com/login.srf
- Audience URL (Entity ID)* -
urn:federation:MicrosoftOnline
- ACS URL (SSO URL)* -
- For the Subject User Name Attribute field, select External ID in the dropdown.
- This field is the value that is present in the WS-Fed token after Beyond Identity authenticates the user. This is how Entra matches the Beyond Identity user to the user in Entra.
- For the Attribute Statements (Optional) section, use the table below to input the additional four attributes. These are additional attributes sent in the WS-Fed token to Entra during the authentication process.
Service Provider Attribute Name | Name Format | Beyond Identity Attribute Name | Namespace |
---|---|---|---|
immutableID | unspecified | External ID | http://schemas.microsoft.com/LiveID/Federation/2008/05 |
emailaddress | unspecified | http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress | |
UPN | unspecified | Username | http://schemas.xmlsoap.org/claims |
authnmethodsreferences | unspecified | Custom static string http://schemas.microsoft.com/claims/multipleauthn | http://schemas.microsoft.com/claims |
- Click Save Changes at the top of the page.
Stage II
The Stage II sections cover the System for Cross-Domain Identity Management (SCIM) implementation between Beyond Identity as the inbound platform and Microsoft Entra ID as the outbound platform. SCIM is used to populate users from your Microsoft Entra ID directory to the Beyond Identity directory. The SCIM protocol automatically updates any changes in your Microsoft Entra ID directory to the Beyond Identity directory.
With the SCIM implementation, the Entra ID directory is the source of truth. Any changes made to the Entra ID directory are reflected in the Beyond Identity directory.
🟠 Create SCIM application in Microsoft Entra ID
This section includes steps for creating a SCIM application in Microsoft Entra ID. This SCIM application provisions users to Beyond Identity.
- Navigate to your Microsoft Entra ID Admin Console at https://portal.azure.com.
- Navigate to Microsoft Entra ID.
- On the left-hand navigation, click Manage → Enterprise applications.
- Click + New application.
- Click + Create your own application.
- For field What's the name of your app?, input
Beyond Identity SCIM
. - Click Create.
- Under the Getting Started section, click 1. Assign users and groups.
- Click + Add user/group.
- On the left-hand navigation, under Users and groups, click None Selected.
- Select the users and groups for using Beyond Identity authentication. This includes all the users in the domain that you later federate.
- After selecting the users and groups, click Assign at the bottom of the page.
- Now, on the left-hand navigation, click Manage → Provisioning.
- This shows a preview of the application. On the left-hand navigation, click Manage → Provisioning.
- For the Provisioning Mode, set to Automatic.
- The new section, Admin Credentials appears.
- Return to the Beyond Identity console to get the SCIM credentials to input into the Admin Credentials section.
🔵 Set up SCIM application in Beyond Identity
This section is for getting the SCIM credentials from Beyond Identity to enter into the Entra ID SCIM application you just created. This step enables Entra ID to push users and groups from your Entra ID directory into your Beyond Identity directory.
- Navigate to your Beyond Identity Admin Console.
- On the left-hand navigation, click Access Control → Applications.
- Select the Browse Applications tab.
- Click the SCIM tile to proceed.
- Click Add SCIM.
- Under General → Display Name, input
Microsoft Entra ID SCIM
into the text field. - Under the Configure inbound provisioning section, obtain the following values and store for user later.
- SCIM URL
- An API Bearer token you generate in the next step.
- To generate the API Bearer token, go to the Bearer tokens section and click the Add Bearer Token button.
- For the Name field, input
Microsoft Entra ID SCIM Token
. Leave the expiration field as the default value. - Click Add token.
- Copy the value and store in a secure location.
- Click Save Changes at the top of the page.
The Beyond Identity bearer token for the inbound SCIM has an expiration date. To ensure the SCIM implementation doesn't break, the token must be updated after the initial token expires.
Entra ID does not support SCIM with client credentials
, which is a service-to-service authentication protocol that automatically refreshes the tokens. We will look into alternative solutions to ensure that you don't have to manually update the token from time to time.
🟠 Enter SCIM credentials in Microsoft Entra ID
- Navigate back to your SCIM application that you created in Create SCIM application in Microsoft Entra ID section.
- Under Admin Credentials, input the following values.
Tenant URL
: the value ofSCIM URL
from the section above.Secret Token
: the Bearer token that you created from the section above.
- Click Test Connection.
- If the test connection is successful, click Save.
- If the test connection is unsuccessful, go back to the Set up SCIM application in Beyond Identity section and ensure the correct values were copied over.
- Click Save.
- The new section, Mappings, appears.
🟠 Update Attribute Mappings for SCIM in Microsoft Entra ID
This section covers the attribute mappings for the SCIM application in Microsoft Entra ID. This ensures that your Entra ID user and group attributes maps correctly to the Beyond Identity user and group attributes.
Provision Microsoft Entra ID Groups
- Under the Mappings section, click Provision Microsoft Entra ID Groups.
- Under the Attribute Mapping section, there should be a customappsso Attribute called externalId.
- In that row, click the Delete button.
In the Beyond Identity SCIM implementation for groups, we do not support this field.
Provision Microsoft Entra ID Users
-
Under the Mappings section, click Provision Microsoft Entra ID Users.
-
At the bottom of the Attribute Mapping section, click Show advanced options checkbox.
-
Click Edit attribute list for customappsso.
-
Mark the following attributes as required:
- id
- displayName
- userName
- externalId
-
At the bottom, add the following attribute.
Name Type emails[primary eq true].value
String -
Click Save.
-
Under the Attribute Mappings section, click Add New Mapping.
-
Apply the following configurations. All other fields are valid defaults.
- Source attribute:
mail
- Target attribute:
emails[primary eq true].value
- Source attribute:
-
Click Save.
In the SCIM specifications, users have two types of emails, the primary
email and work
email. This setup confirms the correct email selection in the configuration.
The default Entra ID SCIM configuration maps the user's email into the work
email. The work
email isn't currently supported in Beyond Identity. The custom mapping for Beyond Identity uses the supported primary
email instead.
- Under the Attribute Mappings list, find the
externalId
attribute. - In that row, click the
Edit
button. - For the Source attribute field, select
immutableId
. - Click Save.
This process confirms the immutableId
is set as the External ID
field in Beyond Identity when Entra ID populates the Beyond Identity directory.
This unique value allows identity matching of your Entra ID and Beyond Identity directories.
- Click Save at the top of the page to save all changes to Attribute Mapping.
The next section covers provisioning users from your Entra ID directory to the Beyond Identity directory.
🟠 Provision users in Beyond Identity using the Entra ID SCIM application
This section includes steps to provision users from your Entra ID directory to the Beyond Identity directory.
- Navigate back to your SCIM application in Entra ID.
- Navigate to the Overview section.
- Click Start Provisioning.
This process may take up to 30 minutes to complete. Entra ID also pushes changes to the Beyond Identity directory using SCIM on a fixed interval. This typically happens on a 40 minute schedule.
- After this process is complete, return to your Beyond Identity Console.
- Click on Identities and you should see all your users populated!
Stage III
This section outlines the user enrollment process. It includes assigning users to the Beyond Identity application and confirming they register a passkey on their device or devices.
Completing this step is mandatory before federating the domain. This is because domain federation in Entra ID is a comprehensive action and can't be portioned or split otherwise for authentication. In this case, all users must have Beyond Identity assigned as the application and have a registered passkey on their device.
When authentication is switched to Beyond Identity, users must have a Beyond Identity passkey to log in successfully. All users without a Beyond Identity passkey are locked out from logging in.
Prevent any disruptions to your organization and confirm all users register a passkey on their device before proceeding with domain federation in Stage IV.
🔵 Assign application to users
In this section, we will assign your users the WS-Fed application that we created in Stage I. This ensures that when they login to Entra ID with their passkey, they successfully authenticate with Beyond Identity.
- Navigate to your Beyond Identity Admin Console.
- On the left-hand navigation, click Access Control → Applications.
- Go to your Microsoft Entra ID WS-Fed application that you created in Stage I.
- Click the Assignments tab at the top.
- Click the Add Assignments drop down.
- Add the users and groups that are authenticating via Beyond Identity (this should be ALL your users).
- Click Save Changes at the top of the page once completed.
🔵 Create Entra ID Bookmark App
In this section, we will set up a Bookmark App. When your users complete the enrollment process, they are redirected to the Beyond Identity dashboard. To prevent user confusion, we will put an app tile that redirects the user to the Azure Portal.
- Navigate to your Beyond Identity Admin Console.
- On the left-hand navigation, click Access Control → Applications.
- Select the Browse Applications tab.
- Click on the Bookmark tile.
- Click Add Bookmark.
- Fill in the following Fields:
- Display Name:
Azure Portal
- Login Link:
https://myapps.microsoft.com
- App Tile: Upload an Azure Icon.
- Display Name:
- Click Save Changes at the top.
- Navigate to the Assignments tab at the top.
- Click the Add Assignments drop down.
- Add the users and groups that are authenticating via Beyond Identity (this should be ALL your users).
- Click Save Changes at the top.
🔵 Enroll users with passkeys
In this section, we will get your end users set up with a passkey on their device. All your users MUST have a passkey registered on their device(s) before federating the domain, or they will be locked out.
Bulk Enrollment
- On the Beyond Identity console, navigate to Identities.
- Use the Enrollment status filter to filter by enrollment status. Enrollment status can be one of the following values:
- Unenrolled: The identity does not have any pending invites or any active passkeys.
- Pending: The identity has one or more pending invites and no active passkeys.
- Enrolled: The identity has one or more active passkeys.
- After filtering, you can multi-select users that you want to send an enrollment email to.
- Click the Add passkey(s) button above the identities table. A Send enrollment modal should appear.
- Under Identity Verification Method, select Magic link.
- For the Send email option, the email connected to that identity receives a Beyond Identity welcome email for the process to register a passkey.
- When the user goes through the enrollment process, they will go through an interactive guide with the following 2 steps:
- Download the Beyond Identity Platform Authenticator - this is the app that is required for Beyond Identity authentication.
- Enroll a passkey on their device.
Single identity enrollment
- On the Beyond Identity console, navigate to Identities → a specific user → Passkeys tab.
- The following options are avaialable for adding a passkey for an identity:
- If an identity does not have any active passkeys, click the Add a passkey button in the middle.
- If an identity has one or more active passkeys, click the Actions button → Add passkey.
- Under Identity Verification Method, select Magic link.
- For the Delivery Method option, select Send email or Generate link.
- Click the Send enrollment button.
- For the Send email option, the email connected to that identity receives a Beyond Identity welcome email for the process to register a passkey.
- For the Generate link option, a URL is generated from Beyond Identity. This link is for sharing with the user for them to register a passkey.
- When the user goes through the enrollment process, they will go through an interactive guide with the following 2 steps:
- Download the Beyond Identity Platform Authenticator - this is the app that is required for Beyond Identity authentication.
- Enroll a passkey on their device.
Ensure all your users have enrolled in passkeys before proceeding with the next step.
Stage IV Domain Federation
In this step, we will federate your Azure domain to use Beyond Identity authentication.
Ensure all your users have enrolled in passkeys before proceeding with the next step. Domain federation in Entra ID is an all-or-nothing operation when it comes to authentication. If any users do not have passkeys, they will be locked out.
🔵 Get Powershell Script from WS-Fed Application
We have a generated Powershell script for you to run!
- Navigate to your Beyond Identity Admin Console.
- On the left-hand navigation, click Access Control → Applications.
- Go to your Microsoft Entra ID WS-Fed application that you created in Stage I.
- Under Configuration, click the View Federation Script button.
- Enter in the following values:
- Domain Name: Your domain name that you want federated. It should not have a leading period. Ex.
beyondidentity.com
. - Logoff Url: You can set a logoff URL, or leave it as the default value.
- Domain Name: Your domain name that you want federated. It should not have a leading period. Ex.
- Download or copy the script. You will need it in the next step.
🟠 Executing Powershell Script for Domain Federation
These steps are for executing the script in Powershell to federate the domain.
- In your Powershell environment, run the script from the step above.
- For the Security warning pop up, click Run once.
- The browser window appears for the log in to Microsoft. Continue to pick your account for the login.
- The domain is federated after logging in. According to Microsoft, domain federation can take up to 60 Minutes.
Stage V
This outlines the process for adding new users to your Entra ID environment.
🟠 Add new users after federation
If you add users to Entra after federating your domain, you may encounter the sourceAnchor
issue. To prevent this, use the following Powershell script to create new users after federation.
Run the PowerShell script below to create new users and set the immutableID
value for proper mapping, ensuring a seamless integration. If you need further assistance, contact your Beyond Identity representative.
Install-Module MSOnline
Connect-MsolService
$upn = "[email protected]"
Write-Output "Calling Get-MsolUser"
$user = Get-MsolUser -UserPrincipalName $upn
Write-Output "User $user"
$uuid = [system.convert]::ToBase64String(([GUID]$user.objectID.Guid).ToByteArray())
Write-Output "$uuid"
Set-Msoluser -UserPrincipalName $upn -ImmutableID $uuid
Congratulations! You've completed your Beyond Identity integration with Entra ID!