Benutzer-Synchronisation mit Azure AD/Active Directory

Für das BrightBookingUserAdminTools-Modul gelten die folgenden Abhängigkeiten:

• PowerShell Version 5 oder höher
• Die folgenden PowerShell-Module:
  • PowerShellGallery
  • ActiveDirectory
  • Azure AD
• Der Rechner (Server) sollte in Ihrer Windows-Domäne eingebunden sein

Bitte folgen Sie den nächsten Schritten, um die Abhängigkeiten zu installieren:

1. Melden Sie sich an dem Rechner (Server) an, auf dem Sie den Task installieren möchten. (Dieser Rechner sollte mit der Windows-Domäne verbunden sein).
2. Starten Sie PowerShell auf diesem Computer als "administator":
   
3. Überprüfen Sie, ob PowerShell 5 installiert ist:
   • Führen Sie den folgenden Befehl aus:
     

     $PSVersionTable.PSVersion

   • In dem Ergebnis, das Sie erhalten, sollte der "Major" eine "5" oder höher sein.
   • Wenn die 'Major' niedriger ist als '5', befolgen Sie diese Schritte:
     • Installieren Sie Windows Management Framework 5 (dies beinhaltet PowerShell 5):
       Download Windows Management Framework 5
     • Hinweis 1: Wenn Sie die Fehlermeldung "Das Update ist nicht auf Ihren Computer anwendbar" erhalten, haben Sie wahrscheinlich den falschen Download ausgewählt; bitte lesen Sie diesen Artikel.
     • Hinweis 2: Windows Management Framework 5 hängt von .NET Framework 4.5 ab.
     • Hinweis 3: Ein Neustart ist wahrscheinlich erforderlich.
     • Nach der Installation überprüfen Sie bitte, ob die 'Major' ist '5' oder höher:
       

       $PSVersionTable.PSVersion

4. Installieren Sie das PowerShellGallery PowerShell-Modul:
   • Führen Sie die folgenden Befehle in PowerShell aus (als Administrator ausgeführt)
   • Installieren Sie den NuGet PackageProvider:
     

     Install-PackageProvider -Name NuGet -MinimumVersion 2.8.5.201 -Force

   • Konfigurieren Sie PowerShellGallery als vertrauenswürdige Quelle:
     

     Set-PSRepository -Name PSGallery -InstallationPolicy Trusted

   • Installieren Sie das PowerShellGet-Modul:
     

     Import-Module -Name PowerShellGet

5. Wenn Sie synchronisieren möchten mit Aktives Verzeichnis: Installieren Sie das ActiveDirectory PowerShell-Modul:
   • Das ActiveDirectory PowerShell-Modul ist ein Teil der Remote Server Administration Tools (RSAT).
   • Bitte befolgen Sie diese Schritte, um die Remote Server Administration Tools (RSAT) zu installieren
6. Wenn Sie synchronisieren möchten mit Azure AD: Installieren Sie das Azure AD PowerShell-Modul:
   • Führen Sie die folgenden Befehle in PowerShell aus (als Administrator ausgeführt)
   • Installieren Sie das Azure AD-Modul:
     

     Install-Module -Name AzureAD

Installieren oder aktualisieren Sie das BrightBookingUserAdminTools PowerShell-Modul:

Install-Module -Name BrightBookingUserAdminTools -Force

Der Befehl "-Force" sorgt dafür, dass die neueste Version des Moduls installiert wird, auch wenn eine frühere Installation vorhanden ist. Wenn das Modul bereits installiert war, muss die PowerShell-Sitzung neu gestartet werden.

Um die Benutzer synchronisieren zu können, müssen Sie die folgenden Informationen im GoBright Portal abrufen:

• Die API-URL und der API-Schlüssel
• Der Name der Integration, die mit den Benutzern verknüpft werden soll

Folgen Sie diesen Schritten, um die API-URL und den API-Schlüssel zu finden:

• Melden Sie sich mit einem Manager-Konto im Portal GoBright an.
• Gehen Sie zu Admin center > Integrationen > API-Zugang
• Erzeugen Sie einen API-Schlüssel über die Schaltfläche "Hinzufügen". Wählen Sie als Typ "Manager" und geben Sie eine Beschreibung für eine spätere Referenz ein
  • Hinweis: Bitte stellen Sie sicher, dass Sie den API-Schlüssel speichern, da es keine Möglichkeit gibt, ihn wiederherzustellen.
• Die "API-URL" ist Ihre GoBright Umgebungs-URL, die Sie in der URL-Leiste Ihres Browsers und unter Admin-Center > Integrationen > API-Zugang finden: API url https://[tenant-id].gobright.cloud/

Gehen Sie folgendermaßen vor, um den Namen der Integration zu ermitteln:

• Melden Sie sich mit einem Manager-Konto im Portal GoBright an.
• Gehen Sie zu Admin center > Integrationen
• Kopieren Sie den Namen der Integration (Exchange/Office 365), mit der die Benutzer verknüpft werden sollen

In den nächsten Schritten werden der Name der Integration, die API-URL und der API-Schlüssel benötigt.

Im letzten Schritt erstellen Sie das eigentliche Skript, um dem GoBright PowerShell-Modul mitzuteilen, welche Benutzer Sie abrufen und in Ihre GoBright Umgebung übertragen möchten. Dies kann mit Azure AD oder Active Directory durchgeführt werden.

[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12 
$ErrorActionPreference = "Stop"

Wählen Sie eine der folgenden Erklärungen für das Skript aus, die auf Ihre Situation zutrifft.

Schritt 4.1: Verbinden Sie sich mit Ihrem Azure AD

Starten Sie PowerShell und verbinden Sie sich mit Ihrem Azure AD über den Standardbefehl "Connect-AzureAD".

Schritt 4.2: Testen Sie die Auswahl der Benutzer

Der Befehl zum Abrufen der Informationen aus Active Directory und zur Verarbeitung in BrightBooking lautet:

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 Admin center > Integrations]'

Sie können die folgenden Parameter in dem Befehl "Push-AzureADUsersToBB" verwenden:

Nachfolgend finden Sie einige Beispielbefehle, die Sie nach Bedarf an Ihre Situation anpassen können.

Diese Befehle aktualisieren die Benutzer im System noch nicht, es handelt sich also um Testbefehle, da sie den Parameter "-WhatIf" enthalten.

Beispiel für Testbefehle:

Verarbeiten Sie alle Benutzer im Azure AD auf GoBright:

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

Verarbeiten Sie Benutzer mit UPN's, die mit 'yourdomain.com' enden, auf 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 Admin center > Integrations]' -WhatIf

Verarbeiten Sie Benutzer mit einer NFC-ID und einem Pincode in einem benutzerdefinierten Attribut. Beachten Sie, dass der Name des Erweiterungsattributs mit dem in Azure AD identisch sein muss:

$users_all_import = Get-AzureADUser -All $true [optional: filter]
 $users_all = @()


 $pincodeField = '[Extension attribute here]'


 $NFCField = '[Extension attribute here]'


 Foreach ($user in $users_all_import) {

 $getExtensionProperty = $user | Select-Object -ExpandProperty ExtensionProperty

 If ($getExtensionProperty.$pincodeField) {

 $pin = (Get-AzureADUserExtension -ObjectId $user.ObjectId).get_item($pincodeField)

 } Else {

 $pin = ''

 }


 If ($getExtensionProperty.$NFCField) {

 $nfc = (Get-AzureADUserExtension -ObjectId $user.ObjectId).get_item($NFCField)

 } Else {

 $nfc = ''

 }


 $user | Add-Member UserPincode $pin -Force

 $user | Add-Member UserNFC $nfc -Force

 $users_all += $user

 }


 $users_all | Push-AzureADUsersToBB -ADUserPincodePropertyName UserPincode -ADUserNFCIdPropertyName UserNFC -BrightBookingApiUrl '[API url]' -BrightBookingApiKey '[API key]' -BrightBookingIntegrationName '[name of integration as created in Admin center > Integrations]' -WhatIf

Verarbeiten Sie Benutzer und fügen Sie die Benutzerrollen innerhalb von GoBright basierend auf ihrer Gruppenmitgliedschaft in Azure AD hinzu:

$groupToRoleMapping = @()
 $groupToRoleMapping += @ # match specific users that belong to a group for Meet-Work-Visit
 $groupToRoleMapping += @ # match specific users that belong to a group for Meet-Work-Visit
 $groupToRoleMapping += @ # match specific users that belong to a group for Meet-Work-Visit
 $groupToRoleMapping += @ # match specific users that belong to a group for View

 $groupToRoleMapping += @ # **special case** this line matches for every user, because of the 'MatchType', and is needed when you want to have a generic role for every user

 $roleNameDefaultIfNoGroupMatched = "Regular user"


 $users_all = Get-AzureADUser -All $true
 $users_all | Push-AzureADUsersToBB -UserDefaultRoleName $roleNameDefaultIfNoGroupMatched -GroupUserRoleMapping $groupToRoleMapping -BrightBookingApiUrl '[API url]' -BrightBookingApiKey '[API key]' -BrightBookingIntegrationName '[name of integration as created in Admin center > Integrations]' -WhatIf

Verarbeiten Sie alle Benutzer außer denen, die Mitglied einer bestimmten Gruppe in Azure AD sind:

$excludedGroups = @()
 $excludedGroups += '[GroupName1]'
 $excludedGroups += '[GroupName2]'
 $excludedGroups += '[GroupName3]'
 $ADGroups = Get-AzureADGroup -All $true | Where-Object { $excludedGroups -notcontains $_.DisplayName }
 $users_all = $ADGroups | Get-AzureADGroupMember -All $true
 $users_all | Push-AzureADUsersToBB -BrightBookingApiUrl '[API url]' -BrightBookingApiKey '[API key]' -BrightBookingIntegrationName '[name of integration as created in Admin center > Integrations]' -WhatIf

Schritt 4.2: Ausführen der eigentlichen Synchronisierung

Sobald die Liste der Benutzer korrekt gefiltert ist, können Sie die eigentliche Synchronisierung durchführen, indem Sie den Parameter "-WhatIf" entfernen.

Führen Sie nun denselben Befehl aus, aber ohne "-WhatIf", und die Benutzer werden in Ihrer Umgebung GoBright verarbeitet.

Schritt 4.3: Planen Sie die regelmäßige Ausführung der Integration über den Windows-Taskplaner

Um das Skript unbeaufsichtigt ausführen zu können, sollten Sie sich irgendwie automatisch anmelden.

Empfohlene Methode für die unbeaufsichtigte Anmeldung:
Die empfohlene Methode für die unbeaufsichtigte Anmeldung ist die Erstellung einer registrierten Anwendung in Azure AD und die Verbindung mit dieser Anwendung:

#script for creating user, cert, and get tenantid #getting data for daily script
 Connect-AzureAD $pwd = "Password to encrypt the cert" $subject = "GoBright_unattendedlogin" # may not be longer than 15 characters = the name certificate and app $tmppath = "C:tmp" $certname= "unattendedlogin_azuread.pfx" $fullcertpath = "C:tmpunattendedlogin.pfx" $IdentifierUris = "https://www.fillInYourOwnDomain.com" # Here you need to fill in your own domain name
 $thumb = (New-SelfSignedCertificate -CertStoreLocation Cert:CurrentUserMy -subject $subject -KeyExportPolicy Exportable -NotAfter (Get-Date).AddYears(10) -Type CodeSigningCert -KeySpec Signature).Thumbprint $pwd = ConvertTo-SecureString -String $pwd -Force -AsPlainText if ($tmppath -eq $false) Export-PfxCertificate -cert "cert:CurrentUsermy$thumb" -FilePath $fullcertpath -Password $pwd
 $cert = New-Object System.Security.Cryptography.X509Certificates.X509Certificate($fullcertpath, $pwd) $keyValue = [System.Convert]::ToBase64String($cert.GetRawCertData())
 $application = New-AzureADApplication -DisplayName $subject -IdentifierUris $IdentifierUris New-AzureADApplicationKeyCredential -ObjectId $application.ObjectId -CustomKeyIdentifier $subject -Type AsymmetricX509Cert -Usage Verify -Value $keyValue $sp=New-AzureADServicePrincipal -AppId $application.AppId Add-AzureADDirectoryRoleMember -ObjectId (Get-AzureADDirectoryRole | where-object {$_.DisplayName -eq "Directory Readers"}).Objectid -RefObjectId $sp.ObjectId
 $tenantid = Get-AzureADTenantDetail | Select ObjectId -ExpandProperty ObjectId $appid = $application.AppId $thumb $tenantid $appid
 #copy data from thumb, tenantid, appid to daily user sync script

Für weitere Informationen klicken Sie bitte auf diesen Link.

Zu Testzwecken können Sie die folgende Methode verwenden, um sich automatisch mit der unbeaufsichtigten Anmeldemethode bei Ihrem Azure AD anzumelden und Ihr Skript zu testen, bevor Sie das eigentliche Skript zur Benutzersynchronisierung ausführen:

$tenantid = "[fill in your tenant id from the output of the first script]" $thumb = "[fill in your thumb id from the output of the first script]" $appid = "[fill in your appid from the output of the first script]"
 Connect-AzureAD -TenantId $tenantid -ApplicationId $appid -CertificateThumbprint $thumb
 [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12 $ErrorActionPreference = "Stop"
 $users_all = Get-AzureADUser -All $true | Where-Object {$_.userprincipalname -like "*someDomainname.com"} $users_all | Push-AzureADUsersToBB -UserDefaultRoleName $roleNameDefaultIfNoGroupMatched -GroupUserRoleMapping $groupToRoleMapping -DeactivateExistingUsersInSameIntegrationThatAreNotLoaded -BrightBookingApiUrl '[API url]' -BrightBookingApiKey '[API key]' -BrightBookingIntegrationName '[name of integration as created in Admin center > Integrations]' -WhatIf

Schritt 4.1: Testen Sie die Auswahl der Benutzer

Der Befehl zum Abrufen der Informationen aus Active Directory und deren Verarbeitung in GoBright lautet:

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

Sie können die folgenden Parameter in dem Befehl "Push-ADUsersToBB" verwenden:

Nachfolgend finden Sie einige Beispielbefehle, die Sie nach Bedarf an Ihre Situation anpassen können.

Diese Befehle aktualisieren die Benutzer im System noch nicht, es handelt sich also um Testbefehle, da sie den Parameter "-WhatIf" enthalten.

Beispiel für Testbefehle:

Verarbeiten Sie Benutzer mit UPNs, die auf "yourdomain.com" enden:

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

Verarbeiten Sie Benutzer mit UPNs, die mit "yourdomain.com" enden, und verwenden Sie das Feld "PersonnelNumber" in ActiveDirectory als Pincode für die Benutzer:

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

Benutzer bearbeiten, die Mitglieder einer bestimmten Gruppe in einer OU (Organisationseinheit) sind:

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 Admin center > Integrations]' -WhatIf

Verarbeiten Sie Benutzer, die Mitglieder einer bestimmten Gruppe in einer OU (Organisationseinheit) sind, und legen Sie eine bestimmte Rolle auf der Grundlage ihrer Gruppenmitgliedschaft fest:

$groupToRoleMapping = @()

 $groupToRoleMapping += @ # match specific users that belong to a group
 $groupToRoleMapping += @ # match specific users that belong to a group
 $groupToRoleMapping += @ # match specific users that belong to a group to a role of View
 $groupToRoleMapping += @ # **special case** this line matches for every user, because of the 'MatchType', and is needed when you want to have a generic role for every user
 $roleNameDefaultIfNoGroupMatched = "Regular user"
 Push-ADUsersToBB -Filter { memberOf -RecursiveMatch "CN=OfficeUsers,DC=Company,DC=com" } -SearchBase "OU=Office,DC=Company,DC=com" -ADUserPincodePropertyName PersonnelNumber -UserDefaultRoleName $roleNameDefaultIfNoGroupMatched -GroupUserRoleMapping $groupToRoleMapping -BrightBookingApiUrl '[API url]' -BrightBookingApiKey '[API key]' -BrightBookingIntegrationName '[name of integration as created in Admin center > Integrations]' -WhatIf

Verarbeitet Benutzer, die Mitglieder einer bestimmten Gruppe in einer OU (Organisationseinheit) sind, mit [Domäne][Benutzername] als Authentifizierungsbenutzername:

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 Admin center > Integrations]' -WhatIf

In einem Beispiel, in dem Sie mit zwei verschiedenen Active Directory-Tenants arbeiten, diese aber mit einer GoBright Umgebung verknüpfen müssen, können Sie das folgende Beispielskript verwenden:

Beachten Sie, dass das folgende Skript die Anweisung -WhatIf nicht unterstützt. Wenn Sie dieses Skript ausführen, werden die Benutzer von Ihrem Active Directory auf GoBright übertragen.

[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12

 $ErrorActionPreference = "Stop"
 $ADUsersProperties = @("SamAccountName","DistinguishedName","DisplayName","ProxyAddresses","Mail","MemberOf")

 If ($ADUserPincodePropertyName)
 {
 $ADUsersProperties += $ADUserPincodePropertyName 
$ConvertUsersParams.ADUserPincodePropertyName = $ADUserPincodePropertyName
 } 

 If ($ADUserNamePropertyName)
 {
 $ADUsersProperties += $ADUserNamePropertyName
 $ConvertUsersParams.ADUserNamePropertyName = $ADUserNamePropertyName
 }

 If ($ADUserMobilePropertyName)
 {
 $ADUsersProperties += $ADUserMobilePropertyName
 $ConvertUsersParams.ADUserMobilePropertyName = $ADUserMobilePropertyName
 }

 If ($ADUserNFCIdPropertyName)
 {
 $ADUsersProperties += $ADUserNFCIdPropertyName
 $ConvertUsersParams.ADUserNFCIdPropertyName = $ADUserNFCIdPropertyName
 }

 If ($ADUserDefaultCostCenterIdOrNamePropertyName)
 {
 $ADUsersProperties += $ADUserDefaultCostCenterIdOrNamePropertyName
 $ConvertUsersParams.ADUserDefaultCostCenterIdOrNamePropertyName = $ADUserDefaultCostCenterIdOrNamePropertyName
 }

 $groupToRoleMapping = @()
 $groupToRoleMapping += @
 $groupToRoleMapping += @ # **special case** this line matches for every user, because of the 'MatchType', and is needed when you want to have a generic role for every user

 

 #Get users from OU1 / or when adding -Server YourServername1.local from AD 1
 $users1 = Get-ADUser -Filter 'UserPrincipalName -like "*yourdomain.com"' -SearchBase "OU=Office-Sales,DC=Company,DC=com" -Properties $ADUsersProperties | Select-Object *
 -ADSpecificUsername DomainPlusUsername -BrightBookingApiKey '[API key]' -BrightBookingIntegrationName '[name of integration as created in Admin center > Integrations]'

 #Get users from OU1 / or when adding -Server YourServername2.local from AD 2
 $users2 = Get-ADUser -Filter 'UserPrincipalName -like "*yourdomain.com"' -SearchBase "OU=Office-Marketing,DC=Company,DC=com" -Properties $ADUsersProperties | Select-Object *
 -ADSpecificUsername DomainPlusUsername -BrightBookingApiUrl '[API url]' -BrightBookingApiKey '[API key]' -BrightBookingIntegrationName '[name of integration as created in Admin center > Integrations]'

 

 # merge the users to one list
$users_all = $users1 + $users2

 

 # Filter so we only get user objects
 $users_all = $users_all | Where-Object {$_.ObjectClass -eq "user"}
 $convertedUsers = $users_all | Convert-ADUsersToBBUserExport -GroupUserRoleMapping $groupToRoleMapping -ADSpecificUsername UserPrincipalName -UserDefaultRoleName "Default User Role"
 $convertedUsers

 

#Send users to GoBright
 Send-ADUsersToBB -pipelineConvertedADUsers $convertedUsers -DeactivateExistingUsersInSameIntegrationThatAreNotLoaded -BrightBookingApiUrl '[API url]' -BrightBookingApiKey '[API key]' -BrightBookingIntegrationName '[name of integration as created in Admin center > Integrations]'

Schritt 4.2: Ausführen der eigentlichen Synchronisierung

Sobald die Liste der Benutzer korrekt gefiltert ist, können Sie die eigentliche Synchronisierung durchführen, indem Sie den Parameter "-WhatIf" entfernen.

Führen Sie nun denselben Befehl aus, aber ohne "-WhatIf", und die Benutzer werden in Ihrer Umgebung GoBright verarbeitet.

Schritt 4.3: Planen Sie die regelmäßige Ausführung der Integration über den Windows-Taskplaner

Führen Sie die folgenden Schritte aus, um die Benutzer nach einem bestimmten Zeitplan aus Active Directory zu synchronisieren:

• Nehmen Sie den Befehl, den Sie verfasst haben (siehe vorherige Schritte), und speichern Sie ihn in einer .ps1-Datei:
  • Erstellen Sie eine .ps1-Datei (z. B. UsersToBrightBooking.ps1) in einem Ordner Ihrer Wahl
  • Öffnen Sie die Datei mit einem Editor, z. B. 'notepad'.
  • Fügen Sie den vollständigen Befehl in die Datei ein
  • Speichern Sie die Datei
• Führen Sie die Datei aus, um zu sehen, ob sie erfolgreich ist.
• Erstellen Sie eine Aufgabe in der Windows-Aufgabenplanung:
  • Windows-Aufgabenplaner öffnen
  • Eine Aufgabe erstellen
  • Legen Sie einen Zeitplan fest, z. B. einmal pro Tag oder alle 4 Stunden
  • Hinzufügen einer Aktion 'Programm starten':
    • Programm/Skript:
      Powershell.exe
    • Parameter:
      -windowstyle minimized -c "powershell -c .[Name der erstellten .ps1-Datei] -verbose >> ExportToGoBright_Output.txt 2>&1″
    • Start in:
      Geben Sie unter "Start in" den Speicherort des Skripts ein, z. B:C:Skripte