On this page
- Scope and Purpose of this Document
- Security and Confidentiality of Data
- Synchronizing Data
- Integration Option: Azure / Office 365
- Integration Option: Locally hosted AD
- Sample PowerShell Script:
- Sample CSV file format
- Sample Office 365 Integration Screens
Scope and Purpose of this Document
This document is created to outline possible ways of integrating the iLobby Address Book with various available Enterprise systems for the purpose of automation of data entry and maintenance. The goal is to keep the iLobby Address Book updated with latest employee data via sync with another business system. The approach must be secure, efficient and maintain the desired level of compliance and confidentiality.
Security and Confidentiality of Data
This document falls under iLobby’s privacy and security policies which mandate sufficient level of encryption and data segmentation to be present throughout the platform. For the purpose of this document following guidelines are to be followed:
- Minimum of TLS 1.2 encryption to be used for all data transfers
- All data submissions must be uniquely tokenized or identified using a unique key ID and secret, issued to a specific client. Client may have more than one key, but each key can only be assigned to one client.
- Expired key/tokens are not to be re-used
- All data must travel from the customer system, directly into protected area of iLobby. No middle servers/repositories are to be used, unless they are in-scope and makeup the iLobby platform. Under no circumstances will iLobby request the client to post data to an insecure server, even temporarily.
- VPN and IP restricted connections may be used to further safeguard the data
Synchronizing Data
By default, all data pushed through any of the synchronization mechanisms outlined in this document will take precedence and will overwrite data manually entered. If empty fields are submitted, they will be ignored and they will not overwrite data already stored. Data is synchronized based on the email address of the address book entry. Each sync will add new records to the address book and will mark records not present in the sync as “disabled”.
Few options are available for clients looking to sync address books for multiple locations. If this is a requirement, please contact support@goilobby.com for available options.
Integration Option: Azure / Office 365
iLobby supports direct to Azure/Office 365 integration. This integration will expose the entire contents of the AD to iLobby on “read only” basis.
When requested, iLobby will provide the Client with a web url residing on iLobby platform. This url, when clicked, will attempt to connect the iLobby server with your hosted AD. In order to authenticate the connection, the user will have to enter their AD credentials, which have to allow for access to AD contents. Permission request will be displayed (some items may be duplicated). Once the connection is authorized by the user, iLobby will be issued a token by Azure/Office 365. This token will be used to establish an ongoing connection and to extract the AD information. iLobby Enterprise App will also appear in your Azure control panel to denote that the connection has been made. You will be able to remove it when no longer required.
Please see Sample Office 365 Integration Screens at the end of this document for additional detail.
Integration Option: Locally hosted AD
iLobby address book can be populated with AD data by running the provided powershell script (see attachment) on the customer server. This is a push action, where customer fully controls what data is pushed to the iLobby server and at what frequency. As a guideline, we recommend that only relevant data is submitted and that frequency is set at once per day.
When requested, iLobby will provide the Client with an API key to be used for transmission. The key is to be inserted into the required part of the provided powershell script. The script may be modified to reflect the customer’s AD structure and consists of the following main parts:
- Querying AD for a list of users with specified fields and within specified AD groups
- Creation of a CSV file containing the list
- Upload of the CSV file to iLobby Web API using the issued key
Multiple sites may be synched using a single CSV file by specifying the correct site as per the sample format below, or by requesting unique API keys for each site in order to submit separate, site specific, CSV files.
Integration Option: Custom Integration
iLobby address book can be populated with data from any source by submitting a pre-formatted CSV file to the iLobby API. As a guideline, we recommend that only relevant data is submitted and that frequency is set at once per day.
When requested, iLobby will provide the Client and an API key to be used for transmission and the format for the URL request. The CSV file submitted must meet iLobby format standards in order to be processed. Sample format is attached.
Sample PowerShell Script:
Please see below the example of the updated PowerShell script for .CSV Address Book sync.
- SAMPLE POWERSHELL SCRIPT, CHANGE EXTENSION TO .PS1 PRIOR TO EXECUTION#
- <# 1. DEFINE SEARCH LOCATIONS #>
- $OULocation="OU=Users,DC=TOR"
- <# 2. SET API CREDENTIALS #>
- $client_id = ''
- $client_secret = ''
- <# 3. SET OUTPUT DIRECTORY #>
- $sourceFilePath = $PSScriptRoot + "\adextract.csv"
- <# 4. SET UP USER PROPERTIES TO EXPORT #>
- $fields = @('mail','DisplayName','telephoneNumber','HomePhone')
- <# ACTIVE DIRECTORY USER EXPORT TO CSV FILE #>
- Import-Module ActiveDirectory
- $Users = Get-ADUser -Filter {Enabled -eq "True"} -SearchBase $OULocation -SearchScope Subtree -Properties $fields | select $fields
- $Users | Export-Csv $sourceFilePath -NoTypeInformation -Force
- <# GET TOKEN #>
- $headers=@{}
- $headers.Add("Content-Type", "application/x-www-form-urlencoded")
- $response = Invoke-WebRequest -Uri 'https://partnerapi.goilobby.com/auth/connect/token' -Method POST -Headers $headers -Body "grant_type=client_credentials&client_id=$($client_id)&client_secret=$($client_secret)"
- $token = ConvertFrom-Json $response.Content
- $access_token = $token.access_token
- <# UPLOAD CSV FILE TO ILOBBY API #>
- [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.SecurityProtocolType]::Tls12;
- $urlDest = "https://partnerapi.goilobby.com/addressbook/uploadcsv";
- $webClient = New-Object System.Net.WebClient;
- $webClient.Headers.Add("Content-Type", "application/x-www-form-urlencoded")
- $webClient.Headers.Add("Authorization", "Bearer $($access_token)");
- $resp = $webClient.UploadFile($urlDest, "POST", $sourceFilePath);
- $enc = [System.Text.Encoding]::ASCII
- $enc.GetString($resp)
Sample CSV file format
FIRSTNAME,LASTNAME,TITLE,DIVISION,EMAIL,MOBILE,DESKPHONE,SITE
Rob,Jones,Manager,Management,rob.jones@test.com,4169998888,4169997777,Toronto
!!! When including the "SITE" column, please make sure that the values for all records match the site names in the iLobby portal.
Sample Office 365 Integration Screens
When requested, iLobby support will provide the client with a unique integration link for establishing the connection between client’s O365 installation and iLobby. After navigating to the link, client will be presented with the following screens:
Account Selection
This screen will allow the client to select the user account with which the integration link will be established:
Permissions Screen
Once account is selected, iLobby will need to be authorized and granted the permissions required to access the contents of customer’s Office 365 installation:
Application List
iLobby can now be managed in the list of installed applications and services under Enterprise Applications list within the Management tab of your Office 365 management portal: