You can use the Authentication workspace to configure directory services for SaltStack Config using the LDAP protocol. This protocol is used for connecting to services such as Active Directory or Microsoft Azure.

Note: You can use more than one system at a time to authenticate users in SaltStack Config if needed. For example, you could use both a SAML-based IdP or LDAP-based IdP while simultaneously storing some user credentials natively on the RaaS server. However, SaltStack Config does not allow configuring more two SAML providers or two LDAP providers at the same time.

SaltStack Config uses the following back end process to authenticate LDAP-based systems:

  • Preview - When you preview your connection settings, SaltStack Config retrieves a sample list of users and groups from your LDAP server so you can verify you have entered the correct configuration parameters.
  • Login - When a user enters credentials in the SaltStack Config login form, the backend server checks for a match in the database at that time. It then initiates a multi-step lookup process and, upon finding a match, authenticates the user. Given this lookup process, enabled individual users in enabled groups do not appear in the Roles workspace until the user's first login.
  • Background tasks - SaltStack Config runs a background job periodically to look up each linked group and user in the Directory Service connection to ensure it still exists. If the group or user has been removed, the backend server deactivates its link in the database.
  • Archived groups and users - Any groups you remove from your Directory Service connection are archived. Even though these groups are inactive and users can’t log in, they’re still visible in the Roles workspace and can be selected. This also applies to any removed users previously visible in the Roles workspace.
  • Nested groups - When working with nested groups, by enabling a parent group, you also enable all child groups by default.

Configuring an LDAP connection

To configure LDAP, first create a connection, then enable specific LDAP users and groups to authenticate to SaltStack Config. Once you have enabled groups or users, you can define their Role-Based Access Control (RBAC) settings.

You can choose to prefill the fields with default settings customized to your directory service, such as Active Directory or OpenLDAP.

Note: The following steps should be completed by an experienced LDAP or Active Directory administrator who understands the overall LDAP system layout. Contact your administrator for assistance.

To set up an LDAP directory service:

  1. (Optional) Before configuring LDAP, it might be helpful to test your connection and queries using a third-party tool. For AD users, you might use LDP or ADSI Edit. For Linux users, the recommended tool is ldapsearch.
    Note: For more on testing with these tools, see How to verify and troubleshoot a Directory Service connection in the Support Center.
  2. Click Administration > Authentication on the side menu.
  3. Click Create.
  4. From the Configuration Type menu, select LDAP.
  5. (Optional) Under Settings, click Prefill Defaults and select your directory service from the dropdown.

    The default entries populate according to your selection. However, certain entries such as User Search DN are incomplete. Make sure to verify that entries match your directory service schema, and to replace placeholder text with the correct values for your service.

  6. Enter or verify information for your LDAP connection.

    Basic

    Field Description
    Name Name of LDAP connection. Since this is a display name only, enter any name would be useful to help differentiate this authentication backend from others.
    Host LDAP host server address, formatted as either a FQDN or IP address.
    Port Port where LDAP server is configured. The default is 389 for unencrypted LDAP, and 636 for LDAP over SSL.
    Background Sync SaltStack Config validates all users and group against the authentication backend at a set interval defined (in minutes) here.
    SSL
    Enable SSL
    Select to connect to the LDAP server over a Secure Sockets Layer (SSL) using the certificate specified in your RaaS server settings. If no configuration is provided, the system certificates store will be used to validate the SSL connection. For more on setting up the RaaS server, see Set up SSL certificates in the Installing and Configuring SaltStack Config guide.
    Important: As a best practice, select Enable SSL. When this option is left unselected, SaltStack Config transmits information in plain text over an insecure connection.
    Validate Certificate
    Select to ensure the SSL certificates are validated upon connecting. Leave unselected to skip validation, for example when using self-signed certificates (not recommended for production).

    Authentication

    Field Description
    Auth Base DN

    Base LDAP Distinguished Name. This is the location groups and users are queried from, for example DC=sse,DC=example,DC=com.

    Note: The LDAP details page includes separate input fields for Person Object Class, Account Attribute Name, Group Class, Group Attribute Name, and Sync Scheduling, as described below. Therefore, do not include these objects in the Base DN field.
    Admin Bind DN Administrator DN configured for the LDAP server. SaltStack Config uses this to authenticate to the directory for user and group lookups. Enter input based on the following syntax: cn=Administrator,cn=Users,dc=example,dc=com.
    Admin Bind DN Password

    The administrator’s individual password.

    This is stored with encryption in the database. It is not stored in plaintext.
    Auth Bind DN Filter

    Filter applied to select a specific user. The result of this search is a user DN that SaltStack Config uses to bind to the directory and grant the user access to SaltStack Config. This is useful for limiting the number of results that are returned from a given search.

    Note: Because the filter syntax can become quite complex, a best practice is to test the entry using LDP, ldapsearch, or a similar tool to validate your entry and make any adjustments before filling out this field.

    The following sample filter would return only an account matching the provided username belonging to the DevOps or Level II groups.

    (&(objectclass=user)(sAMAccountName={username})(|(memberOf=CN=DevOps,OU=Groups,OU=TestCompanyHQ,DC=adtest,DC=com)(memberOf=LevelII,OU=Groups,DC=adtest,DC=com)))

    If you are using prefilled defaults, make sure to replace placeholder text with the correct values for your directory service.

    Note: When configuring a forest structure, leave this field blank.
    Remote Unique ID Attribute Name Name of the value used to identify unique entries. This is the unique ID attribute for all entries. In AD this is ObjectGUID.

    Groups

    Field Description
    Group Search DN The search base for groups. For example, in AD this might be cn=Groups,dc=example,dc=com. Indicates where in the directory to search for groups. Use along with Group Search Scope below.
    Group Search Scope

    Indicates directory search depth from the base indicated in Group Search DN and can have one of four values:

    baseObject
    Value 0, often referred to as base. Use this to search only for this object and no other.
    singleLevel
    Value 1, often referred to as one. Use this to consider only immediate children of the base entry for matches.
    wholeSubtree
    Value 2 (or SUBTREE in ldap3), often referred to as sub. Use this to search to base and all of its subordinates to any depth.
    subordinateSubtree
    Value 3, often referred to as subordinates. This is the same as wholeSubtree but the base search entry is ignored.
    Group Search DN Filter Search filter for extracting groups from the directory. This is typically (objectClass=group), but in some AD configurations it might be (objectCategory=group). Use in addition to Group Class for more granularity.
    Group Class Object class name used to define groups, for example groupOfNames.
    Group Name Attribute The name of the attribute that you want to use for group name. Enter a single-value attribute, not multi-value.
    Group Membership Attribute The name of the attribute in the user entry that contains the group name, for example, memberOf.

    Users

    Field Description
    User Search DN The search base for users, for example, cn=Users,dc=example,dc=com in AD or cn=people,cn=accounts,dc=example,dc=com in other directory services. Indicates where in the directory to search for users. Use along with User Search Scope below.
    User Search Scope Indicates directory search depth from the base indicated in User Search DN and can have one of four values. See the four values described in Group Search Scope.
    User Search DN Filter Search filter for extracting users from the directory. This is typically (objectClass=person) but in some AD configurations it might be (objectCategory=user).
    Person Class Directory Service class name containing users you want to enable to log in. Most systems (including Active Directory) use person, but some may prefer user or inetOrgPerson.
    User ID Attribute The unique name of the user account attribute. For AD, this is sAMAccountName. For other services, it is often uid or memberUid.
    User Membership Attribute The name of the attribute in the group entry that contains the user name. Possible examples include member or uniquemember.
  7. To preview your settings without saving, click Update Preview.

    The preview window shows users and groups selected for your connection. You can select either the Groups or Users tab to preview users and groups associated with the service as needed.

  8. Click Save.

    Your LDAP configuration has been saved. To verify the configuration is correct, you might want to try logging in to SaltStack Config from a test user account. If you’re not able to successfully log in, see Troubleshooting for tips.

    Note: For LDAP configurations, SaltStack Config stores the connection settings, including the groups and users identified. It retrieves only groups and users within the scope you have defined and does not synchronize the entire directory.

    Over time you might need to refresh or re-sync your LDAP directory. For example, you should update your directory if you added new users and you want to enable them in SaltStack Config.

Enabling groups and users

After setting up your LDAP connection, you then need to configure directory service groups and ensure users can log in to SaltStack Config. To configure directory service groups:

  1. In the Authentication workspace, select the required LDAP configuration.
  2. Select the Groups tab to see a list of groups retrieved from your LDAP configuration.
    Note: If you’re retrieving a large number of groups, the page might take up to a minute to load.
  3. Select the groups you want to enable in SaltStack Config.
  4. Select the Users tab to see a list of users retrieved from your LDAP configuration.
    Note: If you’re retrieving a large number of users, the page might take up to a minute to load.
  5. Select the users you want to enable in SaltStack Config.
    Note: Any users included in enabled groups are already selected and can’t be deselected.
    directory-service-users-enabled-group
  6. Click Save.

    You can now define Role-Based Access Control (RBAC) settings for the selected groups. However, the Roles workspace allows you to manage settings for individual users included in the selected groups only after the user’s first login. To delete groups or users, deselect the group or user and then click Save.

    For more on RBAC in SaltStack Config, see How do I define user roles.

Troubleshooting your LDAP Connection

If you’re not able to successfully preview your connection, follow these troubleshooting steps.
Problem Description Solution
I’m not able to preview my connection

If you’re not able to preview your groups and users, in many cases this is due to a connection problem between your LDAP server and SaltStack Config, or an invalid entry in the LDAP configuration form.

  1. Ensure that TCP connections from SaltStack Config to the selected port on the LDAP server are allowed.
  2. Double-check your form entries and validate syntax using a third-party tool. See How to verify and troubleshoot a Directory Service connection.
  3. If neither of the previous items helps resolve the issue, see the Other issues section below.
  4. If none of the above items helps, contact customer support.
When trying to preview my connection, the page gets stuck loading If the page gets stuck loading for over two minutes, restart the RaaS service, then delete and re-create the configuration.
  1. Open the RaaS log.
    tail -f /var/log/raas/raas

    The log contains an error similar to the following:

    [ERROR    :256][ForkPoolWorker-2:10253][ldap_preview_background_task(some_uuid)]
Task ldap preview_background_task[some_uuid]raised unexpected: KeyError('ad-1_preview')
  2. Stop and then restart the RaaS service.
    systemctl stop raas
systemctl start raas
  3. Return to the SaltStack Config user interface and delete the LDAP connection.
    Note:

    You might want to copy and paste your configuration entries into a backup text file before deleting.

  4. Create the LDAP configuration again.
Other miscellaneous issues

If you’ve already configured and saved your LDAP connection but users aren’t able to log in, or if you are encountering any other issues, check the raas logs with extended debugging enabled to help determine the root cause.

To enable extended debugging:

  1. On RaaS, open /etc/raas/raas.
  2. Make the following changes:
    • Under Loggingoptions, uncomment log_file_loglevel:debug
    • Under AD/LDAPdriverconfiguration, uncomment log_level and set to log_level:EXTENDED
  3. Stop and then restart the RaaS service.
    systemctl stop raas
systemctl start raas
  4. View the raas log. 
    tail -f /var/log/raas/raas

Some common errors you might see in the logs are as follows:

  • Wrong settings for connection (SSL). Adjust your SSL settings.
    [raas.utils.validation.schemas.settings][DEBUG   :546 ][Webserver:9096]
Error while connecting to AD/LDAP Server. SSL connection issues: socket
ssl wrapping error: [Errno 104] Connection reset by peer
  • Wrong password for Admin BIND DN. Verify and re-enter your password.
    [raas.utils.rpc   ][DEBUG   :284 ][Webserver:9095]
Processed RPC request(129360670417695). Response:
{'riq': 129360670417695, 'ret': None, 'error': {'code': 3004, 'message':
'Request validation failure.', 'detail': {'_schema':
['Credentials are not valid']}}, 'warnings': []}
  • The prefilled default Auth Bind DN Filter is creating a conflict. Leave the field blank, or use {username} instead of {{username}}.
    Note:

    You might encounter this error when you’ve already saved your LDAP connection, but users aren’t able to log in.

    [var.tmp._MEIBCyG76.raas.mods.auth.ldap][DEBUG   :903 ][Webserver:9096]
Running _get_auth_backend_user with this search_filter: (&(objectclass=person)(sAMAccountName={username}))

[var.tmp._MEIBCyG76.raas.mods.auth.ldap][DEBUG   :931 ][Webserver:9096]
Could not find any user using '(&(objectclass=person)(sAMAccountName={username}))'
as the search filter in the ldap backend under the ad-1 configuration.
Trying remote_uid 'None'

[var.tmp._MEIBCyG76.raas.mods.auth.ldap][DEBUG   :963 ][Webserver:9096]
Could not find any user using '(&(objectClass=person)(objectGUID=None))'
as the search filter in the ldap backend under the ad-1 configuration.