# SSO with LDAP

This guide walks you through configuring Single Sign-On (SSO) for the API7 Dashboard using the LDAP protocol. Unlike OIDC and SAML (which use browser redirects), LDAP authentication sends the user's credentials directly from the dashboard to the LDAP server for verification.

## How It Works[​](#how-it-works "Direct link to How It Works")

<!-- -->

1. The user enters their username and password on the dashboard login page using the LDAP login option.
2. The dashboard connects to the LDAP server using the configured Bind DN (service account).
3. The dashboard searches for the user using the Base DN and Identifier attribute.
4. If found, the dashboard attempts to bind as the user with the provided password.
5. On successful authentication, the dashboard extracts user attributes and creates or updates the account.
6. If role and permission boundary mappings are configured, they are applied on each login.

## Prerequisites[​](#prerequisites "Direct link to Prerequisites")

Before you begin, ensure you have:

* A running API7 Gateway deployment with dashboard access.

* An LDAP-compatible directory server (e.g., OpenLDAP, Microsoft Active Directory, FreeIPA).

* A service account (Bind DN) with read/search permissions on the user directory.

* The following information:

  <!-- -->

  * **Host and Port**: LDAP server address and port (default: `389` for LDAP, `636` for LDAPS).
  * **Base DN**: The root of the directory tree to search for users (e.g., `dc=example,dc=com`).
  * **Bind DN**: The distinguished name of the service account (e.g., `cn=read-only-admin,dc=example,dc=com`).
  * **Identifier**: The attribute that uniquely identifies users (e.g., `uid` for OpenLDAP, `sAMAccountName` for Active Directory).

## Step 1: Create an LDAP Login Option[​](#step-1-create-an-ldap-login-option "Direct link to Step 1: Create an LDAP Login Option")

1. In the API7 Dashboard, navigate to **Organization > Settings**.
2. Click **Add Login Option**.
3. Fill in the configuration:

| Field                  | Description                                                                 | Example                                |
| ---------------------- | --------------------------------------------------------------------------- | -------------------------------------- |
| **Name**               | Display name shown on the login page as "Login with {Name}"                 | `Corporate LDAP`                       |
| **Provider**           | Select `LDAP`                                                               | —                                      |
| **Host**               | LDAP server hostname or IP address                                          | `ldap.example.com`                     |
| **Port**               | LDAP server port                                                            | `389`                                  |
| **Base DN**            | Root of the directory tree for user searches                                | `dc=example,dc=com`                    |
| **Bind DN**            | Distinguished name of the service account for LDAP searches                 | `cn=read-only-admin,dc=example,dc=com` |
| **Bind Password**      | Password for the Bind DN service account                                    | `********`                             |
| **Identifier**         | Attribute that forms the user DN with the login username                    | `uid`                                  |
| **Use SSL**            | Enable TLS encryption for the LDAP connection                               | `false`                                |
| **SSL Verify**         | Verify the LDAP server's TLS certificate (only applies when SSL is enabled) | `true`                                 |
| **Timeout**            | Connection timeout in seconds                                               | `10`                                   |
| **Attributes Mapping** | Map LDAP attributes to API7 user fields                                     | See below                              |

### Attribute Mapping[​](#attribute-mapping "Direct link to Attribute Mapping")

| API7 Field | LDAP Attribute (OpenLDAP) | LDAP Attribute (Active Directory) |
| ---------- | ------------------------- | --------------------------------- |
| `username` | `uid`                     | `sAMAccountName`                  |
| `email`    | `mail`                    | `mail`                            |
| `name`     | `cn`                      | `displayName`                     |

### TLS Configuration (Optional)[​](#tls-configuration-optional "Direct link to TLS Configuration (Optional)")

For secure LDAP connections (LDAPS), enable **Use SSL** and optionally provide:

| Field                   | Description                                                        |
| ----------------------- | ------------------------------------------------------------------ |
| **Root CA Certificate** | PEM-encoded CA certificate to verify the LDAP server's certificate |
| **Client Certificate**  | PEM-encoded client certificate for mTLS authentication             |
| **Client Key**          | PEM-encoded client private key for mTLS authentication             |

4. Click **Add**.

## Step 2: Verify SSO Login[​](#step-2-verify-sso-login "Direct link to Step 2: Verify SSO Login")

1. Sign out of the API7 Dashboard.
2. On the login page, select the **Login with {Name}** option.
3. Enter your LDAP username and password.
4. After successful authentication, you are logged in to the dashboard.

The user appears under **Organization > Users**. By default, the user has no roles assigned.

important

Deleting a user in the Dashboard removes their roles and permission boundaries, but the user can still log in again as a new user. To fully revoke access, remove or disable the user in the LDAP directory.

## Configure Role Mapping[​](#configure-role-mapping "Direct link to Configure Role Mapping")

Role mapping automatically assigns API7 roles to LDAP users based on directory attributes. This requires the relevant attributes to be available on LDAP user entries.

info

Automatic role mappings take precedence over manual role assignments. When mappings are active, any manual changes are overwritten on the user's next login.

### Step 1: Configure LDAP User Attributes[​](#step-1-configure-ldap-user-attributes "Direct link to Step 1: Configure LDAP User Attributes")

Role mapping relies on attributes present in the LDAP user entry. There are two common approaches:

#### User Attribute[​](#user-attribute "Direct link to User Attribute")

Assign a direct attribute to users. For example, add a `title` attribute with the value `admin`:

```
dn: uid=alice,dc=example,dc=com

objectClass: inetOrgPerson

uid: alice

cn: Alice Johnson

mail: alice.johnson@example.com

title: admin
```

In API7, use the mapping rule: Attribute `title`, Operation `Exact Match`, Value `admin`.

#### Group Membership[​](#group-membership "Direct link to Group Membership")

Add users to LDAP groups and use the `memberOf` attribute (requires the `memberOf` overlay to be enabled in OpenLDAP):

```
dn: uid=alice,dc=example,dc=com

objectClass: inetOrgPerson

uid: alice

cn: Alice Johnson

mail: alice.johnson@example.com

memberOf: ou=developers,dc=example,dc=com

memberOf: ou=admins,dc=example,dc=com
```

In API7, use the mapping rule: Attribute `memberOf`, Operation `Contains String in Array`, Value `admins`.

tip

For Active Directory, `memberOf` is available by default. For OpenLDAP, you may need to enable the [memberOf overlay](https://www.openldap.org/doc/admin26/overlays.html#Member%20Of).

### Step 2: Enable Role Mapping in API7[​](#step-2-enable-role-mapping-in-api7 "Direct link to Step 2: Enable Role Mapping in API7")

1. In the API7 Dashboard, navigate to **Organization > Settings**.
2. Select your LDAP login option.
3. Enable **Role Mapping**.
4. Configure the mapping rule:

| Field              | Description                                                                                                | Example       |
| ------------------ | ---------------------------------------------------------------------------------------------------------- | ------------- |
| **Internal Role**  | The API7 role to assign                                                                                    | `Super Admin` |
| **Role Attribute** | The LDAP attribute name to match                                                                           | `title`       |
| **Operation**      | Comparison method: `Exact Match`, `Contains String`, `Exact Match in Array`, or `Contains String in Array` | `Exact Match` |
| **Role Value**     | Expected attribute value                                                                                   | `admin`       |

5. Click **Enable**.

### Permission Boundary Mapping[​](#permission-boundary-mapping "Direct link to Permission Boundary Mapping")

Permission boundary mapping works the same way as role mapping but assigns [permission policies](https://docs.api7.ai/api7-gateway/security-and-compliance/permission-policies-and-boundaries.md) as boundaries instead of attaching roles. Enable **Permission Boundary Mapping** in the login option settings and configure the mapping rules with the same attribute-matching approach.

## Delete a Login Option[​](#delete-a-login-option "Direct link to Delete a Login Option")

warning

Deleting a login option removes all dashboard users associated with that option.

1. Navigate to **Organization > Users** and verify which users are associated with this login option.
2. Navigate to **Organization > Settings**.
3. Click **Delete** on the login option.

note

At least one login option must remain enabled at all times. You cannot delete or disable the last remaining enabled login option.

## Additional Resources[​](#additional-resources "Direct link to Additional Resources")

* [SSO with OIDC](https://docs.api7.ai/api7-gateway/security-and-compliance/sso-oidc.md)
* [SSO with SAML](https://docs.api7.ai/api7-gateway/security-and-compliance/sso-saml.md)
* [SSO Overview (Enterprise Feature)](https://docs.api7.ai/api7-gateway/enterprise-features/dashboard-sso.md)
* [Roles and Permission Policies](https://docs.api7.ai/api7-gateway/security-and-compliance/role-based-access-control.md)
* [Role-Based Access Control](https://docs.api7.ai/api7-gateway/security-and-compliance/role-based-access-control.md)