> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.itential.com/itential-gateway/4/install-configure-ldap/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.itential.com/_mcp/server. # Install and configure LDAP authentication > Configure LDAP authentication for Itential Gateway to replace local authentication. Itential Gateway out-of-box authentication is configured for local authentication. Using local authentication, Gateway administrators can configure basic username and password authentication for Gateway users. Gateway administrators can further associate users with Gateway groups and roles, adding a level of authorization to the local authentication process to limit the types of operations users can perform. For customers who want to make use of their existing user authentication systems, Gateway now offers the ability to disable local authentication and replace it with LDAP user authentication. This supports customer efforts to centralize their identity management system, and puts in place a framework for future support of Multi-Factor Authentication (MFA). ## LDAP authentication The process for performing LDAP authentication to Gateway is depicted in the high-level procedure below. ![](/_fern-img/3bd1abd9863f1e9b577a8b86be487eacf139f7f44d48af084eb64a121009942b.webp) To support this approach, make sure the following steps are taken: #### Add LDAP users to appropriate groups Add LDAP users who will access Gateway to appropriate group memberships in LDAP. #### Create anItential Platform service account in LDAP If using Itential Automation Platform (IAP) to authenticate to Gateway, create anItential Platform service account/user in LDAP and assign it to an appropriate group. Itential recommends selecting a group membership for anItential Platform user that is unique, and theItential Platform user has no other group memberships or permissions in your environment. #### Enable basic password-based authentication Enable basic password-based authentication for those users (both regular andItential Platform) who will be authenticating to Gateway. In this release, Gateway does not support authentication factors other than a password. ## Configure Gateway for LDAP authentication Set the LDAP configuration options in the Itential Gateway GUI under **Configuration** > **LDAP**. ![](/_fern-img/ed705cb63c890bcbfa68670e9bca718ac1c05732900fc0325095194e9f7d936d.webp) After saving the LDAP configuration, test that the **BIND Username** and **BIND Password** work as expected by using the **Test Connection** button next to the **Save** button. Set LDAP to `ldap_auth_enabled: True` in the **properties.yml** file, and then restart Gateway. ![](/_fern-img/033a9646198281a3c42d821d8ed38d8fb7a30393780c07a174b7638afc2fb421.webp) ## Configure authorization groups and roles In this step, configure the authorization characteristics that determine what capabilities logged-in users have. To configure a group in Gateway, a name must be provided, and all the roles that will be associated with any user that is part of that group must be assigned. The name that is selected is important, because of how Gateway LDAP authentication maps LDAP users to Gateway groups and roles. Each user coming from an LDAP is typically associated with one or more groups through an LDAP attribute, such as the `memberOf` attribute. When configuring the Gateway LDAP properties, specify which LDAP user attribute holds the user group membership information. When a user authenticates to Gateway, Gateway will request the user's LDAP attributes and apply a mapping to map the LDAP group member names to Gateway group names. For example, the following groups are defined in Gateway: `iag-admin`, `iag-operator`, `iag-user`. If Gateway has been configured to look at the `memberOf` LDAP attribute for group memberships, then users may have the following group memberships: ```bash memberOf: group=iag-operator,cn=example,cn=com memberOf: group=iag-user,cn=example,cn=com ``` Configure Gateway to recognize the format of the information provided in the `memberOf` attribute so that Gateway can extract the relevant information. In the example above, Gateway will determine that this user belongs to both the `iag-operator` and `iag-user` groups. Gateway will combine the roles defined for both Gateway groups and provide that authorization to the user. Review the LDAP groups, Gateway groups, and the associated Gateway group roles to ensure that users are being given only those role permissions that are required to fulfill their responsibilities in Gateway. At least one Gateway group must be created that will allow roles to act as the administrator role, otherwise Gateway cannot be managed once LDAP authentication has been enabled. There is no special group designated as an administrator group. The group must be configured to ensure the name of the group is mapped uniquely from your LDAP user group memberships. ## Configure direct bind By default, the backend of LDAP authentication uses a **Search Bind** to connect to LDAP, find the user DN, and then authenticate with the correctly found DN and provided password combination. To utilize direct binds to make login times faster, the **User DN** and **Base DN** must point directly to the LDAP user location. In addition, the **User Login RDN** and **User Login Attribute** must be the same and set to use a direct bind. If you would prefer to log in users via their email address, you would not be able to do a direct bind, but could instead set the **User Login Attribute** to `mail`. ### Direct bind configuration example ```bash Search Bind: Unchecked User DN: "OU=users" User Login Attribute: cn User Login RDN: cn ``` ## Restart Gateway Once Gateway LDAP authentication has been configured or changed, Gateway must be restarted for Gateway to switch to the LDAP authentication provider. Changing Gateway group or role assignments does **not** require a restart. When Gateway LDAP is enabled and Gateway is restarted, users andItential Platform can authenticate to Gateway using their LDAP credentials. Enabling Gateway LDAP disables Gateway local authentication. ## Disable Gateway LDAP and enable local authentication In situations that require a return to using Gateway local authentication, such as not being able to authenticate any Gateway admins to Gateway, log into the host machine where Gateway is installed and edit the Gateway properties file to disable LDAP authentication, then restart Gateway. ## Troubleshoot LDAP configuration If you encounter a problem in LDAP configuration: #### Check Gateway groups and group names Check the Gateway groups and group names. #### Verify user group memberships in LDAP Verify users in LDAP are associated with the correct groups. #### Verify Gateway credentials If Gateway is unable to authenticate, make sure Gateway has been configured with the correct credentials. #### Review Gateway logs Review the Gateway logs to determine what, if any, LDAP connectivity or bind errors are returned. > Configure LDAP authentication for Itential Gateway to replace local authentication.