add docs for ldap integration

docs/server/ldap-authentication.md

@@ -0,0 +1,213 @@
+# LDAP Authentication
+
+This document describes how to configure and use LDAP authentication in Cloudgene.
+
+## Configuration
+
+LDAP authentication is configured in the `config/application.yml` file in your Cloudgene installation directory. Here's a complete configuration example:
+
+```yaml
+ldap:
+  enabled: true
+  url: "ldap://localhost:389"
+  baseDn: "dc=example,dc=com"
+  userDn: "cn=admin,dc=example,dc=com"
+  password: "admin"
+  userSearchBase: "ou=people,dc=example,dc=com"
+  userSearchFilter: "(uid=%s)"
+  attributesToSync:
+    - "mail"
+    - "cn"
+  mailAttribute: "mail"
+  fullNameAttribute: "cn"
+  defaultRoles:
+    - "guest"
+```
+
+### Configuration Parameters
+
+- `enabled`: Enable/disable LDAP authentication
+- `url`: LDAP server URL
+- `baseDn`: Base Distinguished Name for LDAP queries
+- `userDn`: DN of the admin user used for binding to LDAP
+- `password`: Password for the admin user
+- `userSearchBase`: Base DN for user searches
+- `userSearchFilter`: LDAP filter to search for users (the `%s` placeholder is replaced with the username)
+- `attributesToSync`: List of LDAP attributes to synchronize with the local database
+- `mailAttribute`: LDAP attribute containing the user's email address
+- `fullNameAttribute`: LDAP attribute containing the user's full name
+- `defaultRoles`: Default roles assigned to new LDAP users
+
+## User Management
+
+### Authentication Types
+
+Cloudgene supports two types of authentication:
+
+`auth` is the column in the user table.
+
+1. Local Authentication (`auth='local'`):
+   - Users created directly in the database
+   - Passwords managed through Cloudgene's interface
+   - Includes default admin user and test users
+
+2. LDAP Authentication (`auth='ldap'`):
+   - Users authenticated via LDAP server
+   - Passwords managed through LDAP only
+   - Cannot change passwords through Cloudgene
+
+### Authentication Process
+
+1. When a user attempts to log in, the system first tries LDAP authentication:
+   - Verifies LDAP authentication is enabled
+   - Connects to the LDAP server using admin credentials 
+   - Searches for the user using the configured search filter
+   - Attempts to bind with the user's credentials
+   - If LDAP authentication fails, falls back to local database authentication
+
+2. If LDAP authentication succeeds:
+   - For new users:
+     - Creates a new user record in the local database
+     - Sets `auth='ldap'` to mark as LDAP-authenticated
+     - Assigns default roles from configuration
+     - Generates a random password for local database record
+   - For existing users:
+     - Updates user information from LDAP
+     - Updates last login timestamp
+   - In both cases:
+     - Syncs email and full name from LDAP attributes
+     - Sets the user as active
+
+3. If LDAP authentication fails:
+   - System attempts authentication against local database
+   - Validates username and password hash stored in database
+   - If successful, logs user in with local account
+   - If unsuccessful, returns authentication error
+
+### Password Management
+
+1. Local Users (auth column in user table set to 'local'):
+   - Can change passwords through Cloudgene's interface
+   - Can use password reset functionality
+   - Can recover forgotten passwords
+
+2. LDAP Users (auth column in user table set to 'ldap'):
+   - Cannot change passwords through Cloudgene
+   - Must manage passwords through LDAP server
+   - Password-related features are hidden in the UI
+   - Receive clear messages to contact system administrator for password changes
+
+### User Interface
+
+The frontend automatically adapts based on the authentication type:
+
+1. Local Users see:
+   - Password change section in profile
+   - Password reset functionality
+   - Password recovery options
+
+2. LDAP Users see:
+   - Informative message about LDAP password management
+   - No password change options
+   - Instructions to contact system administrator
+
+### LDAP Structure Requirements
+
+The LDAP directory should have the following structure:
+
+```ldif
+# Base DN (e.g., dc=example,dc=com)
+   |
+   +-- cn=admin,...  (Admin user for binding)
+   |
+   +-- ou=people,... (User container)
+       |
+       +-- uid=username,... (User entries)
+           |-- objectClass: inetOrgPerson
+           |-- cn: Full Name
+           |-- mail: [email protected]
+           |-- uid: username
+```
+
+### Security Considerations
+
+1. Admin Binding:
+   - Uses secure binding with admin credentials
+   - Admin credentials should have read access to user entries
+
+2. User Authentication:
+   - Performs two-step verification:
+     1. Searches for user with admin binding
+     2. Verifies user credentials with direct binding
+
+3. Password Management:
+   - LDAP user passwords are managed exclusively in LDAP
+   - Local database uses randomly generated passwords for LDAP users
+   - Password changes for LDAP users must be made in LDAP
+   - Clear separation between local and LDAP user password management
+
+### Test Environment
+
+The test environment is configured to handle both authentication types:
+
+1. Default Users:
+   - Admin user created with `auth='local'`
+   - Test users created with `auth='local'`
+   - Configured in Fixtures.java and TestApplication.java
+
+2. LDAP Testing:
+   - Test cases handle both authentication types
+   - Verifies proper behavior for password management
+   - Ensures correct UI adaptation
+
+### Troubleshooting
+
+Common issues and solutions:
+
+1. Connection Issues:
+   - Verify LDAP server URL and port
+   - Check network connectivity
+   - Ensure admin credentials are correct
+
+2. User Search Issues:
+   - Verify userSearchBase is correct
+   - Check userSearchFilter matches LDAP structure
+   - Confirm user exists in specified location
+
+3. Attribute Sync Issues:
+   - Verify attribute names match LDAP schema
+   - Ensure admin user has read access to attributes
+   - Check LDAP server logs for access issues
+
+4. Password Management Issues:
+   - Verify user's authentication type (`auth` column)
+   - Check if user is trying to change password through correct channel
+   - Ensure proper error messages are displayed
+
+## Logging
+
+LDAP authentication provides detailed debug logging. Enable debug logging for the `cloudgene.mapred.server.auth.LdapAuthenticationProvider` class to see:
+
+- LDAP connection attempts
+- User search operations
+- Binding results
+- Attribute synchronization details
+- Authentication type changes
+- Password management attempts
+
+### Enabling Debug Logging
+
+To enable debug logging for LDAP authentication:
+
+Add or modify the logging configuration in `config/logback.xml`:
+
+```xml
+<configuration>
+    <!-- Existing loggers -->
+    
+    <!-- Add LDAP authentication logger -->
+    <logger name="cloudgene.mapred.server.auth.LdapAuthenticationProvider" level="DEBUG" />
+</configuration>
+```
+
+The logs will appear in your configured logging output (usually `logs/cloudgene.log`).