Configuring the AzureAD / Active Directory synchronization

The AzureAD / Active Directory synchronization is capable of automatically creating, updating and disabling users from AzureAD or Active Directory.

We have created the 'BrightBookingUserAdminTools' PowerShell module, which handles this logic. By creating a (planned) task with the right PowerShell commands, you can push this information regularly to GoBright from your server.

Introduction

The integration-logic is available as a PowerShell module, via PowerShellGallery, as 'BrightBookingUserAdminTools'.

Install-Module -Name BrightBookingUserAdminTools

The 'BrightBookingUserAdminTools' PowerShell module should be installed on a machine (server) in your domain.

When configured it follows the following steps, each time it runs:

  1. Get the users from AzureAD or Active Directory, filtered by your preferences, for example filtered by group membership
  2. These users are sent to GoBright and immediately created or updated
  3. If the user is deactivated in AzureAD or Active Directory, it will also be deactivated in GoBright
  4. Users that are not read from the AzureAD or Active Directory are also no updated in GoBright

Follow the steps below to install and configure the integration.

Step 1: Install required PowerShell modules

The BrightBookingUserAdminTools module has the following dependencies:

  • PowerShell version 5 or higher
  • The following PowerShell modules:
    • PowerShellGallery
    • ActiveDirectory
    • AzureAD
  • The machine (server) should be linked in your Windows domain

Please follow the next steps to install the dependencies:

  1. Log in to the machine (server) where you want to install the task. (this machine should by linked in the Windows domain).
  2. Start PowerShell on that machine, as 'administator':
    clip0001-279x300.jpg
  3. Check if PowerShell 5 is installed:
    • Execute the following command:
      $PSVersionTable.PSVersion
    • In the result you get, the 'Major' should be '5' or higher.
    • If the 'Major' is lower than '5', follow these steps:
      • Install Windows Management Framework 5 (this includes PowerShell 5):
        Download Windows Management Framework 5
      • Note 1: if you get the error 'The update is not applicable to your computer' you probably selected the wrong download, please refer to this article.
      • Note 2: Windows Management Framework 5 depends on .NET Framework 4.5.
      • Note 3: Reboot is probably required.
      • After installation please check if the 'Major' is '5' or higher:
        $PSVersionTable.PSVersion
  4. Install the PowerShellGallery PowerShell module:
    • Execute the following commands in PowerShell (running as administrator)
    • Install the NuGet PackageProvider:
      Install-PackageProvider -Name NuGet -MinimumVersion 2.8.5.201 -Force
    • Configure PowerShellGallery as a trusted source:
      Set-PSRepository -Name PSGallery -InstallationPolicy Trusted
    • Install the PowerShellGet module:
      Import-Module -Name PowerShellGet
  5. If you want to synchronize with Active Directory: Install the ActiveDirectory PowerShell module:
  6. If you want to synchronize with AzureAD: Install the AzureAD PowerShell module:
    • Execute the following commands in PowerShell (running as administrator)
    • Install the AzureAD module:
      Install-Module -Name AzureAD

Step 2: Installation of the synchonization module

Install the BrightBookingUserAdminTools PowerShell module:

Install-Module -Name BrightBookingUserAdminTools -Force

Step 3: Configuration: get the API url and API key

To be able to synchronize the users, you need to get the following information in the GoBright Portal:

  • The API url and API key
  • The name of the integration which should be linked to the users 

Follow these steps to find the API url and API key:

  • Log in with a manager user in the GoBright portal
  • Go to Settings > General settings
  • Activate 'Enable API access'
  • Generate an API key with type 'manager' and enter a description for later reference
    • Note: please make sure you save the API key, as there is no way to recover it
  • Copy the 'API url' for later reference

Follow these steps to find the name of the integration:

  • Log in with a manager user in the GoBright portal
  • Go to Settings > Integrations
  • Copy the name of the integration (Exchange/Office 365) which should be used to link the users to

The name of the integration, the API url and API key are needed in the next steps.

Step 4: Configure the synchronization PowerShell script

Script for Active Directory synchronization

Step 4.1: Test the selection of users

The command to get the information from Active Directory and process it in BrightBooking is:

Push-ADUsersToBB [filter] [optional: specific username/pincode field] -BrightBookingApiUrl '[API url]' -BrightBookingApiKey '[API key]' -BrightBookingIntegrationName '[name of integration as created in Settings > Integrations]'

You can use the following parameters in the 'Push-ADUsersToBB' command:

-Filter
(required)
The filtercondition to filter the users you want to synchronize (more documentation available)
-SearchBase
(optional)
Specifies the Active Directory path the search under (more documentation available)

-ADSpecificUsername
(optional)





 

By default the user will authenticate with the primary e-mailaddress of the user to the Microsoft Exchange Server or Office365.

Provide these values to use a different way of authenticating of the user to the Microsoft Exchange Server or Office365:
DomainPlusUsername to use DOMAIN\username
UserPrincipalName to use the UPN

-ADUserPincodePropertyName
(optional)
Specify an fieldname of a field in Active Directory which you want to use as a 'pincode' (has to be numeric, minimum of 4 digits, and has to be unique)
-ADUserMobilePropertyName
(optional)
Specify an fieldname of a field in Active Directory which you want to use to get the mobile phonenumber of the users (e.g. for notification of the digital reception)
Will use the standard 'Mobile' field by default.
-BrightBookingApiUrl
(required)
The API url, as found in step 3
-BrightBookingApiKey
(required)
The API url, as found in step 3
-BrightBookingIntegrationName
(required)
The API url, as found in step 3
-WhatIf
(optional)
Use the '-WhatIf' parameter to only test and see, but not actually send data to your GoBright environment

 

Below you can find several example commands, you can adjust them the way you need to fit your situation.

There commands will not yet actually update users in the system, so these are test commands, because the include the '-WhatIf' parameter.

Example test commands:

Process users with UPN's ending with 'yourdomain.com':

Push-ADUsersToBB -Filter 'UserPrincipalName -like "*yourdomain.com"' -BrightBookingApiUrl '[API url]' -BrightBookingApiKey '[API key]' -BrightBookingIntegrationName '[name of integration as created in Settings > Integrations]' -WhatIf

Process users with UPN's ending with 'yourdomain.com', and using the 'PersonnelNumber' field in ActiveDirectory as pincode for the users:

Push-ADUsersToBB -Filter 'UserPrincipalName -like "*yourdomain.com"' -ADUserPincodePropertyName PersonnelNumber -BrightBookingApiUrl '[API url]' -BrightBookingApiKey '[API key]' -BrightBookingIntegrationName '[name of integration as created in Settings > Integrations]' -WhatIf

Process users which are members of a specific group in an OU (Organizational Unit):

Push-ADUsersToBB -Filter { memberOf -RecursiveMatch "CN=Administrators,DC=Company,DC=com" } -SearchBase "OU=Office,DC=Company,DC=com" -ADUserPincodePropertyName PersonnelNumber -BrightBookingApiUrl '[API url]' -BrightBookingApiKey '[API key]' -BrightBookingIntegrationName '[name of integration as created in Settings > Integrations]' -WhatIf

Process users which are members of a specific group in an OU (Organizational Unit), with [domain]\[username] as authentication username:

Push-ADUsersToBB -Filter { memberOf -RecursiveMatch "CN=Administrators,DC=Company,DC=com" } -SearchBase "OU=Office,DC=Company,DC=com" -ADSpecificUsername DomainPlusUsername -BrightBookingApiUrl '[API url]' -BrightBookingApiKey '[API key]' -BrightBookingIntegrationName '[name of integration as created in Settings > Integrations]' -WhatIf

Step 4.2: Run the actual synchronization

Once the list of users is correctly filtered, you can execute the real synchronization by removing the '-WhatIf' parameter.

So now execute the same command, but without '-WhatIf' and it will process the users to your GoBright environment.

Step 4.3: Schedule the integration to run periodically via Windows task scheduler

Follow these steps to synchronize the users from Active Directory on a schedule:

  • Take the command you've composed (see previous steps), and save it in a .ps1 file:
    • Create a .ps1 file (e.g. UsersToBrightBooking.ps1) in a folder you prefer
    • Open the file with an editor, for example 'notepad'
    • Paste the full command into the file
    • Save the file
  • Execute the file to see if it is successfull
  • Create a task in the Windows task scheduler:
    • Open Windows task scheduler
    • Create a task
    • Set a schedule, for example once a day, or every 4 hours
    • Add an action 'Start a program':
      • Program/script:
        Powershell.exe
      • Parameters: 
        -windowstyle minimized -c "powershell -c .\[Name of the created .ps1 file] -verbose >> ExportToGoBright_Output.txt 2>&1"
      • Start in:
        Fill the 'start in' with the location of the script, e.g.: C:\scripts\

 

Script for AzureAD synchronization

Step 4.1: Connect to your AzureAD

Start PowerShell, and connect to your AzureAD via the standard 'Connect-AzureAD' command.

Step 4.2: Test the selection of users

The command to get the information from Active Directory and process it in BrightBooking is:

Get-AzureADUser -All $true [optional: filter] | Push-AzureADUsersToBB [optional: specific username/pincode field] -BrightBookingApiUrl '[API url]' -BrightBookingApiKey '[API key]' -BrightBookingIntegrationName '[name of integration as created in Settings > Integrations]'

You can use the following parameters in the 'Push-AzureADUsersToBB' command:

-ADUserPincodePropertyName
(optional)

Specify an fieldname of a field in Active Directory which you want to use as a 'pincode' (has to be numeric, minimum of 4 digits, and has to be unique)
-ADUserMobilePropertyName
(optional)


Specify an fieldname of a field in Active Directory which you want to use to get the mobile phonenumber of the users (e.g. for notification of the digital reception)
Will use the standard 'Mobile' field by default.
-BrightBookingApiUrl
(required)
The API url, as found in step 3
-BrightBookingApiKey
(required)
The API url, as found in step 3
-BrightBookingIntegrationName
(required)
The API url, as found in step 3
-WhatIf
(optional)
Use the '-WhatIf' parameter to only test and see, but not actually send data to your GoBright environment

 

Below you can find several example commands, you can adjust them the way you need to fit your situation.

There commands will not yet actually update users in the system, so these are test commands, because the include the '-WhatIf' parameter.

Example test commands:

Process all users in the AzureAD to GoBright:

Get-AzureADUser -All $true | Push-AzureADUsersToBB -BrightBookingApiUrl '[API url]' -BrightBookingApiKey '[API key]' -BrightBookingIntegrationName '[name of integration as created in Settings > Integrations]' -WhatIf

Process users with UPN's ending with 'yourdomain.com' to GoBright:

Get-AzureADUser -All $true | where {$_.userprincipalname -like "*yourdomain.com"} | Push-AzureADUsersToBB -BrightBookingApiUrl '[API url]' -BrightBookingApiKey '[API key]' -BrightBookingIntegrationName '[name of integration as created in Settings > Integrations]' -WhatIf

Step 4.2: Run the actual synchronization

Once the list of users is correctly filtered, you can execute the real synchronization by removing the '-WhatIf' parameter.

So now execute the same command, but without '-WhatIf' and it will process the users to your GoBright environment.

Step 4.3: Schedule the integration to run periodically via Windows task scheduler

To be able to run the script unattended you should somehow login automatically.

Advised unattended login method:
The advised way to do unattended login, is by creating an registered app in Azure AD, and connect to that app: Follow this guide to do so.

For testing purposes you could use the following way to automatically login to your AzureAD:

$username = "[username to use]" 
$password = "[password to use]"
[SecureString]$securePass = ConvertTo-SecureString $password -AsPlainText -Force
[System.Management.Automation.PSCredential]$psCredentials = New-Object System.Management.Automation.PSCredential($username, $securePass)
Connect-AzureAD -Credential $psCredentials

 

Next, follow these steps to synchronize the users from Active Directory on a schedule:

  • Take the command you've composed (see previous steps), and save it in a .ps1 file:
    • Create a .ps1 file (e.g. UsersToBrightBooking.ps1) in a folder you prefer
    • Open the file with an editor, for example 'notepad'
    • Paste the login script to automatically login to your AzureAD
    • Paste the full command into the file
    • Save the file
  • Execute the file to see if it is successfull
  • Create a task in the Windows task scheduler:
    • Open Windows task scheduler
    • Create a task
    • Set a schedule, for example once a day, or every 4 hours
    • Add an action 'Start a program':
      • Program/script:
        Powershell.exe
      • Parameters: 
        -windowstyle minimized -c "powershell -c .\[Name of the created .ps1 file] -verbose >> ExportToGoBright_Output.txt 2>&1"
      • Start in:
        Fill the 'start in' with the location of the script, e.g.: C:\scripts\

 

 

 

1 out of 1 found this helpful