Integration: Entra ID (Active Directory)

Discover how to seamlessly connect inspace with Microsoft's Entra ID (Active Directory) for efficient user data management. Our LDAP module acts as a bridge, enabling data transfer between the company's Active Directory and inspace.

Currently, the LDAP module is stored on the client’s side due to security requirements (some clients can provide data only within their security perimeter). The data, which is transferred to inspace, passes through the LDAP module (please see Scheme 1).

In the future, the LDAP module will be stored on the inspace’s side (please see Scheme 2).

The data structure in the company’s AD and inspace can differ. Fields name and number may not match. For example, the company’s AD may not contain the field “Teams” (please see Scheme 3).

inspace offers its algorithm to enable field matching. Below, you can find the detailed description of:

• LDAP inspace module deployment
• Connection of the LDAP inspace module to the company’s Active Directory
• Matching of fields between the company’s AD and inspace

LDAP Deployment kit contains the following files:

• Installation instructions (this document)
• api_auth - a file containing your authorization key for inspace API. This key is generated specifically for your company and has to be kept secret. If you have doubts or suspicions that your authorization key may have been compromised, please get in touch with the inspace support team to retire this key and receive a new one.
• env.example - a file with an example of the application configuration. You can get a detailed description of this file in the Configuration section.
• nectr.com.au__inspace-ldap__1.0.0.tar.gz - a GZIP-compressed tarball with a Docker image containing the application. You do not have to de-compress it manually.
• scripts/cron.hourly/ldapsync.sh - CRON job to sync LDAP users hourly
• cripts/cron.daily/clean_logs.sh - CRON job to delete log files that are older than 180 days
• scripts/cron.daily/gzip_logs.sh - CRON job to compress log files that are older than 1 day

Please pay attention to a few assumptions this guide makes:

• You have access to a target host's shell.
• You have access to a user with root-level permissions on a target host.
• Your target host has a system volume /opt with at least 16 GB of disk capacity dedicated to it.

1. Docker
To run the application, you will need to have Docker installed. Docker allows for isolating the application environment and simplifying the installation process.
Please refer to the official documentation to get help installing Docker for your platform

2. User and permissions
To use Docker mounted volumes to read/write host system files and directories, you would need a user with a matching GID/UID on a host system.
Docker containers leverage user inspace with UID/GID=2021 to run applications. Therefore, you should create a user with the same UID/GID on your host system and then make this user the owner of files and directories used by the application.
If, for some reason, you have to use a different UID/GID, please contact the inspace support team to request a customized Docker image.
Create user:
$ adduser --uid 2021 inspace

3. Files and directories

1. Create the following directories on your host system:

• /opt/ldap
• /opt/logs/ldap

$ mkdir -p /opt/ldap && \
mkdir -p /opt/logs/ldap

2. Copy files from your LDAP Deployment Kit into host's /opt/ldap:

• nectr.com.au__inspace-ldap__1.0.0.tar.gz -> /opt/ldap/nectr.com.au__inspace-ldap__1.0.0.tar.gz
• .env.example -> /opt/ldap/.env

3. Make an inspace user the owner of these directories and files within it:
$ chown -R inspace:inspace /opt/ldap && \
chown -R inspace:inspace /opt/logs/ldap

4. Edit Configuration File
Edit /opt/ldap/.env file with values that make sense for your system.
Please refer to the Configuration File Reference section at the end of this guide for help and finding a description of individual settings.

5. Load and Start Application Docker Image

1. Load the Docker image from a file:

$ docker load -i `/opt/ldap/nectr.com.au__inspace-ldap__1.0.0.tar.gz`

To confirm that the image was successfully loaded, run:
$ docker image ls

You should see nectr.com.au/inspace-ldap image on the image list:
REPOSITORY nectr.com.au/inspace-ldap
TAG 1.0.0
IMAGE ID 5c4e943ba0a1
CREATED 1 minute ago
SIZE 127MB

After this, the image file can be safely deleted from the host system.

2. Create and run a Docker container using this image:
$ docker run -v /opt/ldap/.env:/home/inspace/app/.env:z \
-v /opt/logs/ldap:/home/inspace/app/logs:z \
--network="host" \
--name inspace-ldap -d nectr.com.au/inspace-ldap:1.0.0

3. Verify that the application is executing successfully:
$ docker logs inspace-ldap

If you see any errors, please save this log and contact the inspace support team for troubleshooting.

6. Install CRON jobs
Copy CRON scripts from your inspace LDAP Deployment Kit to your host system:

• scripts/cron.hourly/ldapsync.sh -> /etc/cron.hourly/ldapsync.sh
• scripts/cron.daily/clean_logs.sh -> /etc/cron.daily/clean_logs.sh
• scripts/cron.daily/gzip_logs.sh -> /etc/cron.daily/gzip_logs.sh

Configuration File Reference
Example
### Active Directory ###
# Login
ad.login=admin
# ↑ Password for login
ad.password=XwjJGN$Yb%8JEh65
# ActiveDirectory access gateway -- ldap:// or ldaps://
ad.uri=ldap://ldap.company.org
# Base domain to authenticate against and search users in
ad.baseDN=DC=ldap,DC=company,DC=org
# Specify in which DNs to search for users. Multiple DNs can be delimited by a semicolon (`;`).
# If empty, `ad.baseDN` will be used instead.
ad.scanDN=
# Specify algorithm for first and last name extraction:
# * `default` - name is read from `ad.attr.firstName`, last name is read from `ad.attr.lastName`.
# * `algo1` - both name and last name are read from `add.attr.firstName`, which must be a string that looks like: "Name [Surname] LastName"
ad.attr.nameExtractAlgo=default
# LDAP attribute to extract the first name from
ad.attr.firstName=givenName
# LDAP attribute to extract the last name from
ad.attr.lastName=sn
# LDAP attribute to extract user's department from
ad.attr.department=department
# LDAP attribute to extract user's position from
ad.attr.position=title
# LDAP attribute to extract user's email from
ad.attr.email=mail
# LDAP attribute to extract user's phone number from
ad.attr.phone=telephoneNumber
# LDAP attribute to extract user's thumbnail photo from
ad.attr.thumbnail=thumbnailPhoto
# LDAP attribute to extract UserAccountControl property flags (used to flag banned users)
ad.attr.userAccountControl=userAccountControl

### Inspace ###
# Inspace API URL
inspace.uri=https://api.inspace.app
# Headless admin token to authorize requests with
inspace.headlessAdminToken= insert AdminToken
# Email domain used by the company. Any user with an email on a different domain is ignored
inspace.emailDomain=company.org

### Logging ###
# Logging level:
# * `info` - output only error and short informational messages
# * `debug` - output messages about every action taken
# * `trace` - output debug messages and queries to AD
log.level=info
# Logging output destination:
# * `console` - stdout
# * `file` - outputs to the file with name formatted as log-YYYY-MM-DD--HH:mm:ss UTC.log
# * `string` - outputs to the file with a given name
log.destination=file
# Directory to store logs. By default application directory is used
log.dir=./logs

Reference
ad.login
Active Directory login.
Example:
ad.login=admin

ad.password
Active Directory password.
Example:
ad.password=XwjJGN$Yb%8JEh65

ad.uri
ActiveDirectory access gateway ldap:// or ldaps://.
Example:
ad.uri=ldap://ldap.company.org

ad.baseDN
Base domain to authenticate against and search users in.
Example:
ad.baseDN=DC=ldap,DC=company,DC=org

ad.scanDN
Specify in which DNs to search for users. Multiple DNs can be delimited by a semicolon (;).
If empty, ad.baseDN will be used instead.
Example:
ad.scanDN=OU=UNIT1,OU=Users,DC=org,DC=inspace,DC=app;OU=UNIT3,OU=Users,
DC=org,DC=inspace,DC=app;OU=UNIT3,OU=Users,DC=org,DC=inspace,DC=app

ad.attr.nameExtractAlgo
Specify the algorithm for first and last names extraction:

• default - name is read from ad.attr.firstName, last name is read from ad.attr.lastName.
• algo1 - both name and last name are read from add.attr.firstName, which must be a string that looks like: "Name [Surname] LastName"

Example:
ad.attr.nameExtractAlgo=default

ad.attr.firstName
LDAP attribute to extract the first name from.
Example:
ad.attr.firstName=givenName

ad.attr.lastName
LDAP attribute to extract the last name from.
Example:
ad.attr.lastName=sn

ad.attr.department
LDAP attribute to extract the user's department from.
Example:
ad.attr.department=department

ad.attr.position
LDAP attribute to extract the user's position from.
Example:
ad.attr.position=title

ad.attr.email
LDAP attribute to extract the user's email from.
Example:
ad.attr.email=mail

ad.attr.phone
LDAP attribute to extract the user's phone number from.
Example:
ad.attr.phone=telephoneNumber

ad.attr.thumbnail
LDAP attribute to extract the user's thumbnail photo from.
Example:
ad.attr.thumbnail=thumbnailPhoto

ad.attr.userAccountControl
LDAP attribute to extract UserAccountControl property flags (used to flag banned users).
Example:
ad.attr.userAccountControl=userAccountControl

inspace.uri
Inspace API URL.
Example:
inspace.uri=https://api.inspace.app

inspace.headlessAdminToken
Headless admin token to authorize requests with. You must use your authorization token received with the LDAP Deployment Kit.
Example:
inspace.headlessAdminToken=12345qaz

inspace.emailDomain
Email domain used by a company. Users with emails on a different domain are ignored.
Example:
inspace.emailDomain=company.org

log.level
Logging level:

• info - output only error and short informational messages
• debug - output messages about every action taken
• trace - output debug messages and queries to AD

Example:
log.level=info

log.destination
Logging output destination:

• console - stdout
• file - outputs to the file with name formatted as log-YYYY-MM-DD--HH:mm:ss UTC.log
• string - outputs to the file with the given name

Example:
log.destination=file

log.dir
Directory to store logs. By default application directory is used
Example:
log.dir=./logs

The support team is available to help users with any questions or issues they may have, from troubleshooting technical problems to offering guidance on how to use inspace’s features. In order to get the most effective and efficient support, it is recommended that users provide as much information as possible about the issue they are experiencing, including any error messages or other details. Contact support in the inspace app, or send an email to support@inspace.app.