Configuring the Microsoft Active Directory integration

The Active Directory integration is capable of automatically creating, updating and disabling users from 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 BrightBooking from your server.

How it works

The integration-logic is available as a PowerShell module, via PowerShellGallery, as '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 Active Directory, filtered by your preferences, for example filtered by group membership
  2. These users are sent to BrightBooking and immediately created or updated
  3. If the user is deactivated in Active Directory, it will also be deactivated in BrightBooking
  4. Users that are not read from the Active Directory are also no updated in BrightBooking

Follow the steps below to install and configure the Active Directory integration.

Preparations

The BrightBookingUserAdminTools module has the following dependencies:

  • PowerShell version 5 or higher
  • The following PowerShell modules:
    • PowerShellGallery
    • ActiveDirectory
  • The machine (server) should be link 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. Install the ActiveDirectory PowerShell module:

Installation

Install the BrightBookingUserAdminTools PowerShell module:

Install-Module -Name BrightBookingUserAdminTools -Force

Configuration: determine how to filter the users

A best-practice is to create a 'BrightBooking' user group, and add users who need access to that group. This enables you to have detailed control.

With the '-Filter' and '-SearchBase' parameter you're able to filter which users will be synchronized to BrightBooking. The '-Filter' and '-SearchBase' parameters are explained on this Microsoft webpage.

Use the following example commands to test which filter you need:

  • Filter for users with username containing the word 'john':
    Get-ADUsersForBB -Filter 'samAccountName -like "*john*"' | Convert-ADUsersToBBUserExport
  • Filter for users in a specific Organizational Unit (OU):
    Get-ADUsersForBB -Filter * -SearchBase "OU=Office,DC=Company,DC=com" | Convert-ADUsersToBBUserExport
  • Filter for users which are member of a group in a specific Organizational Unit (OU):
    Get-ADUsersForBB -Filter { memberOf -RecursiveMatch "CN=Administrators,DC=Company,DC=com" } -SearchBase "OU=Office,DC=Company,DC=com" | Convert-ADUsersToBBUserExport

Now configure the filter you need, this will be needed in the last steps below.

Configuration: determine if you need a 'special' authentication username

When you configure the 'integration' (e.g. the Exchange or Office 365 integration), you will be able to choose if you use the email address as username, or you can configure to use another 'authentication username'. 

By default the email address is used as username for authentication, but in some cases you will need to use the DOMAIN\username or the UserPrincipalName (if this is different from the email address).

If you want to use DOMAIN\username or the UserPrincipalName, you will need the '-ADSpecificUsername' option, which can be 'DomainPlusUsername' or 'UserPrincipalName'.

If needed, use the following example commands to test which option you need:

  • Use [domain]\[username]:
    Get-ADUsersForBB -Filter 'samAccountName -like "*john*"' | Convert-ADUsersToBBUserExport -ADSpecificUsername DomainPlusUsername
  • Use the User Principal Name (UPN):
    Get-ADUsersForBB -Filter 'samAccountName -like "*john*"' | Convert-ADUsersToBBUserExport -ADSpecificUsername UserPrincipalName

Configuration: determine if you want to use a specific attribute of the user as pincode

In BrightBooking pincodes can be used on room displays and mapviewers as an easy way to authenticate yourself.

In some cases the organization already uses codes, for example a personnel number to identify users, which in that case can be used as a pincode. The number should consist only numbers.

If needed, use the following example commands to test the result:

  • Use ‘PersonnelNumber’ of the user as pincode:
    Get-ADUsersForBB -Filter 'samAccountName -like "*john*"' | Convert-ADUsersToBBUserExport -ADUserPincodePropertyName PersonnelNumber

Please note, in this case you will need to configure that users do not manage their own pincode (in general setting in the BrightBooking portal).

Configuration: get the BrightBooking API url and API key

To be able to synchronize the users, you need the following information in BrightBooking:

  • The BrightBooking 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 BrightBooking 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 BrightBooking 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.

Configure & test the Active Directory integration

With the steps above you have gathered all information to get a working integration.

Note: the commands below will actually add, update and deactivate users in BrightBooking, so you probably want to test this with just one specific user, before using it for all your users.

The command to get the information from Active Directory and process it in BrightBooking is:
Push-ADUsersToBB [filter] [optional: specifieke username/pincode veld] -BrightBookingApiUrl '[API url]' -BrightBookingApiKey '[API key]' -BrightBookingIntegrationName '[name of integration]'

Some example commands:

  • Process users with usernames containing the word ‘john’:
    Push-ADUsersToBB -Filter 'samAccountName -like "*john*"' -BrightBookingApiUrl '[API url]' -BrightBookingApiKey '[API key]' -BrightBookingIntegrationName 'Office 365'
  • 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" -BrightBookingApiUrl '[API url]' -BrightBookingApiKey '[API key]' -BrightBookingIntegrationName 'Office 365'
  • 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 'Office 365'

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: -File “[full path to the created .ps1 file]”
0 out of 0 found this helpful