Überblick Overview

Die Integration von Keycloak mit Active Directory durch User Federation ermöglicht es Unternehmen, ihre bestehende AD-Infrastruktur zu nutzen und gleichzeitig moderne Identity Management-Funktionen bereitzustellen. In diesem Artikel erkläre ich die praktische Implementierung einer solchen Lösung.

Integrating Keycloak with Active Directory through User Federation enables organizations to leverage their existing AD infrastructure while providing modern Identity Management capabilities. This article explains the practical implementation of such a solution.

Architektur-Übersicht Architecture Overview

Architektur der Keycloak-Active Directory Integration Keycloak-Active Directory Integration Architecture

Die Architektur zeigt den Datenfluss zwischen den verschiedenen Komponenten:

The architecture shows the data flow between the various components:

• AnwendungenApplications authentifizieren sich über OIDC/SAML bei Keycloak authenticate via OIDC/SAML with Keycloak
• Keycloak fungiert als Identity Provider und vermittelt zwischen Apps und AD acts as Identity Provider and mediates between Apps and AD
• Active Directory bleibt die zentrale Benutzerverwaltung remains the central user management system
• LDAP-ProtokollLDAP Protocol ermöglicht die Kommunikation zwischen Keycloak und AD enables communication between Keycloak and AD

Konfiguration der User Federation User Federation Configuration

1. LDAP Provider erstellen 1. Create LDAP Provider

Navigieren Sie in der Keycloak Admin Console zu "User Federation" und erstellen Sie einen neuen LDAP Provider:

Navigate in the Keycloak Admin Console to "User Federation" and create a new LDAP Provider:

Console Path: Realm → User Federation → Add Provider → LDAP

Connection URL: ldaps://dc1.example.com:636
Bind DN: CN=keycloak-svc,OU=Service Accounts,DC=example,DC=com
Bind Credential: [Service Account Password]

2. Basis-Konfiguration 2. Basic Configuration

# LDAP Settings
Users DN: OU=Users,DC=example,DC=com
Username LDAP attribute: sAMAccountName
RDN LDAP attribute: cn
UUID LDAP attribute: objectGUID
User Object Classes: person, organizationalPerson, user

# Connection Settings
Connection Timeout: 5000
Read Timeout: 10000
Connection Pooling: true
Pagination: true

3. Mapper-Konfiguration 3. Mapper Configuration

Erstellen Sie Attribut-Mapper für die gewünschten AD-Felder:

Create attribute mappers for the desired AD fields:

# Standard Mapper
- username → sAMAccountName
- email → mail  
- firstName → givenName
- lastName → sn

# Gruppen Mapper
Name: group-ldap-mapper
Mapper Type: group-ldap-mapper
LDAP Groups DN: OU=Groups,DC=example,DC=com
Group Object Classes: group
Group Name LDAP Attribute: cn

Erweiterte Funktionen Advanced Features

Rollenbasierte Zugriffskontrolle Role-based Access Control

Option 1: Automatische Rollenzuweisung basierend auf AD-Gruppen Option 1: Automatic Role Assignment Based on AD Groups

Voraussetzungen für Option 1: Stellen Sie sicher, dass die Benutzerrollen auf dem LDAP-Server wie folgt repräsentiert sind:

Prerequisites for Option 1: Ensure that user roles are represented on the LDAP server as follows:

• Eine Organisationseinheit (OU), z.B. "Roles" oder "Groups"
• An organizational unit (OU), e.g., "Roles" or "Groups"
• Gruppen unter dieser Einheit, die die individuellen Benutzerrollen repräsentieren
• Groups under this unit representing individual user roles
• Das cn-Attribut der Gruppen entspricht den Namen der Keycloak-Rollen
• The cn attribute of groups matches Keycloak role names
• Benutzer werden über das member-Attribut zu diesen Gruppen hinzugefügt
• Users are added to groups via the member attribute

# Option 1: Automatische Rollenzuweisung
TBD

Option 2: Standard-Rolle für alle LDAP-Benutzer Option 2: Default Role for All LDAP Users

Falls die AD-Gruppen nicht den Keycloak-Rollennamen entsprechen, verwenden Sie einen Standard-Mapper, der allen LDAP-Benutzern eine Platzhalterrolle zuweist:

If AD groups don't match Keycloak role names, use a default mapper that assigns a placeholder role to all LDAP users:

# Option 2: Standard-Rollenzuweisung
TBD

Password Sync

Troubleshooting

Häufige Probleme Common Issues

• LDAP Connection Failed: Überprüfen Sie Firewall-Regeln und Zertifikate Check firewall rules and certificates
• User Import Issues: Validieren Sie die Users DN und Object Classes Validate Users DN and Object Classes
• Group Mapping Fehler: Stellen Sie sicher, dass der Service Account Lesezugriff auf Gruppen hat Ensure the Service Account has read access to groups
• Performance Probleme: Aktivieren Sie Connection Pooling und Pagination Enable Connection Pooling and Pagination

Best Practices

• Service Account:Service Account: Verwenden Sie einen dedizierten Service Account mit minimalen Berechtigungen Use a dedicated Service Account with minimal permissions
• SSL/TLS: Nutzen Sie immer verschlüsselte LDAPS-Verbindungen Always use encrypted LDAPS connections
• Caching: Konfigurieren Sie angemessene Cache-Einstellungen für bessere Performance Configure appropriate cache settings for better performance
• Monitoring: Implementieren Sie Überwachung für LDAP-Verbindungen und Sync-Prozesse Implement monitoring for LDAP connections and sync processes
• Testing: Testen Sie die Integration mit verschiedenen AD-Gruppenmitgliedschaften Test the integration with various AD group memberships

Fazit Conclusion

Die Integration von Keycloak mit Active Directory über User Federation bietet eine elegante Lösung für hybride Identity Management-Szenarien. Durch die zentrale Verwaltung in AD bleiben bestehende Prozesse erhalten, während moderne SSO-Funktionen für neue Anwendungen verfügbar werden.

Integrating Keycloak with Active Directory via User Federation provides an elegant solution for hybrid Identity Management scenarios. Central management in AD preserves existing processes while making modern SSO features available for new applications.

Diese Architektur bildet eine solide Grundlage für die schrittweise Migration zu cloud-nativen Identity-Lösungen, ohne bestehende Workflows zu unterbrechen.

This architecture forms a solid foundation for gradual migration to cloud-native identity solutions without disrupting existing workflows.