Before You Get Started

🚧
WARNING ABOUT USERNAMES & SYNCING
Snipe-IT considers the username of a user to be the unique identifier when syncing with LDAP/AD.
If you manually created some users, or imported them via CSV, using a non-email address style username, you are likely to create duplicate users when you subsequently sync with AD, Okta, Azure, etc.
Make sure you confirm what the username style is in the directory service you are syncing with BEFORE actually syncing for the first time.

For example, if your manually created or CSV imported usernames look like jane.smith (with an email value of [email protected]), you should confirm that the directory service you're syncing to uses jane.smith as a username value, OR update the usernames of your users to be consistent with what the directory service will use.

jane.smith is not the same as [email protected], so you'll end up with duplicate users, one for jane.smith and one for [email protected].

❗️
TAKE A BACKUP
Whenever you're touching data directly via MySQL, you should ALWAYS take a backup FIRST.

Helpful MySQL Commands

If you've already created your users manually or via CSV import and are either switching to an AD/LDAP system that requires a different username format, we provide some helpful MySQL commands that can hopefully get you sorted. These commands would be run against the Snipe-IT database, either via MySQL command line or using a MySQL GUI tool such as phpMyAdmin, Sequel Ace, or others.

Update Plain Username to Email Address

You can update a plain username to an email address using the following mysql command:

# Update a regular username to append the domain name

UPDATE users SET username = CONCAT(username,'@yourdomain.com') WHERE username NOT LIKE '%@%' AND deleted_at IS NULL;

This will look through the users table for any non-deleted records with username fields with a value that is missing an @ symbol, and then modify that record to be [email protected].

If you just want to copy user email addresses into their username field, thus changing their login username to be their email address, you can run the following:

# Update a regular username to be the same as the user's email address

UPDATE users SET username = email where email!='';

You should make sure that all of your email addresses are unique before running this command.

Rebranding

If you need to change the email address domain for your usernames and email addresses, for example after a rebrand or if your company got acquired, you could run this:

# Update the domain names of email addresses from the old domain to the new one

UPDATE users SET email = REPLACE(email, '@old-domain.com', '@new-domain.com') WHERE email LIKE '%@old-domain.org';

# Update the username to the updated email address

UPDATE users SET username = email where email!='';

Changing Email Format

If you need to convert your email addresses (and/or usernames) to a [email protected] format, you can run:

# Convert email addresses to be [email protected]

UPDATE users SET email = lower(CONCAT(first_name, '.', last_name,'@yourdomain.com')) WHERE last_name!='';

# Update the username to be the email address

UPDATE users SET username = email where email!='';

Checking for Duplicates

To check for duplicate usernames for users that have not been soft-deleted:

# Check for duplicate usernames

SELECT id, username, email, first_name, last_name, COUNT(*) FROM users WHERE deleted_at IS NULL GROUP BY email HAVING COUNT(*) > 1;

To return a count of duplicates for all rows for users that have not been soft-deleted:

# Return a count of duplicates

SELECT id, username, email, first_name, last_name, COUNT(*) FROM users WHERE deleted_at IS NULL GROUP BY username;

This will return all usernames with the number of duplicates for each one.

Hosted LDAP Providers

If you're using a common AD/LDAP hosted directory service such as Google Workspace, Azure/Entra, etc, you'll want to check out the documentation on Hosted LDAP Providers, as many of them require a few additional steps to integrate with Snipe-IT.

🚧
You must have the php-ldap extension installed for LDAP integration to work

The LDAP Sync functionality will import any users in your LDAP/Active Directory using the LDAP sync (in People > LDAP), and will update existing users. It will also allow users to use their LDAP credentials to login to Snipe-IT.

To set up your Snipe-IT installation to be able to use LDAP for user login and import, go to Admin > Settings and scroll down to the LDAP settings sections.

We never, ever write anything to your LDAP server, and a read-only administrator account can be used for these settings.

LDAP Login Overview

When you have LDAP enabled and a user tries to login, it will first query your LDAP server with their credentials. If they authenticate successfully with your LDAP server, their local user record will be updated and they will be logged in.

If the user does not authenticate successfully against your LDAP server, their local user is NOT updated, and the system falls back to trying to authenticate them as a local (non-LDAP) account.

Configuration

Some settings are only used during LDAP Sync, some are only used during LDAP Login, and some settings are used for both. Check the "Used For" column to determine which settings are used for which.

❗️
Warning:
All LDAP attribute values except "LDAP Authentication Query" MUST be entered in all lowercase.

Option	Example	Notes	Required	Used For
LDAP Server	`ldap://ldap.example.com`	The URL of the LDAP server, beginning with `ldap://` or `ldaps://`	Yes	All
LDAP Password Sync	unchecked	If the user has succesfully authenticated before, and the LDAP server is down, this will enable the user to continue to log in.	No	Login
LDAP Permissions Group	No Default Group	The Permissions Group you want to assign to newly-created users	No	All
Active Directory Domain	`ad.yourdomain.com`	The domain to authenticate your AD against. This is often your company email domain, but not always. We concatenate this with your user's username to execute the authentication, so if your user was janedoe, and your AD domain was mysite.com, we create the User Principal Name by combining them. This is only needed for AD (not LDAP) connections.	No	Login
Client-Side TLS key		Almost always only used for Google Secure LDAP (GSuite)	No	Sync
Client-Side TLS Certificate		Almost always only used for Google Secure LDAP (GSuite)	No	Sync
Use TLS	unchecked	If your LDAP server supports the STARTTLS extension to encrypt a normally-unencrypted connection, check this. Usually it's just better to use `ldaps://` but if you can't do that for some reason, this is a reasonable fallback	No	All
Use SSL certificate validation	Checked - "Allow invalid SSL certificate"	If you use a directory server that does not have a public verifiable TLS certificate, then you should check this box. This is true for most Active Directory servers.	No	All
LDAP Bind Username	`cn=read-only-admin,dc=example,dc=com`	Admin username to use to connect to LDAP to search the OU for LDAP import.	Yes	Sync
LDAP Bind Password	`password`	Password to use when authenticating to LDAP	Yes	Sync
Base Bind DN	`dc=example,dc=com`	The base where the search for users will be executed.	Yes	All
LDAP Filter	`&(cn=*)`	The search filter for the LDAP query. For AD filter enabled users using: `&(sAMAccountType=805306368)(!(userAccountControl:1.2.840.113556.1.4.803:=2))`	Yes	Sync
LDAP Authentication query	`uid=`	The LDAP query we should use to search your LDAP users. THIS IS THE ONLY FIELD THAT SHOULD BE MIXED CASE! AD: Usually `sAMAccountName=`	Yes	Login
LDAP Active Flag	`active`	Optional flag for disabled user accounts. WARNING: if this flag is set, and doesn't exist in your directory, users will not be able to log in!	No	Sync

For an extensive list of Active Directory filters that can help you narrow down the users you sync, check out the documentation on Microsoft's website.

Troubleshooting

If you're having trouble, we provide an LDAP Troubleshooter command line tool that should help you figure out where the issues might be.

Field Mapping for Syncing

📘
Note that in most cases, the value for mapped fields in your LDAP Field Mapping Settings should be lowercase, even if they are actually mixed case in your AD/LDAP. For example, if your AD/LDAP uses displayName, you still want to use displayname (lowercased) in your LDAP Field Mapping settings in Snipe-IT.

Option	Common Value
LDAP Username Field	`uid` or `samaccountname`
LDAP Email Field	`mail`
LDAP First Name Field	AD: `givenname` LDAP: `cn`
LDAP Last Name Field	`sn`
LDAP Employee Number Field	`emp_no`
LDAP Department Field	`department`
LDAP Manager Field	`manager`
LDAP Phone Field	`telephonenumber`
LDAP Mobile Number Field (v8.2.2+)	`mobile`
LDAP Display Name (v8.2.2+)	`displayname`
LDAP Address Field	`streetaddress`
LDAP City Field	`l`
LDAP State/Province Field	`st`
LDAP Postal Code Field	`postalcode`
LDAP Country Field	`co`
LDAP Job Title Field	`title`
LDAP Location Name	`physicaldeliveryofficename`

Testing LDAP Settings

In Snipe-IT v4.0.10 and higher, there is an easier way to determine if your LDAP settings are correct.

Once you have entered your LDAP settings (in Admin > LDAP/AD), and you have checked the "Enable LDAP" checkbox and saved your settings, you will see two LDAP test buttons at the bottom of your LDAP Settings page.

(Click on the images below for a larger, animated demonstration if they do not play automatically.)

The first checks to make sure your LDAP binding and OU is correct, and we can search your directory. This is necessary for syncing your users via the LDAP Sync utility.

The second LDAP test button attempts to actually authenticate with your LDAP server as if you were one of your users logging in, so you will need to provide a valid username and password for an LDAP user account that has permission to bind to your LDAP server. This user does not need to have searching/indexing capabilities.

Using Active Directory

If your LDAP server is an Active Directory server, make sure you check the AD checkbox on your LDAP Settings page (Admin > LDAP/AD), and add an Active Directory Domain to your settings.

Snipe-IT will first check to see if you've set your LDAP server as an AD server, and will then try to use whatever AD Domain you've specified. If you don't add an AD Domain, it will try to guess the user's distinguished name using the email domain you set in your settings.

LDAP Command Line Sync

LDAP syncing is available via the GUI and also available via the LDAP Sync command line tool.

📘
For Hosted Snipe-IT Customers
If you need to set up an LDAP sync cron job on the hosted platform, just shoot us an email at [email protected] and we'll get you sorted. :)

LDAP Sync & Login

Before You Get Started

WARNING ABOUT USERNAMES & SYNCING

TAKE A BACKUP

Helpful MySQL Commands

Update Plain Username to Email Address

Rebranding

Changing Email Format

Checking for Duplicates

Hosted LDAP Providers

You must have the `php-ldap` extension installed for LDAP integration to work

LDAP Login Overview

Configuration

Warning:

Troubleshooting

Field Mapping for Syncing

Testing LDAP Settings

Using Active Directory

LDAP Command Line Sync

For Hosted Snipe-IT Customers

Before You Get Started

WARNING ABOUT USERNAMES & SYNCING

TAKE A BACKUP

Helpful MySQL Commands

Update Plain Username to Email Address

Rebranding

Changing Email Format

Checking for Duplicates

Hosted LDAP Providers

You must have the php-ldap extension installed for LDAP integration to work

LDAP Login Overview

Configuration

Warning:

Troubleshooting

Field Mapping for Syncing

Testing LDAP Settings

Using Active Directory

LDAP Command Line Sync

For Hosted Snipe-IT Customers

You must have the `php-ldap` extension installed for LDAP integration to work