LDAP / Active Directory Login
LDAP / Active Directory Login lets users sign in to AIR with their Active Directory (AD) username and password. Access is managed from Active Directory:
- Automatic user creation: A user account is created in AIR the first time a directory user signs in. You do not need to create directory users in AIR in advance.
- Group to role mapping: Roles and organization access are assigned automatically based on the user’s Active Directory group memberships, including nested groups.
- Directory-managed profiles: First name, last name, and email address come from Active Directory and are refreshed on every sign-in.
- Deleted user cleanup: Optionally, users who are deleted or disabled in Active Directory are also removed from AIR.
You can find these settings under Settings > Security > LDAP / Active Directory Login.
How sign-in works
Section titled “How sign-in works”When a user signs in with a directory account, AIR performs the following steps:
- AIR connects to your Active Directory server with the credentials the user entered. The service account is never used for sign-in.
- If the credentials are valid, AIR reads the user’s directory record (email address, first name, last name) and all group memberships, including nested groups.
- AIR compares the user’s groups with your group to role mappings and determines the roles and organizations the user receives.
- If the user does not exist in AIR yet, the account is created automatically. If the user already exists, their roles and profile details are updated.
Users can enter their username in any of the following formats:
usernameDOMAIN\usernameusername@domain
Prerequisites
Section titled “Prerequisites”Before you enable LDAP login, make sure that:
- The AIR Console can reach your Active Directory server on the LDAP port (389) or the LDAPS port (636), or on a custom port if you use one.
- Every user who will sign in has an email address set in Active Directory. Users without an email address cannot be created automatically.
- You have decided which Active Directory groups map to which AIR roles.
- You have the Global Admin role if you want to configure group to role mapping.
- (Optional) You have a read-only Active Directory service account if you want to enable deleted user cleanup.
Configure the connection
Section titled “Configure the connection”The Connection section defines how AIR connects to Active Directory.
| Field | Description |
|---|---|
| Enable | Turns LDAP login on or off. |
| Use secure connection | Connects over LDAPS. Recommended. |
| Server | The hostname or IP address of your domain controller. |
| Domain | Your Active Directory domain, for example corp.local. |
| Port | Optional. If you leave it empty, AIR uses 636 when secure connection is enabled and 389 when it is disabled. |
| User search base | Optional. Limits sign-in to users inside a specific OU or container, for example OU=Security Team,DC=corp,DC=local. If you leave it empty, the whole domain is searched. The value must be a valid distinguished name (DN). |
Click Save at the bottom of the page to save the connection settings.
Configure the directory service account (optional)
Section titled “Configure the directory service account (optional)”The Directory service account is only needed for deleted user cleanup. It is not used to sign users in.
- Enter a Service account username and Service account password. A read-only account with permission to search the whole domain is sufficient. Domain Admin rights are not required.
- After you save, the password is stored securely and is never displayed again. The page only shows that a password is saved.
- If you leave the password field empty when you save, the saved password is kept.
- To remove the saved password, click Clear saved password. Clearing the username also removes the password.
Configure group to role mapping
Section titled “Configure group to role mapping”Group to role mapping decides which roles and organizations a directory user receives. Only Global Admin users can view and change the mapping. Other users can see the section, but it is read-only.
Each mapping row contains:
- Group DN: The distinguished name of the Active Directory group, for example
CN=AIR Analysts,OU=Groups,DC=corp,DC=local. - Roles: One or more AIR roles that members of the group receive.
- Organization scope: Either All organizations or a list of selected organizations.
How roles are calculated
Section titled “How roles are calculated”- One or more mappings match: The user receives all roles from all matching mappings. If any matching mapping uses All organizations, the user has access to all organizations. Otherwise, the user has access to every organization selected in the matching mappings.
- No mapping matches: Automatically created users receive the Default roles, which always apply to all organizations. If no default roles are set, the user cannot sign in.
Membership in nested groups counts as membership in the parent group. For example, if Tier 1 is a member of AIR Analysts, members of Tier 1 also match the AIR Analysts mapping.
Default roles
Section titled “Default roles”Default roles are given to automatically created users who do not match any mapping.
Mapping rules
Section titled “Mapping rules”When you save the mapping, AIR checks that:
- Each Group DN is a valid distinguished name. Escaped commas (
\,) are supported. - The same group is not added twice. Group DNs are compared without regard to letter case or extra spaces.
- Each row has at least one role.
- Each row that uses selected organizations has at least one organization.
- All selected roles and organizations exist.
- Roles that include system or Global Admin privileges are only mapped with the All organizations scope.
Group to role mapping has its own Save mapping button and is saved separately from the rest of the page.
Remove deleted directory users
Section titled “Remove deleted directory users”When a user is deleted or disabled in Active Directory, they cannot sign in to AIR. If you also want AIR to remove these users, turn on Remove deleted directory users.
To turn this option on:
- Enable LDAP login.
- Enter the service account username and password.
- Turn on Remove deleted directory users and click Save. AIR connects to Active Directory with the service account to confirm that it works.
When this option is enabled, directory users who are deleted or disabled in Active Directory are removed from AIR. This applies to all directory users, including users who were created before this option was available.
The following safeguards apply:
- Users with API tokens are kept. Users who own an API token are not removed, so that integrations do not break.
- Mass deletion protection: If more than 5 users and more than 20% of all directory users would be removed at once, no users are removed. This protects you from mistakes such as a wrong configuration or missing service account permissions.
- No removal on errors: If AIR cannot complete the check against Active Directory, no users are removed.
User profiles and the Users page
Section titled “User profiles and the Users page”Profile details come from Active Directory
Section titled “Profile details come from Active Directory”Directory users cannot be edited in AIR. Their details are managed only in Active Directory:
- First name, last name, and email address are read from Active Directory and updated on every successful sign-in.
- Roles and organizations are assigned only through group to role mapping.
- On Users, administrators cannot edit directory users.
- On Account > My Profile, directory users see a notice that their details come from the directory and cannot change them.
The only exception is the profile photo: directory users can upload or remove a profile photo on Account > My Profile.
A few exceptions apply when profile details are updated from Active Directory:
- If a user has no email address in Active Directory, the email address stored in AIR is kept.
- If the email address in Active Directory is already used by another AIR user, the email address is not changed. First name and last name are still updated.
Creating users
Section titled “Creating users”Directory users are created automatically when they first sign in. The New User form on the Users page creates local users only. When LDAP login is enabled, the form shows a reminder about this.
Automatically created and manually created directory users
Section titled “Automatically created and manually created directory users”AIR treats directory users differently depending on how they were created:
| User type | A mapping matches | No mapping matches |
|---|---|---|
| Created automatically at first sign-in | Roles are replaced with the mapped roles | Default roles are assigned. If there are no default roles, sign-in is denied |
| Created manually, including directory users that existed before automatic user creation | Roles are replaced with the mapped roles | Roles are not changed. The user signs in with their current roles |
Audit log events
Section titled “Audit log events”The following events are recorded in the audit log:
| Event | When it is recorded |
|---|---|
| Active Directory role mapping saved | The group to role mapping or default roles are changed. |
| Active Directory user cleanup settings saved | The deleted user cleanup setting is changed. |
| Directory access synced for user | A user’s roles or organizations change during sign-in. Recorded as the System user. |
| User deleted | A user who was deleted or disabled in Active Directory is removed from AIR. Recorded as the System user. |
Permissions
Section titled “Permissions”| Action | Required permission |
|---|---|
| Save connection, service account, and cleanup settings | Permission to save settings |
| View and save group to role mapping | Global Admin |
Do I need to create directory users in AIR before they can sign in?
Section titled “Do I need to create directory users in AIR before they can sign in?”No. Users are created automatically on their first successful sign-in, as long as they match a group mapping or default roles are configured.
What happens if a user is removed from a mapped group?
Section titled “What happens if a user is removed from a mapped group?”On their next sign-in, their roles are recalculated. An automatically created user who no longer matches any mapping receives the default roles. If there are no default roles, the user cannot sign in.
What happens when a user is disabled in Active Directory?
Section titled “What happens when a user is disabled in Active Directory?”The user cannot sign in to AIR. If Remove deleted directory users is enabled, the user is also removed from AIR, unless they own an API token.
Can a user sign in with user@domain instead of DOMAIN\user?
Section titled “Can a user sign in with user@domain instead of DOMAIN\user?”Yes. Users can sign in with username, DOMAIN\username, or username@domain.
Is the service account used for sign-in?
Section titled “Is the service account used for sign-in?”No. Every user signs in with their own credentials. The service account is only used to remove users who were deleted or disabled in Active Directory.
How can I see which users were removed?
Section titled “How can I see which users were removed?”Users who are removed because they were deleted or disabled in Active Directory appear in the audit log as User deleted events recorded by the System user.
Do I need to recreate directory users who already exist in AIR?
Section titled “Do I need to recreate directory users who already exist in AIR?”No. Directory users who were created before automatic user creation was available keep their accounts and continue to sign in with their Active Directory credentials. No data is removed and their roles are not changed until a group mapping applies to them.
Will existing directory users keep their roles after I add group mappings?
Section titled “Will existing directory users keep their roles after I add group mappings?”It depends on their group memberships:
- The user is a member of a mapped group: On their next sign-in, their roles and organizations are replaced with the roles and organizations from the mapping. Their previous roles are removed.
- The user is not a member of any mapped group: Their roles are not changed. They continue to sign in with their current roles. Default roles are not applied to them.
Before you add a mapping, check which existing users are members of that group.
Will the name and email address of existing directory users change?
Section titled “Will the name and email address of existing directory users change?”Yes. On their next sign-in, first name, last name, and email address are updated with the values from Active Directory, and these fields become read-only in AIR. If the user has no email address in Active Directory, the email address stored in AIR is kept.
What happens to existing directory users who are outside the user search base?
Section titled “What happens to existing directory users who are outside the user search base?”Directory users who were created before automatic user creation was available can continue to sign in with their current roles. The user search base applies to new users and to users who were created automatically at sign-in.
An existing directory user can no longer sign in. Why?
Section titled “An existing directory user can no longer sign in. Why?”The most common reason is a username format mismatch. If the username stored in AIR is different from the user’s Active Directory account name, AIR cannot match the existing account. For example, the account is stored as [email protected], but the user signs in with user. AIR then tries to create a new account, and sign-in fails if the email address is already used by the existing account.
To avoid this, ask the user to sign in with the same username format that is stored in AIR.
Does removing deleted directory users also apply to existing users?
Section titled “Does removing deleted directory users also apply to existing users?”Yes. When Remove deleted directory users is enabled, existing directory users who are deleted or disabled in Active Directory are also removed from AIR. Users who own an API token are kept.
Are local and API users affected by these settings?
Section titled “Are local and API users affected by these settings?”No. Local and API users continue to sign in with their AIR password. Group to role mapping, profile updates, and deleted user removal only apply to directory users.
Can I use LDAP login together with two-factor authentication?
Section titled “Can I use LDAP login together with two-factor authentication?”Yes. Directory users can set up two-factor authentication from their account settings.