Skip to main content

Microsoft365 Integration (Formerly Office365)

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

BlokSec's Microsoft365 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.

How Microsoft 365 Federation Works

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 Admin Domain Config

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.

How Microsoft 365 Provisioning Works

If provisioning is enabled in BlokSec, users created from the BlokSec Admin UI will automatically be provisioned (created) in Microsoft 365's directory (Azure Active Directory) using Microsoft's Graph API. This is provided as a convenience to save administrators having to create accounts in both places. Once the user has been created in BlokSec, open their newly created account in the M365 console (https://admin.microsoft.com) to assign M365 licences as required.

Authentication​

Configure Authentication in the BlokSec Admin UI​

  1. Sign into BlokSec admin UI with admin privileges for your tenant

  2. On the main dashboard, click the Add Application drop-down and select Create From Template, and select Microsoft 365

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

  4. Click Submitto save the configuration

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

warning

You can only federate a custom domain (i.e., not your <tenant>.onmicrosoft.com domain) and the domain can not be the default domain for the organization.

tip

Domain Best Practice

Make your <tenant>.onmicrosoft.com domain the 'Default' domain for your tenant, and then federate your custom domain

Example from BlokSec's Luvion demonstration tenant:

Example of a correct configuration for BlokSec federation

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​

  1. In PowerShell, type the following command and enter your administrator credential for your Office 365 tenant when prompted: Connect-MsolService

  2. Once successfully connected, copy the updated version of thePS Script updated with your custom domain from step #5 above and paste / enter in PowerShell command prompt

  3. The provide 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:

    1. Example output from successful command execution

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​

  1. Open a browser and navigate to the Entra Admin Center - https://entra.microsoft.com 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 https://admin.microsoft.com portal)

  2. Select Applications in the left-hand navigation, then select App registrations.

  3. Select New registration. Enter a name for your application, for example, BlokSec Provisioning Integration.

  4. Set Supported account types as Accounts in this organizational directory only.

  5. Leave Redirect URI empty.

  6. 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 it in the next step.

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

  1. Select API permissions in the secondary navigation menu.

  2. Remove the default User.Read permission under Configured permissions by selecting the ellipses (...) in its row and selecting Remove permission.

  3. Select Add a permission, then Microsoft Graph.

  4. Select Application permissions.

  5. Select User.ReadWrite.All, then select Add permissions.

  6. Select Grant admin consent for..., then select Yes to provide admin consent for the selected permission.

  7. Select Certificates and secrets in the secondary navigation menu, then select New client secret.

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

  9. Copy the secret from the Value column, this is your client_secret that you will need it in the next steps.

Configure Provisioning in the BlokSec Admin UI​

  1. Sign into BlokSec admin UI with admin privileges for your tenant

  2. Select your Microsoft 365 application then edit the configuration (top right cog icon > Edit Application)

  3. Go to the provisioning tab

  4. Check the Enable provisioning checkbox

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

  • Click Submit

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

Creating Users and Assigning Licenses​

BlokSec Admin UI​

  1. Log into the BlokSec Admin UI with an admin user

  2. Navigate to Applications > Microsoft 365 > (Cog menu) > Create Account

  3. Fill in the user's details. Note that Emailwill 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

Create Account example

Microsoft 365 Admin Center​

  1. Log into the Microsoft 365 Admin Center as an administrative user

  2. Select the user who was created above

  3. Select the Licenses and apps tab

  4. Select the Microsoft 365 license type you would like added to the new user

Example M365 license application