Known limitations

We do not support SSO for Azure in combination with Windows Autopilot.
Outlook 2010 does not support Modern Authentication by default.
When using HelloID as IDP for AzureAD, Modern Authentication is required.
Check out the following links for more information:
- https://answers.microsoft.com/en-us/msoffice/forum/all/enabling-modern-authentication/f0f1b9d2-a080-4ca9-8ba6-8754a35d6de4
- https://docs.microsoft.com/en-us/office365/admin/security-and-compliance/enable-modern-authentication?redirectSourcePath=%252fen-us%252farticle%252fEnable-Modern-Authentication-for-Office-2013-on-Windows-devices-7dc1c01a-090f-4971-9677-f1b192d6c910&view=o365-worldwide

Introduction

This guide will walk you through configuring HelloID and Microsoft Azure (and Office365) for SAML single sign-on.

Requirements:

HelloID environment
AzureAD environment with a custom domain
Access to PowerShell ISE version 5.1 or later

The default domain *.onmicrosoft.com cannot be used for federation. To add a domain in Microsoft Azure go to the Admin Center > Settings > Domains.

Backup Account

Before proceeding with the federation, make sure there is a backup admin account that is not a member of the domain which you want to federate. The following screenshot provides an example of these two types of accounts.

that is going to be federated.
Backupadmin: Member of the *.onmicrosoft.com domain, the default domain.

Create or Import a Certificate

If there is no certificate yet, a certificate must be imported or created. This can be done in the HelloID Administrator Portal under Settings > Certificates. For this tutorial, we will use a self-signed certificate. Learn more about certificates here.

Create a Service Provider Application for Microsoft Azure in HelloID

Add the Azure Application

Login as Administrator in the HelloID Portal and press manage portal. Go to Settings > Certificates and press Create Self-Signed Certificate to create a Certificate for Microsoft Azure. See How to use certificates for more information about creating and using certificates.
Go to Applications > Applications and press Open application catalog.
Search for the Microsoft Azure SAML application template and press Add.

General tab

On the General tab, the Default settings do not need to be changed. Press Next to continue.

Single Sign-on tab

On the Single Sign-On tab, perform the following steps:

For the Issuer field, provide your HelloID domain in the format "https://{customer}.helloid.com".
Endpoint/ACS URL does not need to be changed.
In the X509 Certificate dropdown, select the certificate that you created or imported previously.
Select the certificate you created at the start of this guide and press Next.

Self service tab

On the Self Service tab, choose whether to automatically create a Self Service product, which makes the application requestable. This is optional. Click Next.

Finish tab

On the Finish tab, click Save to add the application to HelloID.

Configuring the Mapping Set

By default, the 'matching identifier' is set to the user's Username. This is assuming the username as in HelloID is known and matches the ImmutableId in AzureAD.
If you wish to use another attribute, click here to learn more about attribute mappings.

In most cases, the On-premises AD environment is the source for AzureAD and the local AD users are synced to AzureAD with AzureAD Connect. In this case, the ImmutableId of the AzureAD users is, by default, the base64 encoded string of the objectGUID (of the AD account) converted to a byte array.

Synchronization script

Since this isn't a default attribute synced from AD we have provided a synchronization script for this purpose. Click here to find out more about PowerShell Scripts in HelloID.

Copy the following script and fill in the parameters

$portalBaseUrl, replace <customer> with your HelloID domain name.
$HelloIDApiKey, replace <Provide your API key here> with your HelloID API Key.
$HelloIDApiSecret , replace "<Provide your API key here> with your HelloID API Secret.

<#------------- Parameters -------------#>
$portalBaseUrl = "https://.helloid.com"

$HelloIDApiKey = ""
$HelloIDApiSecret = ""
<#------------- Functions: HelloID -------------#>
# Possible Events Information,Success,Warning,Error,Failed,Console,Critical
function Write-HidStatus {
    [cmdletBinding()]
    param(
        [Parameter(Mandatory = $true)]
        $Message,
  
        [Parameter(Mandatory = $true)]
        [String]
        $Event
    )
      
    if ([String]::IsNullOrEmpty($portalBaseUrl) -eq $true) {
        Write-Output ($Message)
    }
    else {
        Hid-Write-Status -Message $Message -Event $Event
    }
}
  
function Write-HidSummary {
    [cmdletBinding()]
    param(
        [Parameter(Mandatory = $true)]
        $Message,
   
        [Parameter(Mandatory = $true)]
        [String]
        $Event
    )
    if ([String]::IsNullOrEmpty($portalBaseUrl) -eq $true) {
        Write-Output ($Message)
    }
    else {
        Hid-Write-Summary -Message $Message -Event $Event
    }
}
  

# Create function to create new web request key
function New-WebRequestKey {
    [CmdletBinding()]
    param(
        [Parameter(Mandatory = $true)] 
        [String] 
        $ApiKey,

        [Parameter(Mandatory = $true)] 
        [String] 
        $ApiSecret,

        [Parameter(Mandatory = $true)]
        [Ref]
        $Response
    )
    try {
        Write-HidStatus -Message "Creating HelloID API key..." -Event Information
        $Response.Value = $null
        $pair = "${ApiKey}:${ApiSecret}"
        $bytes = [System.Text.Encoding]::ASCII.GetBytes($pair)
        $base64 = [System.Convert]::ToBase64String($bytes)
        $key = "Basic $base64"
        $Response.Value = $key
        Write-HidStatus -Message "Successfully created HelloID API key" -Event Success
    }
    catch {
        throw "Could not create HelloID API key, errorcode: 0x$('{0:X8}' -f $_.Exception.HResult), message: $($_.Exception.Message)"
    }
}

# Create function for Rest method
function Invoke-HidRestMethod {
    [CmdletBinding()]
    param(
        [Parameter(Mandatory = $true)] 
        [String] 
        $Method,

        [Parameter(Mandatory = $true)] 
        [String] 
        $Uri,

        [Parameter(Mandatory = $false)] 
        [String] 
        $ContentType,

        [Parameter(Mandatory = $false)] 
        [String] 
        $Key,

        [Parameter(Mandatory = $false)] 
        $Body,

        [Parameter(Mandatory = $true)]
        [Ref]
        $Response,

        [Parameter(Mandatory = $false)] 
        $Credential,

        [Parameter(Mandatory = $false)]
        $Headers,

        [Parameter(Mandatory = $false)]
        $PageSize
    )

    [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls -bor [Net.SecurityProtocolType]::Tls11 -bor [Net.SecurityProtocolType]::Tls12
 
    $parameters = @{ }
    if ($Body) {
        $parameters += @{
            Body = $Body
        }
    }
    if ($ContentType) {
        $parameters += @{
            ContentType = $ContentType
        }
    }
    if ($Key) {
        $header = @{ }
        $header.Add("authorization", $Key)
        $parameters += @{
            Headers = $header
        }
    }
    if ($Credential) {
        $parameters += @{
            Credential = $Credential
        }
    }
    if ($Headers -and !$key) {
        $parameters += @{
            Headers = $Headers
        }
    }
    $Response.Value = $null

    try {
        if ($Uri.EndsWith("/") -eq $true) {
            Write-HidStatus -Message ("Failed::Get::$Uri::Uri invalid") -Event Error
            return
        }

        if ($PageSize -ne $null) {
            $take = $PageSize
            $skip = 0
            if ($Uri -match '\?') {
                $uriFirstPage = $Uri + "&skip=$skip&take=$take"
            }
            else {
                $uriFirstPage = $Uri + "?skip=$skip&take=$take"
            }
            $servicePoint = [System.Net.ServicePointManager]::FindServicePoint($uriFirstPage)
            $dataset = Invoke-RestMethod -Method $Method -Uri $uriFirstPage @parameters
            if ($dataset.pageData -ne $null) {
                $dataset = $dataset.pageData
            }
            $result = $servicePoint.CloseConnectionGroup("")

            $Response.Value += $dataset
            Write-HidStatus -Message ("Successfully retrieved data from $uriFirstPage") -Event Information
            
            $skip += $take
            while ($dataset.Count -eq $take) {
                if ($Uri -match '\?') {
                    $uriPage = $Uri + "&skip=$skip&take=$take"
                }
                else {
                    $uriPage = $Uri + "?skip=$skip&take=$take"
                }
        
                $servicePoint = [System.Net.ServicePointManager]::FindServicePoint($uriPage)
                $dataset = Invoke-RestMethod -Method $Method -Uri $uriPage @parameters
                if ($dataset.pageData -ne $null) {
                    $dataset = $dataset.pageData
                }
                $result = $servicePoint.CloseConnectionGroup("")
        
                $skip += $take
                $Response.Value += $dataset
                Write-HidStatus -Message "Successfully retrieved data from $uriPage" -Event Information
            }
        }
        else {
            $Response.Value = $null
            $servicePoint = [System.Net.ServicePointManager]::FindServicePoint($Uri)
            $Response.Value = Invoke-RestMethod -Method Get -Uri $Uri @parameters
            $result = $servicePoint.CloseConnectionGroup("") 
        }
    }
    catch {
        throw $_
    }
}

# Create function for web request
function Invoke-HidWebRequest {
    [CmdletBinding()]
    param(
        [Parameter(Mandatory = $true)] 
        [String] 
        $Method,

        [Parameter(Mandatory = $true)] 
        [String] 
        $Uri,

        [Parameter(Mandatory = $false)] 
        [String] 
        $ContentType,

        [Parameter(Mandatory = $false)] 
        [String] 
        $Key,

        [Parameter(Mandatory = $false)] 
        $Body,

        [Parameter(Mandatory = $true)]
        [Ref]
        $Response,

        [Parameter(Mandatory = $false)] 
        $Credential,

        [Parameter(Mandatory = $false)]
        $Headers
    )  
    [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls10 -bor [Net.SecurityProtocolType]::Tls11 -bor [Net.SecurityProtocolType]::Tls12

    $parameters = @{
        Uri    = $Uri
        Method = $Method
    }
    if ($Body) {
        $parameters += @{
            Body = $Body
        }
    }
    if ($ContentType) {
        $parameters += @{
            ContentType = $ContentType
        }
    }
    if ($Key) {
        $header = @{ }
        $header.Add("authorization", $Key)
        $parameters += @{
            Headers = $header
        }
    }
    if ($Credential) {
        $parameters += @{
            Credential = $Credential
        }
    }
    if ($Headers -and !$key) {
        $parameters += @{
            Headers = $Headers
        }
    }
    if ($PSVersionTable.PSVersion.ToString() -le "6.0") {
        $parameters += @{
            UseBasicParsing = $true
        }
    }

    try {
        $Response.Value = $null
        $servicePoint = [System.Net.ServicePointManager]::FindServicePoint($Uri)
        $webRequest = Invoke-WebRequest @parameters
        $result = $servicePoint.CloseConnectionGroup("")
        $Response.Value = $webRequest
    }
    catch {
        throw $_
    }
}

# Create function for to get all HelloID users
function Get-HIDUsers {
    [CmdletBinding()]
    param(
        [Parameter(Mandatory = $true)] 
        [String] 
        $PortalBaseUrl,

        [Parameter(Mandatory = $true)] 
        $Headers,

        [Parameter(Mandatory = $false)] 
        $UsernameFilter,        

        [Parameter(Mandatory = $true)]
        [Ref]
        $Response
    )
    try {
        $Response.Value = $null
        Write-HidStatus -Message "Gathering users from HelloID..." -Event Information
        if ($PortalBaseUrl.EndsWith("/")) {
            $uri = ($PortalBaseUrl + "api/v1/users")
        }
        else {
            $uri = ($PortalBaseUrl + "/api/v1/users")
        }

        $users = New-Object PSCustomObject
        Invoke-HidRestMethod -Response ([Ref]$users) -Method Get -Uri $uri -Headers $Headers -ContentType "application/json" -PageSize 500

        if (![string]::IsNullOrEmpty($UsernameFilter)) {
            Write-HidStatus -Message "Found [$($users.userName.Count)] users. Filtering out users with [$UsernameFilter] in their username." -Event Warning
            $users = foreach ($user in $users) {
                if ($user.username -notlike "*$UsernameFilter*") {
                    $user
                }
            }
        }

        $Response.Value = $users
        Write-HidStatus -Message "Successfully gathered users from HelloID. Found [$($users.userName.Count)] users" -Event Success        
    }
    catch {
        throw "Could not gather users from HelloID, errorcode: 0x$('{0:X8}' -f $_.Exception.HResult), message: $($_.Exception.Message)"
    }
}
 
function Update-HIDUser {
    [CmdletBinding()]
    param(
        [Parameter(Mandatory = $true)] 
        [String] 
        $PortalBaseUrl,

        [Parameter(Mandatory = $true)] 
        $Headers,

        [Parameter(Mandatory = $true)]
        [String]
        $Username,

        [Parameter(Mandatory = $false)]
        [Boolean]
        $IsEnabled,

        [Parameter(Mandatory = $false)]
        [Boolean]
        $IsLocked,

        [Parameter(Mandatory = $false)]
        [Boolean]
        $MustChangePassword,

        [Parameter(Mandatory = $false)]
        [String]
        $FirstName,

        [Parameter(Mandatory = $false)]
        [String]
        $LastName,

        [Parameter(Mandatory = $false)]
        [String]
        $ContactEmail,

        [Parameter(Mandatory = $false)]
        [String]
        $PhoneNumber,

        [Parameter(Mandatory = $false)]
        [String]
        $EmployeeId,
        
        [Parameter(Mandatory = $false)]
        [String]
        $SamAccountName,

        [Parameter(Mandatory = $false)]
        [Array]
        $Roles,

        [Parameter(Mandatory = $false)]
        [Hashtable]
        $UserAttributes,

        [Parameter(Mandatory = $false)]
        [Boolean]
        $Logging,

        [Parameter(Mandatory = $true)]
        [Ref]
        $Response
    )
    try {
        $Response.Value = $null

        if ($Logging) {
            Write-HidStatus -Message "Updating HelloID user '$Username'..." -Event Information
        }

        if ($PortalBaseUrl.EndsWith("/")) {
            $uri = ($PortalBaseUrl + "api/v1/users/$Username")
        }
        else {
            $uri = ($PortalBaseUrl + "/api/v1/users/$Username")
        }

        $userBody = @{
            userName = $Username
        }
        
        $Attributes = [Ordered]@{
            firstName          = $FirstName
            lastName           = $LastName
            isEnabled          = $IsEnabled
            isLocked           = $IsLocked
            mustChangePassword = $MustChangePassword
            contactEmail       = $ContactEmail
            roles              = $Roles
            userAttributes     = $UserAttributes
            phoneNumber        = $PhoneNumber
            employeeId         = $EmployeeId
            samAccountName     = $SamAccountName
        }
        
        foreach ($inputKey in $Attributes.Keys) {     
            if (![string]::IsNullOrEmpty($Attributes.$inputKey)) {
                if ($inputKey -eq "phoneNumber" -or $inputKey -eq "employeeId" -or $inputKey -eq "samAccountName") {
                    if ($userBody.userAttributes) {
                        $userBody.userAttributes += @{
                            "$inputKey" = $Attributes.$inputKey
                        }
                    }
                    else {
                        $userBody += @{
                            userAttributes = @{
                                "$inputKey" = $Attributes.$inputKey
                            } 
                        }
                    }
                }
                else {
                    $userBody += @{
                        "$inputKey" = $Attributes.$inputKey
                    }
                }
            }
        }
        $jsonUserBody = $userBody | ConvertTo-Json

        $user = New-Object PSCustomObject
        Invoke-HidWebRequest -Response ([Ref]$user) -Method Put -Uri $uri -Headers $Headers -Body ([System.Text.Encoding]::UTF8.GetBytes($jsonUserBody)) -ContentType "application/json"
        $Response.Value = $user
        if ($Logging) {
            Write-HidStatus -Message "Successfully updated HelloID user '$Username'" -Event Success
        }
    }
    catch {
        if ($_.Exception.Message -eq "The remote server returned an error: (400) Bad Request.") {
            $message = ($_.ErrorDetails.Message | ConvertFrom-Json).message
            Write-HidStatus -Message "Could not update HelloID user '$Username', errorcode: 'x$('{0:X8}' -f $_.Exception.HResult), message: $($_.Exception.Message) $message" -Event Error
        }
        else {
            Write-HidStatus -Message "Could not update HelloID user '$Username', errorcode: 'x$('{0:X8}' -f $_.Exception.HResult), message: $($_.Exception.Message)" -Event Error
        }
    }
}
 
 
<#------------- HelloID -------------#>
# HelloID API - Get Web request key
try {
    $key = New-Object PSCustomObject
    New-WebRequestKey -ApiKey $HelloIDApiKey -ApiSecret $HelloIDApiSecret -Response ([Ref]$key)
    $headers = @{ }
    $headers.Add("authorization", $key)
}
catch {
    throw $_
}

# HelloID API - Get HelloID users
try {
    $hidUsers = New-Object PSCustomObject
    Get-HIDUsers -PortalBaseUrl $portalBaseUrl -Headers $headers -UsernameFilter $HelloIDUsersFilter -Response ([Ref]$hidUsers)
    $hidUsers = foreach ($hidUser in $hidUsers) {
        if ($hidUser.isDeleted -eq $false) {
            $hidUser
        }
    }
}
catch {
    throw $_
}
 
[Int]$updatedHidUsers = 0
[Int]$skippedHidUsers = 0
[Int]$unchangedHidUsers = 0
try {
    foreach ($hidUser in $hidUsers) {
        if ($hidUser.userAttributes.objectGUID) {

            $bytearray = ([GUID]$hidUser.userAttributes.objectGUID).tobytearray()
            $immutableID = [system.convert]::ToBase64String($bytearray)
             
            if ($immutableID -ne $hidUser.userAttributes.AzureADImmutableId) {
                $userObject = @{ }
                $hidUser.psobject.properties | ForEach-Object { $userObject[$_.Name] = $_.Value }

                $userAttributes = @{ }
                $hidUser.userAttributes.PsObject.Properties | ForEach-Object { $userAttributes[$_.Name] = $_.Value }
                $userObject.userAttributes = $userAttributes

                # Remove unnecessary properties
                $userObject.Remove('ADSid')
                $userObject.Remove('userGUID')
                $userObject.Remove('immutableId')
                $userObject.Remove('Source')
                $userObject.Remove('Password')
                $userObject.Remove('passwordLastSetTime')
                $userObject.Remove('isLocked')
                $userObject.Remove('lockTime')
                $userObject.Remove('lastLogin')
                $userObject.Remove('isDeleted')
                $userObject.Remove('managedByUserGUID')

                #temp enable all users
                $userObject.isEnabled = $true

                if ($userObject.userAttributes.AzureADImmutableId) {
                    $userObject.userAttributes.AzureADImmutableId = $immutableID
                }
                else {
                    $userObject.userAttributes.Add("AzureADImmutableId", $immutableID)
                }

                $updatedHidUser = New-Object PSCustomObject
                Update-HIDUser @userObject -PortalBaseUrl $portalBaseUrl -Headers $headers -Response ([Ref]$updatedHidUser) -Logging:$false
                $updatedHidUsers++
            }
            else {
                $unchangedHidUsers++
            }
        }
        else {
            $skippedHidUsers++
        }
    }
    if ($skippedHidUsers -gt 0) {
        Write-HidStatus -Message "Skipped [$($skippedHidUsers)] user(s). There was no objectGuid found for these users" -Event Information
    }
    if ($unchangedHidUsers -gt 0) {
        Write-HidStatus -Message "Skipped [$($unchangedHidUsers)] user(s). Their immutableId has not changed" -Event Information
    }
    if ($updatedHidUsers -gt 0) {
        Write-HidStatus -Message "Updated [$($updatedHidUsers)] user(s). The objectGuid has been base64 encoded and set to the AzureADImmutableId" -Event Information
    }
    Write-HidStatus -Message "Finished sync of objectGuid to immutableId, processed [$($hidUsers.username.Count)] user(s)" -Event Success
    Write-HidSummary -Message "Successfully synchronized AzureAD ImmutableId to HelloID Users, processed [$($hidUsers.username.Count)] user(s)" -Event Success
}
catch {
    throw $_
}

A successful run should provide a progress log like the example below.

Do not forget to schedule this task after the Directory Synchronization task. Since the Directory sync is scheduled to run every day at 00:00 by default we have set the ImmutableId sync to be run every day at 01:00.

Changing the mapping set

Now we need to change {{user.userName}} to the HelloID attribute containing the immutableID of the AzureAD account, being {{user.attributes.objectguidbase64}}, remember this attribute is only available after you've run the Sync task.

Application metadata

After saving the Azure application, click its Edit link on the applications overview. This will bring you to its properties page.

Metadata (URL)

You can simply right-click Download metadata and copy the link address (something along the lines of https://enyoi.helloid.com/metadata/download?ApplicationGUID=e6e741f5-a469-4849-93f7-fe2e259a339f) at the right top of the screen.

Federate Microsoft Azure with HelloID

Open PowerShell ISE as Administrator