WS-Fed Integration Guide

Last updated on Jan 30, 2025

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	Update ImmutableID for Azure Users (Azure AD Only Deployments)	- Update ImmutableID for Azure Users	- 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.

1. Navigate to your Entra ID Admin Console at https://portal.azure.com.
2. Navigate to Microsoft Entra ID.
3. On the left-hand navigation, click Manage → Groups.
4. Click + New group.
5. For the Group name field, input Beyond Identity Users.
6. For the Group description field, input Beyond Identity Users Group.
7. Under Members, click No members selected.
8. Search for the users that you want to add to the group.
9. Select the users and click Select.
10. 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.

1. Navigate to your Beyond Identity Admin Console.
2. On the left-hand navigation under Access Control, click Applications.
3. Select the Browse Applications tab.
4. Click the WS-Fed tile to proceed.
5. Click Add WS-FED.
6. Under General → Display Name, input Microsoft Entra ID into the text field.
7. 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
8. 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.
9. 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	Email	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

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

note

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.

1. Navigate to your Microsoft Entra ID Admin Console at https://portal.azure.com.
2. Navigate to Microsoft Entra ID.
3. On the left-hand navigation, click Manage → Enterprise applications.
4. Click + New application.
5. Click + Create your own application.
6. For field What's the name of your app?, input Beyond Identity SCIM.
7. Click Create.
8. Under the Getting Started section, click 1. Assign users and groups.
9. Click + Add user/group.
10. On the left-hand navigation, under Users and groups, click None Selected.
11. Select the users and groups for using Beyond Identity authentication. This includes all the users in the domain that you later federate.
12. After selecting the users and groups, click Assign at the bottom of the page.
13. Now, on the left-hand navigation, click Manage → Provisioning.
14. This shows a preview of the application. On the left-hand navigation, click Manage → Provisioning.
15. For the Provisioning Mode, set to Automatic.
16. The new section, Admin Credentials appears.
17. 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.

1. Navigate to your Beyond Identity Admin Console.
2. On the left-hand navigation, click Access Control → Applications.
3. Select the Browse Applications tab.
4. Click the SCIM tile to proceed.
5. Click Add SCIM.
6. Under General → Display Name, input Microsoft Entra ID SCIM into the text field.
7. 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.
8. To generate the API Bearer token, go to the Bearer tokens section and click the Add Bearer Token button.
9. For the Name field, input Microsoft Entra ID SCIM Token. Leave the expiration field as the default value.
10. Click Add token.
11. Copy the value and store in a secure location.
12. Click Save Changes at the top of the page.

note

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

1. Navigate back to your SCIM application that you created in Create SCIM application in Microsoft Entra ID section.
2. Under Admin Credentials, input the following values.
   • Tenant URL: the value of SCIM URL from the section above.
   • Secret Token: the Bearer token that you created from the section above.
3. Click Test Connection.
   1. If the test connection is successful, click Save.
   2. 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.
4. Click Save.
5. 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

1. Under the Mappings section, click Provision Microsoft Entra ID Groups.
2. Under the Attribute Mapping section, there should be a customappsso Attribute called externalId.
3. In that row, click the Delete button.

note

In the Beyond Identity SCIM implementation for groups, we do not support this field.

Provision Microsoft Entra ID Users

1. Under the Mappings section, click Provision Microsoft Entra ID Users.

2. At the bottom of the Attribute Mapping section, click Show advanced options checkbox.

3. Click Edit attribute list for customappsso.

4. Mark the following attributes as required:

   • id
   • displayName
   • userName
   • externalId

5. At the bottom, add the following attribute.

   Name	Type
   emails[primary eq true].value	String

6. Click Save.

7. Under the Attribute Mappings section, click Add New Mapping.

8. Apply the following configurations. All other fields are valid defaults.

   • Source attribute: mail
   • Target attribute: emails[primary eq true].value

9. Click Save.

note

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.

10. Under the Attribute Mappings list, find the externalId attribute.
11. In that row, click the Edit button.
12. For the Source attribute field, select immutableId.
13. Click Save.

note

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.

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

1. Navigate back to your SCIM application in Entra ID.
2. Navigate to the Overview section.
3. Click Start Provisioning.

note

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.

4. After this process is complete, return to your Beyond Identity Console.
5. 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.

tip

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.

1. Navigate to your Beyond Identity Admin Console.
2. On the left-hand navigation, click Access Control → Applications.
3. Go to your Microsoft Entra ID WS-Fed application that you created in Stage I.
4. Click the Assignments tab at the top.
5. Click the Add Assignments drop down.
6. Add the users and groups that are authenticating via Beyond Identity (this should be ALL your users).
7. 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.

1. Navigate to your Beyond Identity Admin Console.
2. On the left-hand navigation, click Access Control → Applications.
3. Select the Browse Applications tab.
4. Click on the Bookmark tile.
5. Click Add Bookmark.
6. Fill in the following Fields:
   1. Display Name: Azure Portal
   2. Login Link: https://myapps.microsoft.com
   3. App Tile: Upload an Azure Icon.
7. Click Save Changes at the top.
8. Navigate to the Assignments tab at the top.
9. Click the Add Assignments drop down.
10. Add the users and groups that are authenticating via Beyond Identity (this should be ALL your users).
11. 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

1. On the Beyond Identity console, navigate to Identities.
2. 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.
3. After filtering, you can multi-select users that you want to send an enrollment email to.
4. Click the Add passkey(s) button above the identities table. A Send enrollment modal should appear.
5. Under Identity Verification Method, select Magic link.
   1. For the Send email option, the email connected to that identity receives a Beyond Identity welcome email for the process to register a passkey.
6. When the user goes through the enrollment process, they will go through an interactive guide with the following 2 steps:
   1. Download the Beyond Identity Platform Authenticator - this is the app that is required for Beyond Identity authentication.
   2. Enroll a passkey on their device.

Single identity enrollment

1. On the Beyond Identity console, navigate to Identities → a specific user → Passkeys tab.
2. The following options are avaialable for adding a passkey for an identity:
   1. If an identity does not have any active passkeys, click the Add a passkey button in the middle.
   2. If an identity has one or more active passkeys, click the Actions button → Add passkey.
3. Under Identity Verification Method, select Magic link.
4. For the Delivery Method option, select Send email or Generate link.
5. Click the Send enrollment button.
   1. For the Send email option, the email connected to that identity receives a Beyond Identity welcome email for the process to register a passkey.
   2. 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.
6. When the user goes through the enrollment process, they will go through an interactive guide with the following 2 steps:
   1. Download the Beyond Identity Platform Authenticator - this is the app that is required for Beyond Identity authentication.
   2. Enroll a passkey on their device.

note

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.

danger

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!

1. Navigate to your Beyond Identity Admin Console.
2. On the left-hand navigation, click Access Control → Applications.
3. Go to your Microsoft Entra ID WS-Fed application that you created in Stage I.
4. Under Configuration, click the View Federation Script button.
5. 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.
6. 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.

1. In your Powershell environment, ensure you have the proper Microsoft Graph PowerShell SDK installed. In your Powershell environment, run the following command:

   Install-Module Microsoft.Graph -Scope CurrentUser -Repository PSGallery -Force

2. Verify your installation by running the following command:

   Get-InstalledModule Microsoft.Graph

   Ensure the following modules are installed:

   • Microsoft.Graph.Authentication
   • Microsoft.Graph.Identity.DirectoryManagement

   If they are not installed, run the following commands to install those SDKs directly:

   Install-Module Microsoft.Graph.Authentication -Scope CurrentUser -Force
   Install-Module Microsoft.Graph.Identity.DirectoryManagement -Scope CurrentUser -Force

caution

Ensure the versions of Microsoft Graph PowerShell SDK are 2.26.1 or higher. There was a bug in the 2.26.0 version that causes the domain federation to fail.

3. Run the script from the step above.
4. For the Security warning pop up, click Run once.
5. The browser window appears for the log in to Microsoft. Continue to pick your account for the login.
6. 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.

🟠 Update ImmutableID for Azure Users

If your organization is running in an Azure AD Only deployment, you must set the immutableID for the users in your Entra ID directory. This ensures that the users are properly mapped in the Beyond Identity directory. Users created in an Azure AD Only environment do not have this attribute populated.

1. Verify your Microsoft Graph PowerShell SDK installation by running the following command:

   Get-InstalledModule Microsoft.Graph

   Ensure the following modules are installed:

   • Microsoft.Graph.Authentication
   • Microsoft.Graph.Users

   If they are not installed, run the following commands to install those SDKs directly:

   Install-Module Microsoft.Graph.Authentication -Scope CurrentUser -Force
   Install-Module Microsoft.Graph.Users -Scope CurrentUser -Force

2. Run the PowerShell script below to create new users and set the immutableID value for proper mapping. If you need further assistance, contact your Beyond Identity representative.

   # Connect to Microsoft Graph with necessary permissions
   Connect-MgGraph -Scopes "User.ReadWrite.All"
   
   # Define user UPN
   $upn = "<upn of the user you are setting ImmutableID for>"
   
   # Get user details
   Write-Output "Calling Get-MgUser"
   $user = Get-MgUser -UserId $upn
   Write-Output "User found: $($user.DisplayName)"
   
   # Generate ImmutableID from ObjectID
   $uuid = [system.convert]::ToBase64String(([GUID]$user.Id).ToByteArray())
   Write-Output "Generated ImmutableID: $uuid"
   
   # Update the user's ImmutableID
   Update-MgUser -UserId $upn -OnPremisesImmutableId $uuid
   Write-Output "ImmutableID updated successfully."

tip

Congratulations! You've completed your Beyond Identity integration with Entra ID!