Supported production setup with Keycloak and LDAP

[micbar]

Enhanced Authentication System with Improved LDAP and Keycloak Integration

Summary

This PR improves the authentication system with better LDAP and Keycloak configurations for both autoprovisioning and shared user directory modes. It enhances the default deployment examples with clearer documentation and more standardized configuration.

Key Changes

LDAP Improvements

• Simplify LDAP schema by using standard LDAP attributes rather than custom objectClasses
• Configure LDAP as read-only from OpenCloud's perspective by default
• Switch to using entryUUID as the standard user/group identifier
• Add comprehensive documentation in .env file explaining the LDAP configuration
• (optional) use writable sub tree for custom groups

Keycloak Enhancements

• Add support for two distinct authentication modes:
  1. Autoprovisioning: Users are managed by Keycloak and auto-created in OpenCloud on first login
  2. Shared User Directory: Users exist in LDAP which is shared between Keycloak and OpenCloud
• Update Keycloak configuration to pass the LDAP admin password from environment variables
• Mark email addresses as verified by default in the autoprovisioning realm
• Configure docker-entrypoint-override.sh to properly substitute environment variables

Configuration Clarity

• Add detailed documentation for Keycloak configuration options
• Improve organization of environment variables in the .env file
• Create separate realm configurations for each authentication mode

Authentication Modes

1. Shared User Directory Mode

┌─────────────────┐      ┌─────────────────┐      ┌─────────────────┐
│                 │      │                 │      │                 │
│     Client      │─────▶│    Keycloak     │─────▶│    OpenCloud    │
│    (Browser)    │      │  Identity Prov  │      │                 │
│                 │      │                 │      │                 │
└─────────────────┘      └────────┬────────┘      └────────┬────────┘
                                  │                        │
                                  │                        │
                                  ▼                        ▼
                         ┌─────────────────┐      ┌─────────────────┐
                         │                 │      │                 │
                         │     LDAP        │◀─────│   OpenCloud     │
                         │  User Directory │      │   Services      │
                         │                 │      │                 │
                         └─────────────────┘      └─────────────────┘

In this mode:

• LDAP serves as a central user directory shared by both Keycloak and OpenCloud
• User accounts exist in LDAP before authentication
• Keycloak authenticates users against LDAP
• OpenCloud directly accesses LDAP for user information
• Keycloak handles SSO and federation with external identity providers

2. Autoprovisioning Mode

┌─────────────────┐      ┌─────────────────┐      ┌─────────────────┐
│                 │      │                 │      │                 │
│     Client      │─────▶│    Keycloak     │─────▶│    OpenCloud    │
│    (Browser)    │      │  Identity Prov  │      │                 │
│                 │      │                 │      │                 │
└─────────────────┘      └─────────────────┘      └────────┬────────┘
                                                           │
                                                           │
                                                           ▼
                                                  ┌─────────────────┐
                                                  │                 │
                                                  │     LDAP        │
                                                  │  User Directory │
                                                  │                 │
                                                  └─────────────────┘

In this mode:

• Keycloak is the primary user authority
• When a user logs in through Keycloak, OpenCloud automatically creates/updates the corresponding user in LDAP
• User information is synchronized from Keycloak to LDAP via OpenCloud
• Ideal for scenarios where users are managed in an external IdP (like Azure AD) connected to Keycloak

Testing Instructions

1. Clone the repository and checkout this branch
2. Navigate to the deployments/examples/opencloud_full directory
3. Test the Shared Directory Mode:
   • Set LDAP=:ldap.yml and KEYCLOAK=:keycloak.yml in .env
   • Run docker-compose up -d
4. Test the Autoprovisioning Mode:
   • Set LDAP=:ldap.yml, KEYCLOAK=:keycloak.yml, and KEYCLOAK_AUTOPROVISIONING=:keycloak-autoprovisioning.yml in .env
   • Run docker-compose up -d
5. Verify that users can login and are properly provisioned in both modes

Related Issues

• Closes #XXX (Replace with actual issue number if applicable)

Motivation and Context

How Has This Been Tested?

• test environment:
• test case 1:
• test case 2:
• ...

Screenshots (if appropriate):

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Technical debt
• Tests only (no source changes)

Checklist:

• Code changes
• Unit tests added
• Acceptance tests added
• Documentation added

[Copilot]

Pull Request Overview

This PR enhances the authentication system by refining LDAP and Keycloak configurations to support both autoprovisioning and shared user directory modes. Key changes include standardizing LDAP schema attributes, updating Keycloak OIDC claim mappings, and introducing a dedicated configuration for Keycloak autoprovisioning mode.

Reviewed Changes

Copilot reviewed 5 out of 10 changed files in this pull request and generated no comments.

File	Description
deployments/examples/opencloud_full/ldap.yml	Updated LDAP filters and schema identifiers with clearer, standardized values.
deployments/examples/opencloud_full/keycloak.yml	Modified OIDC claim mappings and toggled auto-provisioning behavior for shared directory mode.
deployments/examples/opencloud_full/keycloak-autoprovisioning.yml	Added a separate configuration for autoprovisioning with distinct LDAP schema and user mechanism settings.

Files not reviewed (5)

• deployments/examples/opencloud_full/.env: Language not supported
• deployments/examples/opencloud_full/config/keycloak/docker-entrypoint-override.sh: Language not supported
• deployments/examples/opencloud_full/config/ldap/ldif/10_base.ldif: Language not supported
• deployments/examples/opencloud_full/config/ldap/ldif/20_users.ldif: Language not supported
• deployments/examples/opencloud_full/config/ldap/ldif/30_groups.ldif: Language not supported

Comments suppressed due to low confidence (2)

deployments/examples/opencloud_full/keycloak.yml:17

• The change of PROXY_USER_OIDC_CLAIM from 'preferred_username' to 'uuid' may cause authentication issues unless Keycloak is configured to provide a 'uuid' claim. Please verify that the identity provider emits the expected claim.

PROXY_USER_OIDC_CLAIM: "uuid"

deployments/examples/opencloud_full/keycloak-autoprovisioning.yml:18

• OC_LDAP_USER_SCHEMA_ID is set to 'opencloudUUID' in the autoprovisioning config while 'entryUUID' is used in the shared directory mode; confirm that this intentional discrepancy aligns with the desired behavior.

OC_LDAP_USER_SCHEMA_ID: "opencloudUUID"

[rhafer]

• Add dedicated organizational unit for custom groups (ou=custom,ou=groups)

• Configure LDAP as read-only from OpenCloud's perspective by default

Hm, somehow these two are self-contradicting. If we configure the LDAP server to be really read-only for opencloud then we shouldn't be able to write to the ou=custom,ou=groups subtree either.

It's only working because the example is still using the OpenLDAP rootdn (cn=Admin,dc=....) for accessing the LDAP server. In a real world setup we'd be using an LDAP user that has only read privileges on the server. In which case the custom groups feature would not work.

If we're really talking about a supported setup here I think we need to come up with a different solution for custom groups or disable them until we have a solution.

[Svanvith]

LGTM

[micbar]

• Add dedicated organizational unit for custom groups (ou=custom,ou=groups)
• Configure LDAP as read-only from OpenCloud's perspective by default

Hm, somehow these two are self-contradicting. If we configure the LDAP server to be really read-only for opencloud then we shouldn't be able to write to the ou=custom,ou=groups subtree either.

It's only working because the example is still using the OpenLDAP rootdn (cn=Admin,dc=....) for accessing the LDAP server. In a real world setup we'd be using an LDAP user that has only read privileges on the server. In which case the custom groups feature would not work.

If we're really talking about a supported setup here I think we need to come up with a different solution for custom groups or disable them until we have a solution.

I changed the description. Today tested this with a POC, the partner was fine with the optional group subtree.