LDAP authentication replaces the default email-based authentication mechanism for the UpGuard UI. Any account administrator can confirgure LDAP settings before an UpGuard Engineer enables LDAP authentication.
If you are interested in integrating with your Single Sign On Identity Provider, please refer to our article on Single Sign On.
What Do I Need?
Before configuring LDAP, you will need the following:
- The distinguished name (DN) of an OU that contains your user accounts
- The distinguished name (DN) of a CN (security group) that contains users that will be able to login to UpGuard
- The distinguished name (DN) and password of a user that can query LDAP (referred to as the bind user)
Setting up LDAP
The LDAP settings are found in the
Appliance Settings page, which is available by clicking your organization name in the top right corner of the UpGuard UI and selecting
If you do not see the LDAP section in the settings page, add
?show_ldap to the URL.
|LDAP Host||The hostname of your LDAP server|
|LDAP Port||The port to connect over|
|SSL On?||Flag determining if SSL will be used for the connection|
|LDAP Attribute||The unique identifier for users. Use “sAMAccountName” for Active Directory|
|Users Base DN||The lowest level OU containing all user records|
|Users Group DN||The CN of the specific group you have set up to grant access to UpGuard|
|Bind Account DN||The user UpGuard will use to query LDAP|
|Bind Account Password||The password for the bind user|
Enabling LDAP Authentication
Enabling LDAP must be done by an UpGuard Engineer. Please contact your Technical Account Manager or UpGuard Support to schedule an appointment.
We require an UpGuard Engineer to enable LDAP to mitigate the risk of the configuration being incorrect and an account administrator accidentally locking themselves out of an appliance.
Things to Note
- With LDAP integration set up, access to your UpGuard account will be determined by membership of the group specified in the above form (Users Group DN).
- Users in this group will have Member access by default. Administrators can change this from the Users page.
- Behind the scenes, UpGuard is still using the email address to drive user roles, so the LDAP user must have an email address associated with it.
Emergency Bypass User
Although you may want all your users to authenticate against an LDAP/AD server, there may be special occasions when you still need to access your UpGuard appliance when the auth server is down, broken or inaccessible (especially if you monitor the health of your auth server with UpGuard Core).
UpGuard Core can be enabled to elect one or more users as LDAP Emergency Bypass Users which are user accounts that are allowed to log into the appliance with an email address and password.
Enabling this feature requires assistance from an UpGuard Engineer, so please contact UpGuard Support or your Account Manager to schedule an appointment.
What access should the bypass user have?
If you want to restrict your bypass user to only be able to edit the LDAP settings to perform a manual fail over:
- Create a new organization account,
- Invite the bypass user to this new account only and make sure the bypass user is set to be an Admin of the account.
This will make sure that the user has enough access to view the appliance’s settings page (as an Account Admin) but they do not have any access to the existing nodes, policies, integrations, etc.
If you have a single account appliance and have disabled the require invite option for new users, then this option will be automatically enabled if you create a second organization account. Please discuss this with your Technical Account Manager if you are unsure of the implications of this decision.
However, if you want to allow the bypass user to still see all nodes, policies in the existing account, please invite them to the existing organization account. This apporach has the benefit of giving the bypass user access to your nodes and reports if a manual LDAP fail over isn’t working (due to a networking issue, for example).
If you allow the bypass user to access the account with your nodes, policies, etc then we recommend implementing a proper vaulting procedure around the credentials of the bypass user. For example, not only where they are stored or how to access the credentials, but proper logging of an access event and usage, if required by regulartory, compliance or auditing purposes.
To be alerted when the bypass user logs in, create a new Event View with the query
type=User Logged In AND email@example.com
Please view our guide on Events and Event Actions for more information.
LDAP Test Fails
There should be an error message shown if the LDAP test fails. For specific errors:
- Timeout: A timeout will arise when a firewall rule between the UpGuard Appliance and the LDAP server is configured to drop packets.
- Authentication Error: The Bind account username or password is incorrect.
UpGuard Login Fails via LDAP
Verify that your bind user works outside of UpGuard. Using a tool like
ldp.exe on a Windows AD Controller, verify that you can bind to the
Bind Account DN from your UpGuard settings.