Sincronizzazione degli utenti con Azure AD/Active Directory

Il modulo BrightBookingUserAdminTools ha le seguenti dipendenze:

• PowerShell versione 5 o superiore
• I seguenti moduli PowerShell:
  • Galleria PowerShell
  • ActiveDirectory
  • Azure AD
• La macchina (server) deve essere collegata al dominio Windows.

Seguire i passi successivi per installare le dipendenze:

1. Accedere al computer (server) in cui si desidera installare il task. (questa macchina deve essere collegata al dominio Windows).
2. Avviare PowerShell su quella macchina, come 'amministratore':
   
3. Verificare se PowerShell 5 è installato:
   • Eseguire il seguente comando:
     

     $PSVersionTable.PSVersion

   • Nel risultato ottenuto, il valore "Maggiore" dovrebbe essere "5" o superiore.
   • Se l'opzione 'Maggiore' è inferiore a '5', seguite la seguente procedura:
     • Installare Windows Management Framework 5 (che include PowerShell 5):
       Scaricare Windows Management Framework 5
     • Nota 1: se viene visualizzato l'errore "L'aggiornamento non è applicabile al computer in uso", probabilmente è stato selezionato il download sbagliato; consultare questo articolo.
     • Nota 2: Windows Management Framework 5 dipende da .NET Framework 4.5.
     • Nota 3: probabilmente è necessario un riavvio.
     • Dopo l'installazione, verificare se la casella 'Maggiore' è '5' o superiore:
       

       $PSVersionTable.PSVersion

4. Installare il modulo PowerShellGallery di PowerShell:
   • Eseguire i seguenti comandi in PowerShell (eseguiti come amministratore)
   • Installare NuGet PackageProvider:
     

     Install-PackageProvider -Name NuGet -MinimumVersion 2.8.5.201 -Force

   • Configurare PowerShellGallery come fonte affidabile:
     

     Set-PSRepository -Name PSGallery -InstallationPolicy Trusted

   • Installare il modulo PowerShellGet:
     

     Import-Module -Name PowerShellGet

5. Se si desidera sincronizzare con Active Directory: Installare il modulo PowerShell di ActiveDirectory:
   • Il modulo PowerShell di ActiveDirectory fa parte di Remote Server Administration Tools (RSAT).
   • Per installare gli Strumenti di amministrazione del server remoto (RSAT), procedere come segue
6. Se si desidera sincronizzare con Azure AD: Installare il modulo Azure AD PowerShell:
   • Eseguire i seguenti comandi in PowerShell (eseguiti come amministratore)
   • Installare il modulo Azure AD:
     

     Install-Module -Name AzureAD

Installare o aggiornare il modulo PowerShell BrightBookingUserAdminTools:

Install-Module -Name BrightBookingUserAdminTools -Force

Il comando '-Force' assicura che venga installata l'ultima versione del modulo anche se esiste un'installazione precedente. Se il modulo era già installato, sarà necessario riavviare la sessione PowerShell.

Per poter sincronizzare gli utenti, è necessario ottenere le seguenti informazioni nel portale GoBright :

• L'URL e la chiave API
• Il nome dell'integrazione che deve essere collegata agli utenti

Seguite questi passaggi per trovare l'URL e la chiave API:

• Accedere con un account manager al portale GoBright .
• Accedere a Centro amministrativo > Integrazioni > Accesso API
• Generare una chiave API tramite il pulsante "Aggiungi". Scegliere come tipo "manager" e inserire una descrizione per un riferimento successivo.
  • Nota: assicurarsi di salvare la chiave API, poiché non c'è modo di recuperarla.
• L'"URL API" è l'URL dell'ambiente GoBright che si trova nella barra degli URL del browser e in Admin center > Integrazioni > Accesso API: URL API https://[tenant-id].gobright.cloud/

Seguite questi passaggi per trovare il nome dell'integrazione:

• Accedere con un account manager al portale GoBright .
• Andare al Centro amministrativo > Integrazioni
• Copiare il nome dell'integrazione (Exchange/Office 365) che deve essere utilizzata per collegare gli utenti a

Il nome dell'integrazione, l'URL API e la chiave API sono necessari nei passaggi successivi.

Nell'ultimo passaggio si costruirà lo script vero e proprio per dire al modulo PowerShell GoBright quali utenti si vogliono ottenere e inviare all'ambiente GoBright . Questo può essere fatto con Azure AD o Active Directory.

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

Scegliete una delle spiegazioni del copione che si applica alla vostra situazione.

Passo 4.1: Connettersi ad Azure AD

Avviare PowerShell e connettersi ad Azure AD tramite il comando standard "Connect-AzureAD".

Fase 4.2: Test della selezione degli utenti

Il comando per ottenere le informazioni da Active Directory ed elaborarle in BrightBooking è:

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]'

È possibile utilizzare i seguenti parametri nel comando 'Push-AzureADUsersToBB':

Di seguito sono riportati alcuni esempi di comandi, che possono essere adattati alla situazione in cui ci si trova.

Questi comandi non aggiornano ancora gli utenti nel sistema, quindi sono comandi di prova, perché includono il parametro "-WhatIf".

Esempi di comandi di prova:

Elaborare tutti gli utenti di Azure AD su GoBright:

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

Elaborare gli utenti con UPN che terminano con 'yourdomain.com' a 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

Elaborare gli utenti con un ID NFC e un Pincode in un attributo personalizzato, tenendo presente che il nome dell'attributo di estensione deve essere identico a quello di Azure AD:

$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

Elaborare gli utenti e aggiungere i ruoli utente all'interno di GoBright in base all'appartenenza ai gruppi in Azure AD:

$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

Elabora tutti gli utenti tranne quelli che sono membri di un gruppo specifico in Azure AD:

$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

Passo 4.2: Eseguire la sincronizzazione vera e propria

Una volta filtrato correttamente l'elenco degli utenti, è possibile eseguire la sincronizzazione vera e propria rimuovendo il parametro '-WhatIf'.

Eseguite ora lo stesso comando, ma senza '-WhatIf', e gli utenti verranno processati nell'ambiente GoBright .

Passo 4.3: Pianificare l'esecuzione periodica dell'integrazione tramite il task scheduler di Windows

Per poter eseguire lo script senza sorveglianza, è necessario effettuare in qualche modo il login automatico.

Metodo consigliato per il login non presidiato:
Il metodo consigliato per effettuare il login non presidiato è la creazione di un'applicazione registrata in Azure AD e la connessione a tale applicazione:

#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

Per maggiori informazioni, cliccate su questo link.

A scopo di test, si può utilizzare il seguente metodo per accedere automaticamente ad Azure AD con il metodo di login non presidiato e testare lo script prima di eseguire lo script di sincronizzazione degli utenti vero e proprio:

$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

Fase 4.1: Testare la selezione degli utenti

Il comando per ottenere le informazioni da Active Directory ed elaborarle in GoBright è il seguente:

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

È possibile utilizzare i seguenti parametri nel comando 'Push-ADUsersToBB':

Di seguito sono riportati alcuni esempi di comandi, che possono essere adattati alla situazione in cui ci si trova.

Questi comandi non aggiornano ancora gli utenti nel sistema, quindi sono comandi di prova, perché includono il parametro "-WhatIf".

Esempi di comandi di prova:

Elaborare gli utenti con UPN che terminano con 'yourdomain.com':

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

Elaborare gli utenti con UPN che terminano con 'yourdomain.com' e utilizzare il campo 'PersonnelNumber' di ActiveDirectory come pincode per gli utenti:

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

Elaborare gli utenti che sono membri di un gruppo specifico in una UO (Unità Organizzativa):

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

Elaborare gli utenti che sono membri di un gruppo specifico in una OU (Unità Organizzativa) e impostare un ruolo specifico in base all'appartenenza al gruppo:

$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

Elabora gli utenti che sono membri di un gruppo specifico in una OU (Unità Organizzativa), con [dominio][nome utente] come nome utente di autenticazione:

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 un esempio in cui si lavora con due diversi tenant di Active Directory, ma è necessario collegarli a un unico ambiente GoBright , è possibile utilizzare il seguente script di esempio:

Tenere presente che questo script non supporta l'istruzione -WhatIf. Quando si esegue questo script, gli utenti verranno trasferiti da Active Directory a GoBright.

[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]'

Passo 4.2: Eseguire la sincronizzazione vera e propria

Una volta filtrato correttamente l'elenco degli utenti, è possibile eseguire la sincronizzazione vera e propria rimuovendo il parametro '-WhatIf'.

Eseguite ora lo stesso comando, ma senza '-WhatIf', e gli utenti verranno processati nell'ambiente GoBright .

Passo 4.3: Pianificare l'esecuzione periodica dell'integrazione tramite il task scheduler di Windows

Seguite questi passaggi per sincronizzare gli utenti da Active Directory in base a una pianificazione:

• Prendete il comando che avete composto (vedi passi precedenti) e salvatelo in un file .ps1:
  • Creare un file .ps1 (ad esempio UsersToBrightBooking.ps1) in una cartella a piacere.
  • Aprire il file con un editor, ad esempio 'notepad'.
  • Incollare il comando completo nel file
  • Salvare il file
• Eseguire il file per vedere se è stato eseguito con successo
• Creare un'attività nel pianificatore delle attività di Windows:
  • Aprire il pianificatore delle attività di Windows
  • Creare un'attività
  • Impostare un programma, ad esempio una volta al giorno o ogni 4 ore.
  • Aggiungere l'azione "Avvia un programma":
    • Programma/script:
      Powershell.exe
    • Parametri:
      -windowstyle minimized -c "powershell -c .[Nome del file .ps1 creato] -verbose >> ExportToGoBright_Output.txt 2>&1″
    • Inizio in:
      Compilare "inizio in" con la posizione dello script, ad esempio:C:scripts