# LDAP and Active Directory

> Prepare your directory so OneiD can sign users in with their directory accounts, and decide how directory groups become roles.

Source: https://oltinid.com/docs/sign-in-sources/ldap/ · Section: Sign-in sources · All OneiD documentation: https://oltinid.com/llms.txt

With LDAP or Active Directory as the sign-in source, users sign in to OneiD with their directory user name and password. OneiD checks the password against your directory over LDAPS and never stores it. Your directory stays the place where accounts and groups are managed.

## How sign-in works

1. An application sends the user to OneiD.
2. The user enters the directory user name and password on the OneiD sign-in page.
3. OneiD checks the password with your directory over an encrypted LDAPS connection.
4. OneiD reads the user's details and groups from the directory and turns the groups into roles.
5. If MFA applies, the user enters a code from an authenticator app. See [OneiD accounts and MFA](https://oltinid.com/docs/sign-in-sources/oneid-accounts/#multi-factor-authentication); MFA works the same way for directory users.
6. OneiD issues tokens to the application.

Applications receive the same tokens as with any other source, with `idp` set to `ldap`.

### The user's `sub`

For directory users, `sub` is the directory account name in lower case, without the domain. For example, the account `JDoe` in the domain `EXAMPLE` has the `sub` value `jdoe`. Applications should still treat `sub` as opaque and key users by `iss` and `sub`.

## What to give your OneiD operator

Your OneiD operator configures the connection. For a deployment hosted by OneiD, the operator is the OneiD team. Prepare the following and send the secret values over a secure channel, never by plain email.

- [ ] **Directory server address.** The host name of one directory server that OneiD can reach over LDAPS.
- [ ] **Port.** 636 unless your directory uses another LDAPS port.
- [ ] **Network access.** Allow connections from OneiD to that server and port. Ask your operator for the addresses OneiD connects from.
- [ ] **Service account.** A directory account with read access to the users and groups that will sign in. OneiD uses it to look users up. It needs no write access.
- [ ] **Service account password.** Supplied as a secret.
- [ ] **Bind type.** Basic or Negotiate.
- [ ] **Search base.** The part of the directory that contains the users, for example `OU=Staff,DC=example,DC=com`.
- [ ] **Domain.** Your directory domain, for example `EXAMPLE`.
- [ ] **Server certificate thumbprint (optional).** The SHA-256 thumbprint of the directory server's certificate. With it, OneiD accepts only that certificate.
- [ ] **Group rules.** The required group, the administrators group, the group-to-role mappings and, if wanted, a prefix for unmapped groups. See below.

## Map directory groups to roles

OneiD turns the user's directory groups into roles at each sign-in. The rules are described in [Where users come from](https://oltinid.com/docs/sign-in-sources/overview/#from-groups-to-roles). An example plan you could send to your operator:

| Rule | Directory group | Result |
|---|---|---|
| Required group | `App-Users` | Only members can sign in. |
| Administrators group | `OneiD-Admins` | Members get OneiD's `All` administrator role. |
| Mapping | `Order-Viewers` | Role `OrderViewer` |
| Mapping | `Order-Managers` | Role `OrderManager` |
| Pass-through prefix | `dir-` | An unmapped group `Finance` becomes role `dir-Finance`. |

The same plan written out:

```yaml
requiredGroup: App-Users
administratorsGroup: OneiD-Admins
mappings:
  Order-Viewers: OrderViewer
  Order-Managers: OrderManager
passThroughUnmappedGroups: true
passThroughPrefix: dir-
```

This is a planning format to agree with your operator, not a configuration file you upload.

> **Warning:** Members of the administrators group can change every setting in OneiD. Use a small group that exists only for this purpose.

Leave out pass-through if your applications only need a few roles. Fewer roles in tokens are easier to reason about.

## Limitations

- **One directory server.** OneiD connects to one server. There is no list of fallback servers. When that server cannot be reached, directory users cannot sign in. Talk to your operator about how to keep the address you give available.
- **Cloud-only accounts.** Accounts that exist only in Microsoft Entra ID and not in your on-premises directory cannot sign in through LDAP. Microsoft Entra ID is not available as a sign-in source; [talk to us](https://oltinid.com/contact/?topic=organisation) if you need it.
- **One source per deployment.** A deployment that uses your directory does not also offer OneiD accounts or an upstream provider.

## Learn more

- [Where users come from](https://oltinid.com/docs/sign-in-sources/overview/)
- [OneiD accounts and MFA](https://oltinid.com/docs/sign-in-sources/oneid-accounts/)
- [Scopes, claims and roles](https://oltinid.com/docs/guides/scopes-claims-roles/)
- [Run OneiD in your own environment](https://oltinid.com/docs/operate/overview/)