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

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

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

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

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

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

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

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

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

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

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=admins,dc=example,dc=com

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

tip

For Active Directory, memberOf is available by default. For OpenLDAP, you may need to enable the memberOf overlay.

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 works the same way as role mapping but assigns permission policies 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

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

• SSO with OIDC
• SSO with SAML
• SSO Overview (Enterprise Feature)
• Roles and Permission Policies
• Role-Based Access Control