Skip to main content

LDAP Authentication

LDAP (Lightweight Directory Access Protocol) authentication enables organizations to leverage their existing LDAP infrastructure for both API Portal and API authentication in Traefik Hub.

Introduction​

LDAP authentication in Traefik Hub supports two distinct use cases:

  1. Portal Authentication - Authenticate users accessing the API Portal (Developer Portal)
  2. API Authentication - Validate API requests using LDAP credentials

Both authentication methods can be configured through Kubernetes CRDs or the Traefik Hub Dashboard UI, and work in both online and offline modes.

LDAP Use Cases​

Portal Authentication​

Portal authentication uses LDAP to authenticate users accessing the API Portal. This is configured using the APIPortalAuth CRD.

How it works:

  • Users authenticate to the portal using their LDAP username and password
  • Session-based authentication with cookies
  • User attributes (email, name) synchronized from LDAP in online mode
  • Group membership controls portal access

Common scenarios:

  • Developer portal access for internal developers
  • Partner portal with LDAP-based single sign-on
  • Self-service API discovery and documentation

Authentication Flow:

API Authentication​

API authentication uses LDAP to validate individual API requests. This is configured using the APIAuth CRD.

How it works:

  • API consumers send HTTP Basic Authentication credentials with each request
  • Credentials validated against LDAP server per request
  • LDAP username must match an application ID in a ManagedApplication
  • Access granted via ManagedSubscription

Common scenarios:

  • Internal API access with service accounts
  • Machine-to-machine communication
  • Legacy application integration

Authentication Flow:

Configuration Example​

LDAP authentication can be configured in two ways:

Kubernetes CRDs​

Use APIPortalAuth for portal authentication or APIAuth for API authentication.

apiVersion: hub.traefik.io/v1alpha1
kind: APIPortalAuth
metadata:
  name: ldap-portal-auth
  namespace: apps
spec:
  ldap:
    url: ldaps://ldap.example.com:636
    baseDN: dc=example,dc=org
    bindDN: cn=admin,dc=example,dc=org
    bindPasswordSecretName: ldap-bind-secret
    searchFilter: (&(objectClass=inetOrgPerson)(uid=%s))
    groups:
      memberOfAttribute: memberOf
    attributes:
      userId: uid
      email: mail
      firstname: givenName
      lastname: sn

Dashboard UI​

Configure LDAP through the Traefik Hub Dashboard web interface:

  • Portal Authentication: Navigate to Auth Settings → Identity Providers → LDAP
  • API Authentication: Navigate to Auth Settings → Gateway Access → Basic auth
UI vs CRD Configuration
  • UI Configuration: Convenient for quick setup and testing, stored in Traefik Hub platform
  • CRD Configuration: Infrastructure as Code, version controlled, required for offline mode
  • Precedence: CRD configuration takes precedence over UI configuration when both are defined

LDAP Providers​

Traefik Hub LDAP authentication works with common LDAP directory servers:

OpenLDAP​

Open-source LDAP implementation.

Typical configuration:

  • Object class: inetOrgPerson
  • User identifier: uid
  • Base DN: dc=example,dc=org
  • Group membership: memberOf overlay

Active Directory​

Microsoft's directory service.

Typical configuration:

  • User identifier: sAMAccountName or userPrincipalName
  • Base DN: dc=corp,dc=example,dc=com
  • Group membership: Native memberOf attribute

Oracle Internet Directory​

Oracle's enterprise LDAP solution.

Typical configuration:

  • Standard LDAP attributes
  • Compatible with inetOrgPerson schema
  • Supports memberOf attribute

LDAP Security​

Connection Security​

LDAP connections support multiple security options:

MethodPortDescription
LDAPS636LDAP over TLS/SSL
StartTLS389Upgrade connection to TLS
Plain LDAP389Unencrypted (not recommended for production)

TLS Configuration​

When using encrypted connections:

  • Use system CA certificates for verification
  • Provide custom CA certificates via Kubernetes Secrets
  • Configure TLS verification options

Credential Management​

LDAP bind credentials are securely managed:

  • Bind passwords stored in Kubernetes Secrets
  • Referenced by secret name in APIPortalAuth/APIAuth
  • Scoped to appropriate namespaces

LDAP Groups and Attributes​

Group Membership​

Groups are retrieved using the memberOf attribute:

  • Static group retrieval from user's memberOf attribute
  • No nested group lookups or dynamic queries
  • Group names used for portal access control

Attribute Synchronization​

In online mode, user attributes can be synchronized:

  • User email address
  • First name and last name
  • User ID
  • Group memberships
note

Attribute synchronization is only available in online mode. In offline mode, LDAP is used solely for authentication.

Integration with API Management​

ManagedApplications​

For API authentication, LDAP integrates with ManagedApplications:

  • LDAP username must match the appId in a ManagedApplication resource
  • Applications authenticate using LDAP credentials via Basic Auth
  • Access control managed through ManagedSubscriptions

Example:

apiVersion: hub.traefik.io/v1alpha1
kind: ManagedApplication
metadata:
  name: john-doe-app
  namespace: apps
spec:
  appId: app.john.doe  # Machine user - authenticates API requests
  owner: john.doe      # Human user - manages app in portal
  notes: "Application for John Doe"

API Plans​

LDAP-authenticated applications can be rate-limited using APIPlans:

  • Rate limits applied per LDAP-authenticated application
  • Same rate limiting capabilities as other authentication methods
  • Bucket configuration based on application ID

Testing LDAP Integration​

For testing and development purposes, you can use the FreeIPA Demo Server - a publicly accessible LDAP server provided by the FreeIPA project.

FreeIPA Demo Server Configuration​

Use these settings in the Traefik Hub Dashboard or in your CRD configuration:

SettingValue
URLldap://ipa.demo1.freeipa.org:389
Base DNcn=accounts,dc=demo1,dc=freeipa,dc=org
Search Filter(&(objectClass=inetOrgPerson)(uid=%s))
Bind DNuid=admin,cn=users,cn=accounts,dc=demo1,dc=freeipa,dc=org
Bind PasswordSecret123
Group Membership AttributememberOf

Available Test Users​

All test users have the password: Secret123

UsernameRoleDescription
managerManagerRegular user with manager privileges, member of managers and employees groups
employeeEmployeeRegular user with no special privileges, member of employees group
helpdeskHelpdeskRegular user with helpdesk role, can modify users and group memberships
Admin User Not Supported

The admin user is not an inetOrgPerson object class and will not work with the search filter. Use manager, employee, or helpdesk for testing.

Available Test Groups​

Group NameMembersUse Case
employeesemployee, managerTesting group-based API access for all employees
managersmanagerTesting restricted access for management users

Example Configuration​

apiVersion: hub.traefik.io/v1alpha1
kind: APIPortalAuth
metadata:
  name: freeipa-demo-portal-auth
  namespace: apps
spec:
  ldap:
    url: ldap://ipa.demo1.freeipa.org:389
    baseDN: cn=accounts,dc=demo1,dc=freeipa,dc=org
    bindDN: uid=admin,cn=users,cn=accounts,dc=demo1,dc=freeipa,dc=org
    bindPassword: "urn:k8s:secret:freeipa-bind-secret:password"
    searchFilter: (&(objectClass=inetOrgPerson)(uid=%s))
    groups:
      memberOfAttribute: memberOf
    syncedAttributes:
      - userId
      - firstname
      - lastname
      - email
      - groups
Demo Server Limitations

The FreeIPA demo server is a shared public resource:

  • Do not use for production - only for testing and development
  • No privacy - anyone can access the same test users
  • No persistence - the server is reset periodically
  • Availability not guaranteed - the demo server may be unavailable
  • Performance - may be slow due to shared usage

For production testing, set up your own LDAP server or use your organization's existing LDAP infrastructure.

Additional Resources​

Related Content​