---
myst:
html_meta:
"description lang=en": "General LDAP configuration guide for Kasm Workspaces. "
"keywords": "Kasm, LDAP, Directory, Authentication"
"property=og:locale": "en_US"
---
```{title} LDAP Authentication
```
# LDAP Authentication
## Create an LDAP Configuration
The first step in configuring Kasm to use LDAP for authentication is to set up an LDAP configuration.
- Log into the Kasm Web UI as an administrator
- Click Access Management -> Authentication -> LDAP
- Click Add Configuration
```{figure} /images/ldap/ldap_config.webp
:align: center
**LDAP Config**
```
```{eval-rst}
+---------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| **Property** | **Description** |
+---------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Name | A name given to the configuration |
+---------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| URL | The LDAP connection URL to the LDAP server |
+---------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Search Base | The Base OU used for searching for objects. Kasm will use the search base DCs to identify users to the applicable LDAP Configuration. i.e DC=kasm,DC=core will map to @kasm.core |
+---------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Search Filter | The search filter used to identify user account names |
+---------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Group Membership Filter | This query is used to identify if the user is a member of a particular group. Used for Kasm group to LDAP group mapping |
+---------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Email Attribute | The user attribute used to denote the users email address |
+---------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Alternate Username Domains| Comma separated list of additional domain names that usernames should match on. Use an asterisks to match usernames without a domain name. See section below on domain name matching. |
+---------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Service Account DN | The service or ‘bot’ account used to issue queries to the LDAP server |
+---------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Service Account Password | The service or ‘bot’ account password |
+---------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Search Subtree | If enabled, objects beneath the Search Base will be discovered |
+---------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Auto Create App User | If enabled, Kasm will create an associated user account inside the application when the user first logs in. |
+---------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Enabled | Enable or disable this configuration |
+---------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
```
```{note}
In order for password resets to work with LDAP accounts, the service account must be provided the authority to reset user passwords in Active Directory and the connection must be made over a secure LDAPS connection.
```
## User Domain Name Matching
Users are expected to login with usernames in the format of username@domain.name. The domain-name portion of the username is used to find the appropriate LDAP configuration based on the domain name specified in the `Search Base` field. There are situations where it is desirable for the usernames to have a different domain name that what is Active Directory. In that case administrators can use the `Alternate Username Domains` field to specify a list of alternate domain names in the username that should be used to match to this LDAP configuration. For example 'greenearth.com,acquired_company.com' would be used with users logging in with username@greenearth.com and username@acquired_company.com in addition to the domain in the `Search Base` field.
An asterisks in the `Alternate Username Domains` is supported. An asterisks signifies that usernames that do not have a domain name at all should be matched to this LDAP configuration. Administrators can configure multiple LDAP configurations with an asterisks in the `Alternate Username Domains`, as long as they all point to the same domain. This can be done for redundancy, for example. However, you should not have multiple LDAP configurations that specify an asterisks in the `Alternate Username Domains` field, when they are pointed to different domains. This would result in nondeterministic behavior in matching users to the appropriate LDAP configuration.
## Test Authentication
After creating an LDAP configuration, you can test the settings by clicking the Test LDAP Connection icon on the LDAP Configurations Page.
```{figure} /images/ldap/test_ldap.webp
:align: center
**Test LDAP Config**
```
Enter known valid user credentials
## Common Errors
```{eval-rst}
+-----------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| **Error** | **Notes** |
+-----------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Authentication Error : socket connection | The Kasm API server cannot make a connection to the specified LDAP URL. Verify the URL is correct, and network connectivity between the two end points. |
| error while opening: timed out | |
+-----------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Authentication Error : automatic bind not successful - invalid Credentials | The password for the LDAP service account is invalid. Verify the password is correct and that the account is not locked out. Verify the Service Account DN is correct |
+-----------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Authentication Error : socket ssl wrapping error : [Errno 104] Connection reset by peer | LDAPS was specified in the LDAP URL but the LDAP server is not communicating over SSL |
+-----------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Authentication Error : error recieving data : [Errno 104] Connection reset by peer | The LDAP server rejected the connection. Verify that the port specified in the URL is correct. Verify that protocol LDAP or LDAPS is correct in the URL |
+-----------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Unable to locate user (test@kasm.local) | The user could not be located. Verify the Search Base and Search Filter parameters are correct |
+-----------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| LDAP Login failed for user (test@kam.local) : ({'message':'80090308: LdapErr:DSID-0C09042A, | The provided credentials are invalid or the account is locked out. |
| comment: AcceptSecurityContext error, data 52e, v3839\x00','saslCreds': None, 'result':49,'dn':", | |
| 'description': 'InvalidCredentials','type': 'bindResponse','refferals':None}) | |
+-----------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| LDAP password reset failed:({'result': 53, 'description': 'unwillingToPerform', 'dn': '', | LDAP without SSL was used in the connection, and password reset for a user was attempted. Windows servers only support changing passwords over secure LDAPS connections. |
| 'message': '0000001F: SvcErr: DSID-031A124C, problem 5003 (WILL_NOT_PERFORM), data 0\n\x00', | |
| 'referrals': None, 'type': 'modifyResponse'}) . | |
+-----------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
```
(ldap-linked-group)=
## Create LDAP linked Group
Kasm Workspaces can be configured to automatically map LDAP users to specific Kasm application groups via their LDAP group membership. The mapping is updated for each user when the user logs into the Kasm Web Application.
The mapping functionality can be accessed by using the arrow menu and selecting edit for the group you want to add a mapping to. Then selecting the **SSO Group Mappings** tab and click **Add SSO Mapping**.
The **Add SSO Mapping Screen** is presented the following fields are available to be filled in:
```{figure} /images/groups/edit_group.webp
:align: center
**Edit Group**
```
```{figure} /images/groups/sso_group_mappings.webp
:align: center
**SSO Group Mappings**
```
```{figure} /images/groups/add_sso_group_mapping_config.webp
:align: center
**Add SSO Group Mapping**
```
```{eval-rst}
+------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| **Property** | **Description** |
+------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| SSO Provider | A dropdown of the available SSO identity providers (LDAP, SAML, OpenID) configured in the system. |
+------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Assign All Users | A checkbox that indicates any user that authenticates with the defined SSO provider will be added to the Kasm group |
+------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Group Attributes | The LDAP DN to the desired group |
+------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
```
## LDAP Attribute Mapping
Additional LDAP user attributes are returned by the authentication request to the LDAP server. These LDAP user attributes can be mapped to Kasm User fields. Every time the user logs in, the Kasm user fields will be updated with the values returned by the LDAP server. See the documentation for your LDAP provider for a listing of user attributes.
These can be configured by editing an existing LDAP Authentication configuration, if creating a new configuration you will need to submit and edit to add them.
The following Kasm User fields can be populated with values from LDAP user attributes.
- First Name
- Last Name
- Phone
- Organization
- Notes
- City
- State
- Country
- Email
- Custom Attribute 1
- Custom Attribute 2
- Custom Attribute 3
```{figure} /images/ldap/ldap_attribute_mapping.webp
:align: center
**LDAP Attribute Mapping**
```
```{note}
Kasm can log all LDAP user attributes present in the login event, this is helpful for determining the attribute names. Add a LDAP Attribute Mapping with an attribute name of 'debug' and target any user field. The next time a user logs in, all LDAP user attributes and values will be logged by Kasm.
```
## Configuration Examples
```{toctree}
:maxdepth: 1
ldap/active_directory
ldap/jumpcloud
```