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.

Authentication process

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.

    If you’re not able to successfully preview your connection, see Troubleshooting for tips.

  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. For more on how this works, see Authentication process.

    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.