OAuth & LDAP Integration

OPS Advanced

Integrate with OAuth2/OIDC providers and LDAP/Active Directory.

Overview

EZ-Console supports external authentication through OAuth2/OIDC providers (Google, Azure AD, Okta, etc.) and LDAP/Active Directory. This allows users to sign in with their existing corporate credentials.

OAuth2/OIDC Integration

Configuration

OAuth providers are configured in config.yml:

oauth:
  enabled: true
  providers:
    - name: "google"
      display_name: "Google"
      client_id: "your-client-id"
      client_secret: "your-client-secret"
      icon_url: "https://example.com/google-icon.png"
      auth_url: "https://accounts.google.com/o/oauth2/v2/auth"
      token_url: "https://oauth2.googleapis.com/token"
      user_info_url: "https://www.googleapis.com/oauth2/v2/userinfo"
      redirect_url: "http://localhost:5173/login?provider=google"
      role_field: "role"  # Optional: field in user info for role
      email_field: "email"  # Optional: default "email"
      username_field: "username"  # Optional: default "username"
      full_name_field: "fullName"  # Optional: default "fullName"
      avatar_field: "avatar"  # Optional: default "avatar"
      auto_create_user: true  # Optional: auto create user on first login

Google OAuth Setup

1. Create OAuth Client:

   • Go to Google Cloud Console
   • Create a new project or select existing
   • Enable Google+ API
   • Create OAuth 2.0 credentials
   • Add authorized redirect URI: http://localhost:5173/login?provider=google

2. Configuration:

oauth:
  enabled: true
  providers:
    - name: "google"
      display_name: "Google"
      client_id: "YOUR_GOOGLE_CLIENT_ID"
      client_secret: "YOUR_GOOGLE_CLIENT_SECRET"
      auth_url: "https://accounts.google.com/o/oauth2/v2/auth"
      token_url: "https://oauth2.googleapis.com/token"
      user_info_url: "https://www.googleapis.com/oauth2/v2/userinfo"
      redirect_url: "http://localhost:5173/login?provider=google"

Azure AD Setup

1. Register Application:

   • Go to Azure Portal
   • Azure Active Directory → App registrations
   • New registration
   • Add redirect URI: http://localhost:5173/login?provider=azure_ad

2. Configuration:

oauth:
  enabled: true
  providers:
    - name: "azure_ad"
      display_name: "Azure AD"
      client_id: "YOUR_AZURE_CLIENT_ID"
      client_secret: "YOUR_AZURE_CLIENT_SECRET"
      auth_url: "https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize"
      token_url: "https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token"
      user_info_url: "https://graph.microsoft.com/v1.0/me"
      redirect_url: "http://localhost:5173/login?provider=azure_ad"

Okta Setup

1. Create Application:

   • Go to Okta Admin Console
   • Applications → Create App Integration
   • OIDC - OpenID Connect
   • Add redirect URI: http://localhost:5173/login?provider=okta

2. Configuration:

oauth:
  enabled: true
  providers:
    - name: "okta"
      display_name: "Okta"
      client_id: "YOUR_OKTA_CLIENT_ID"
      client_secret: "YOUR_OKTA_CLIENT_SECRET"
      auth_url: "https://{your-domain}.okta.com/oauth2/v1/authorize"
      token_url: "https://{your-domain}.okta.com/oauth2/v1/token"
      user_info_url: "https://{your-domain}.okta.com/oauth2/v1/userinfo"
      redirect_url: "http://localhost:5173/login?provider=okta"

Custom OAuth Provider

oauth:
  enabled: true
  providers:
    - name: "custom"
      display_name: "Custom Provider"
      client_id: "your-client-id"
      client_secret: "your-client-secret"
      auth_url: "https://provider.com/oauth/authorize"
      token_url: "https://provider.com/oauth/token"
      user_info_url: "https://provider.com/api/user"
      redirect_url: "http://localhost:5173/login?provider=custom"

LDAP/Active Directory Integration

Configuration

LDAP settings are configured through the admin console or API:

Navigate to: System Settings → LDAP Settings

Basic LDAP Configuration

ldap:
  enabled: true
  host: "ldap.example.com"
  port: 389
  use_tls: false
  use_ssl: false
  base_dn: "dc=example,dc=com"
  bind_dn: "cn=admin,dc=example,dc=com"
  bind_password: "password"
  user_search_base: "ou=users,dc=example,dc=com"
  user_search_filter: "(uid=%s)"
  group_search_base: "ou=groups,dc=example,dc=com"
  group_search_filter: "(member=%s)"

Active Directory Configuration

ldap:
  enabled: true
  host: "ad.example.com"
  port: 389
  use_tls: true
  base_dn: "dc=example,dc=com"
  bind_dn: "CN=Service Account,CN=Users,DC=example,DC=com"
  bind_password: "password"
  user_search_base: "CN=Users,DC=example,DC=com"
  user_search_filter: "(&(objectClass=user)(sAMAccountName=%s))"
  group_search_base: "CN=Users,DC=example,DC=com"
  group_search_filter: "(&(objectClass=group)(member=%s))"

Configuration Options

• enabled: Enable LDAP authentication (default: false)
• host: LDAP server hostname (required)
• port: LDAP server port (default: 389 for LDAP, 636 for LDAPS)
• use_tls: Use TLS encryption (default: false)
• use_ssl: Use SSL encryption (default: false)
• base_dn: Base distinguished name (required)
• bind_dn: Bind distinguished name for authentication (required)
• bind_password: Bind password (required)
• user_search_base: Base DN for user search (required)
• user_search_filter: LDAP filter for user search (default: "(uid=%s)")
• group_search_base: Base DN for group search (optional)
• group_search_filter: LDAP filter for group search (optional)

Testing Connections

Test OAuth Connection

1. Navigate to System Settings → OAuth Settings
2. Click Test Connection for a provider
3. Verify redirect works correctly

Test LDAP Connection

1. Navigate to System Settings → LDAP Settings
2. Enter LDAP configuration
3. Click Test Connection
4. Enter test username and password
5. Verify connection and authentication

User Mapping

OAuth User Mapping

OAuth providers return user information that is mapped to EZ-Console users:

• email: User email address
• username: Username (from username_field or email)
• full_name: Full name
• avatar: Avatar URL
• role: Role assignment (if role_field is configured)

LDAP User Mapping

LDAP attributes are mapped to user fields:

• username: From user_search_filter result
• email: From mail attribute
• full_name: From cn or displayName attribute
• groups: From group search results

Auto User Creation

OAuth Auto Creation

When auto_create_user: true:

• Users are automatically created on first OAuth login
• Default role can be assigned
• User information is synced from OAuth provider

LDAP Auto Creation

• Users can be automatically created on first LDAP login
• User information is synced from LDAP
• Groups can be mapped to roles

Troubleshooting

OAuth Issues

Redirect URI Mismatch:

• Verify redirect URI matches exactly in provider settings
• Check for trailing slashes
• Ensure protocol (http/https) matches

Invalid Client Credentials:

• Verify client ID and secret are correct
• Check if credentials are expired
• Verify application is enabled in provider

LDAP Issues

Connection Failed:

• Verify host and port are correct
• Check firewall rules
• Verify TLS/SSL settings match server

Authentication Failed:

• Verify bind DN and password
• Check user search filter
• Verify user exists in LDAP

User Not Found:

• Check user search base and filter
• Verify user DN format
• Check LDAP permissions

Best Practices

1. Use HTTPS in Production

Always use HTTPS for OAuth redirects and LDAP connections in production.

2. Secure Credentials

Store OAuth client secrets and LDAP passwords securely, never in code.

3. Test Before Production

Always test OAuth and LDAP connections in staging before production.

4. Monitor Logs

Monitor authentication logs for failed attempts and connection issues.

Related Topics

• Authentication & Authorization - Auth implementation
• System Settings - System configuration

---

Need help? Ask in GitHub Discussions.