Microsoft 365 Integration

BlokSec can be configured to support passwordless login and (optionally) user provisioning to Microsoft 365 (formerly known as Office 365).

BlokSec’s Microsoft 365 integration enables authentication via the WS-FED protocol. Configuration involves steps on both the BlokSec Admin UI and Microsoft Entra / Azure Active Directory (AAD) using PowerShell.

Microsoft allows administrators to federate (a form of delegation whereby a third party is trusted to perform user authentication) one or more of their domains to BlokSec.

When configuring Microsoft 365 for your company (or client), you will have chosen a domain name - Microsoft assigns an ‘onmicrosoft.com’ suffix to your domain. For example: company_name.onmicrosoft.com. In addition to the onmicrosoft.com base domain, you can also configure a custom domain (or domains); for example: company_name.com. Once a custom domain has been added, that domain can be made default, meaning that user email addresses and logins would be associated with this domain by default.

Here is an example company that has created a custom domain with their company’s name as the default domain (admin.microsoft.com > Settings > Domains):

Microsoft does not allow the .onmicrosoft.com domain to be federated and does not allow a domain’s ‘Default’ domain to be federated. Therefore, to allow the custom domain (e.g. company_name.com) to be federated for passwordless login, it must not be the ‘Default’ domain. For more information, see Domain Federation below.

Authentication

Configure Authentication in the BlokSec Admin UI

Sign into BlokSec admin UI with admin privileges for your tenant
On the main dashboard, click the Add Application drop-down and select Create From Template, and select Microsoft 365
Complete the application details as follows and submit:
- Name: Microsoft 365 (or your desired application name — we will assume this is called ‘Microsoft 365’ for the remainder of this article)
Click Submit to save the configuration
Select View PS Script and copy the contents to an editor. Update the <domain_name> parameter to the value of your tenant’s custom domain.

Domain Federation via PowerShell

Prerequisites

Before you can federate users from Microsoft 365 to BlokSec, you need to add a custom domain to your Microsoft 365 tenant. If you have not done this, please follow these instructions on how to add your domain. Note that the *.onmicrosoft.com domains cannot be federated. Also note that during the addition of the domain (on step 2 of the process), Microsoft 365 will ask if you want to add users, select the option “I don’t want to add users right now.”
You will need to use the Microsoft PowerShell tool. Here are the instructions to install the Microsoft Online Services Sign-In Assistant and the Azure Active Directory Module for Windows PowerShell.

Configuration

In PowerShell, type the following command and enter your administrator credential for your Office 365 tenant when prompted: Connect-MsolService
Once successfully connected, copy the updated version of the PS Script updated with your custom domain from step #5 above and paste / enter in PowerShell command prompt
The provided PS Script follows the federation configuration command with a Get-MsolDomainFederationSettings command that should provide confirmation that the domain was successfully federated with BlokSec for authentication:

Troubleshooting

If you receive a message concerning default domain:

Set-MsolDomainAuthentication : You cannot remove this domain as the default domain without replacing it with another default domain. Use the the Set-MsolDomain cmdlet to set another domain as the default domain before you delete this domain.

Ensure that the domain being federated is not the Default domain for the organization:

In the admin center, go to the Settings > Domains page.
On the Domains page, select the domain you want to set as the default (note that this cannot be the domain you are federating, so if you have only one custom domain, e.g., company.com, change this back to the Microsoft-provided onmicrosoft.com domain, e.g., company.onmicrosoft.com)
Select Set as default

Backing Out

To remove the federation from the selected domain, run the command:

Set-MsolDomainAuthentication -DomainName <domain_name> -Authentication managed

Provisioning

Microsoft Entra Administration Portal

Create Application

Open a browser and navigate to the Entra Admin Center and login using an account with Global Administrator permissions (if your organization is simply subscribing to Microsoft 365 for email and Office applications, this is the same account you use to login to the admin.microsoft.com portal)
Select Applications in the left-hand navigation, then select App registrations.
Select New registration. Enter a name for your application, for example, BlokSec Provisioning Integration.
Set Supported account types as Accounts in this organizational directory only.
Leave Redirect URI empty.
Click Register to submit the application registration. On the application’s Overview page, copy the value of the Application (client) ID, this is your client_id that you will need in the next step.
Select Authentication in the secondary navigation menu. Locate the Advanced settings section and change the Allow public client flows toggle to Yes, then choose Save.

Configure API Permissions

Note: This section requires a work/school account with the Global administrator role (this would be the first account you created when subscribing to Microsoft 365).

Select API permissions in the secondary navigation menu.
Remove the default User.Read permission under Configured permissions by selecting the ellipses (…) in its row and selecting Remove permission.
Select Add a permission, then Microsoft Graph.
Select Application permissions.
Select User.ReadWrite.All, then select Add permissions.
Select Grant admin consent for…, then select Yes to provide admin consent for the selected permission.
Select Certificates and secrets in the secondary navigation menu, then select New client secret.
Enter a description, for example, BlokSec provisioning secret; choose a duration, and select Add. Note, please make note of the secret’s expiry date and be sure to rotate it prior to expiry.
Copy the secret from the Value column, this is your client_secret that you will need in the next steps.

Configure Provisioning in the BlokSec Admin UI

Sign into BlokSec admin UI with admin privileges for your tenant
Select your Microsoft 365 application then edit the configuration (top right cog icon > Edit Application)
Go to the provisioning tab
Check the Enable provisioning checkbox
Enter the following JSON data into the Properties (JSON) text area (change the placeholder values to the correct values for your Microsoft 365 tenant):

{
  "client_id": "<client_id>",
  "client_secret": "<client_secret>",
  "tenant_domain": "<domain_name>"
}

Example provisioning configuration in BlokSec admin UI showing the properties JSON field

Click Submit

Your domain is now configured to accept users provisioned via BlokSec.

Creating Users and Assigning Licenses

BlokSec Admin UI

Log into the BlokSec Admin UI with an admin user
Navigate to Applications > Microsoft 365 > (Cog menu) > Create Account
Fill in the user’s details. Note that Email will be used to send the registration, and Account Name is the new Microsoft 365 account name. For new users who do not have access to their Microsoft 365 email inbox to retrieve the registration email yet (they must first register with BlokSec to be able to login) we recommend using the secondary / personal email address for Email

Microsoft 365 Admin Center

Log into the Microsoft 365 Admin Center as an administrative user
Select the user who was created above
Select the Licenses and apps tab
Select the Microsoft 365 license type you would like added to the new user

Microsoft 365 license assignment screen showing license options for a user