Skip to content

Auth polishing #336

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
christophdb merged 7 commits into from
Jun 19, 2026
Merged

Auth polishing #336

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
943c539
docs(auth): correct and align LDAP/SAML/OAuth authentication docs
christophdb Jun 19, 2026
8753186
docs(auth): unify restart wording and add enterprise flags
christophdb Jun 19, 2026
e8b9953
docs(auth): scope LDAP enterprise flag to sync-based features
christophdb Jun 19, 2026
11d6ff2
docs(auth): document OAuth login flow and SSO method precedence
christophdb Jun 19, 2026
336be3f
docs(ldap): defuse wide table cells in the parameter tables
christophdb Jun 19, 2026
de3aa78
docs(ldap): shorten the LDAP_FILTER example value
christophdb Jun 19, 2026
d066083
docs(saml): tighten the config parameter table Values column
christophdb Jun 19, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 1 addition & 8 deletions docs/configuration/authentication/auth-switch.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -77,11 +77,4 @@ Then you can reset the user's password, e.g. via the web interface. The user wil

## Use LDAP and SAML together

SeaTable supports since version 3.5 to use SAML and LDAP together for one user. To activate this function the following configuration has to be set in `dtable_web_settings.py`.

```bash
# Enable that SAML and LDAP use the same username
LDAP_SAML_USE_SAME_UID = True
```

More details about this option will follow soon.
Using SAML for authentication together with LDAP for synchronization is not a migration between authentication types but a permanent combined setup, available since SeaTable 3.5. It is enabled with `LDAP_SAML_USE_SAME_UID` and described in detail under [LDAP › LDAP and SAML](./ldap.md#ldap-and-saml).
2 changes: 1 addition & 1 deletion docs/configuration/authentication/jwt.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ Here is a short introduction into JWT:

## How to configure and use JWT?

To enable the login with JWTs you have to define a secret key in your `dtable_web_settings.py` and restart the SeaTable service:
To enable the login with JWTs you have to define a secret key in your `dtable_web_settings.py` and [restart SeaTable](../../maintenance/restart-seatable.md):
```python
SSO_SECRET_KEY = 'your-shared-secret-like-a38B232XQJLx392871#2DEF_dowfWE#_39dwefidWFwLw39fDFEF='
```
Expand Down
49 changes: 41 additions & 8 deletions docs/configuration/authentication/ldap.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ Additionally, LDAP in SeaTable can be configured to work seamlessly with SAML.

## LDAP Authentication

To enable LDAP Authentication (LDAP Auth), add the following parameters to `dtable_web_settings.py`, customize to your environment, and restart the SeaTable service:
To enable LDAP Authentication (LDAP Auth), add the following parameters to `dtable_web_settings.py`, customize to your environment, and [restart SeaTable](../../maintenance/restart-seatable.md):

| Parameter | Description | Values |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- |
Expand Down Expand Up @@ -56,13 +56,14 @@ The following parameters are also available, but optional:

| Parameter | Description | Values |
| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
| LDAP_FILTER | Filter for users who can log in, e.g. a certain security group | LDAP filter, e.g. 'memberOf=CN=group,CN=developers,DC=example,DC=com' |
| LDAP_GROUP_FILTER | | |
| LDAP_FILTER | Filter for users who can log in, e.g. a certain security group | LDAP filter, e.g. `memberOf=CN=SeaTable_Users,…` |
| LDAP_USER_UNIQUE_ID | LDAP attribute whose value is stored as the user's `uid` in `social_auth_usersocialauth` and used to recognize a returning user. Choose an attribute that never changes over the user's lifetime, because if it changes, SeaTable treats the user as new. Binary GUID/UUID values are decoded automatically; default value is '' | Attribute name, e.g. `objectGUID` (AD) or `entryUUID` (OpenLDAP) |
| LDAP_GROUP_FILTER | Additional filter applied when searching for groups to synchronize (group sync only). It is combined with the configured group object class using a logical AND. Leave empty to sync all groups of that class; default value is '' | LDAP filter, e.g. `cn=SeaTable*` |
| LDAP_USER_ROLE_ATTR | Name of user role in the LDAP server | Attribute name, e.g. `title` |
| LDAP_USER_FIRST_NAME_ATTR | First part of the user's SeaTable nickname when nickname is spliced; default value is '' | Attribute name, e.g. `givenName` |
| LDAP_USER_LAST_NAME_ATTR | Second part of the user's SeaTable nickname when nickname is spliced; default value is '' | Attribute name, e.g. `sn` |
| LDAP_USER_NAME_REVERSE | Option to reverse order of first name and last name f spliced nickname; default value is `False` | `True` or `False` |
| LDAP_SAML_USE_SAME_UID | Option to allow users to log in via LDAP and SAML using the same username | `True` or `False` |
| LDAP_SAML_USE_SAME_UID | Use SAML for login and LDAP only for synchronization, mapping both to one shared account; disables interactive LDAP login (see [LDAP and SAML](#ldap-and-saml)) | `True` or `False` |
| LDAP_CONTACT_EMAIL_ATTR | Alternative attribute as a mail address when LDAP_LOGIN_ATTR is not `mail`; the attribute overrides the email address imported through LOGIN_ATTR; default value is '' | |
| LDAP_EMPLOYEE_ID_ATTR | ID of the employee | Attribute name, e.g. `33` |

Expand All @@ -76,6 +77,8 @@ To enable LDAP authentication via SASL, add the following parameters to `dtable_

## LDAP Synchronisation

<!-- md:flag enterprise -->

To enable LDAP synchronisation (LDAP Sync), LDAP Auth must be configured and the following parameters added to `dtable_web_settings`:

| Parameter | Description | Values |
Expand All @@ -85,7 +88,7 @@ To enable LDAP synchronisation (LDAP Sync), LDAP Auth must be configured and the
| LDAP_GROUP_MEMBER_UID_ATTR | User attribute set in 'memberUid' option, which is used in "posixGroup"; default value is `uid` | |
| LDAP_USER_OBJECT_CLASS | Name of the class used to search for user objects; default value is `person` | |
| LDAP_GROUP_OBJECT_CLASS | Name of the class used to search for group objects; default value is `group` | For LDAP: `groupOfNames`, `groupOfUniqueNames`, `posixGroup`<br />For AD: `group` |
| LDAP_GROUP_UUID_ATTR | ...; default value is `ObjectGUID` | For LDAP: refer to https://ldapwiki.com/wiki/Universally%20Unique%20Identifier<br />For AD: `ObjectGUID` |
| LDAP_GROUP_UUID_ATTR | ...; default value is `ObjectGUID` | For LDAP: refer to [UUID](https://ldapwiki.com/wiki/Universally%20Unique%20Identifier)<br />For AD: `ObjectGUID` |
| SYNC_GROUP_AS_DEPARTMENT | Option to sync LDAP groups as departments rather than SeaTable groups | `True` or `False` |
| LDAP_DEPARTMENT_NAME_ATTR | Name of the department when SYNC_GROUP_AS_DEPARTMENT = True, the default department name is the OU name | Object name, e.g. `description` |

Expand All @@ -99,12 +102,42 @@ sync_interval = 60 # The unit is seconds

## LDAP and SAML

In some situations, it is useful to configure LDAP - especially LDAP Sync - and SAML as authentication providers. In this case, SeaTable must be prevented from creating two different users (as identified by the `username`) for one and the same `uid` when the person authenticates via LDAP and SAML, which would be the default behavior.
<!-- md:flag enterprise -->

In some situations it is useful to use **SAML for authentication** and **LDAP for synchronization** at the same time. A typical example is a setup where users sign in through an Identity Provider (IdP) via SAML SSO, while the user and group information is provisioned and kept up to date from your LDAP directory.

Add the following parameter to `dtable_web_settings.py` to instruct SeaTable to use the same `username` no matter if a user (as identified by its `uid`) authenticates via LDAP or SAML.
Without further configuration, SeaTable would treat the LDAP identity and the SAML identity of one and the same person as two different users. Each of them would receive its own `username`, and SeaTable would create two separate accounts. To prevent this, add the following parameter to `dtable_web_settings.py`:

```python
LDAP_SAML_USE_SAME_UID = True
```

When enabled, SeaTable creates an additional record for the authenticating user in social_auth_usersocialauth when the user logs in using LDAP. This record maps the `username` to the `uid` for the SAML provider.
### What this setting does

When `LDAP_SAML_USE_SAME_UID = True`:

- **Interactive login via LDAP is disabled.** Users authenticate **only via SAML**. An attempt to log in with LDAP credentials fails with the generic message "Incorrect account or password". This is by design, and nothing is written to `dtable_web.log`.
- **LDAP is used for synchronization only.** The [LDAP Sync](#ldap-synchronisation) job provisions the accounts and keeps users and groups up to date.
- For every user it provisions, LDAP Sync additionally writes a record into `social_auth_usersocialauth` for the SAML provider that maps the user's `username` to the same `uid`. This bridge record is what lets the subsequent SAML login resolve to the account created by LDAP Sync instead of creating a second one.

The three building blocks therefore play these roles:

| Component | Role in combined mode |
| --------- | --------------------------------------------------------------- |
| SAML | The only interactive login method |
| LDAP Sync | Provisions accounts and groups, and writes the SAML bridge record |
| LDAP Auth | Disabled (its connection settings are still required by LDAP Sync) |

### Requirements

- **LDAP Sync must be configured and enabled** (see [LDAP Synchronisation](#ldap-synchronisation)). The LDAP connection parameters (`LDAP_SERVER_URL`, `LDAP_ADMIN_DN`, `LDAP_ADMIN_PASSWORD`, `LDAP_BASE_DN`, …) are still required, because the sync job uses them. This applies even though interactive LDAP authentication is off.
- **The IdP must send the same `uid` as LDAP.** The value the IdP sends as the SAML `uid` (typically the NameID) must be exactly the value of the LDAP attribute used as the user's login identifier (`LDAP_LOGIN_ATTR`, e.g. `sAMAccountName`).
- **The comparison is case-sensitive.** While `sAMAccountName` is case-insensitive in Active Directory, the `uid` match in `social_auth_usersocialauth` is case-sensitive. If LDAP provides `jdoe` and the IdP sends `JDoe`, the two will not match and a second account is created.

### Typical setup procedure

1. Configure and test [SAML](./saml.md) on its own with a test user, then delete that test account again.
2. Configure [LDAP Synchronisation](#ldap-synchronisation).
3. Set `LDAP_SAML_USE_SAME_UID = True` and [restart SeaTable](../../maintenance/restart-seatable.md).
4. Let the sync job run (or wait for the configured `sync_interval`) so the accounts and their SAML bridge records exist.
5. Users sign in via SAML. Do not offer the LDAP login form in this mode, because an LDAP login attempt always fails by design.
Loading
Loading