stack.basicstack.de/apps/opencloud/OPENLDAP_DEPLOYMENT.md

# OpenCloud with External OpenLDAP Deployment Guide

## Architecture Overview

This deployment uses:
- **External OpenLDAP** for user/group storage
- **Pocket ID** (auth.basicstack.de) for authentication via OIDC
- **OpenCloud** as the file storage platform

### Authentication Flow

1. User accesses `https://opencloud.basicstack.de`
2. OpenCloud redirects to Pocket ID for authentication
3. User logs in at `https://auth.basicstack.de`
4. Pocket ID returns OIDC token to OpenCloud
5. OpenCloud auto-provisions user in external OpenLDAP
6. User is granted access based on OIDC group claims

## Deployment Steps

### 1. Create OpenLDAP Admin Secret

First, generate strong passwords and create the sealed secret:

```bash
# Generate passwords
ADMIN_PASSWORD=$(openssl rand -base64 32)
CONFIG_PASSWORD=$(openssl rand -base64 32)

# Save them securely (e.g., password manager)
echo "Admin Password: $ADMIN_PASSWORD"
echo "Config Password: $CONFIG_PASSWORD"

# Create sealed secret
kubectl create secret generic openldap-admin-secret \
  --namespace opencloud \
  --from-literal=admin-password="$ADMIN_PASSWORD" \
  --from-literal=config-password="$CONFIG_PASSWORD" \
  --dry-run=client -o yaml | \
  kubeseal --format yaml > openldap-admin-sealed.yaml

# Apply sealed secret
kubectl apply -f openldap-admin-sealed.yaml
```

### 2. Deploy OpenLDAP

```bash
# Deploy OpenLDAP
kubectl apply -f openldap-deployment.yaml

# Wait for OpenLDAP to be ready
kubectl wait --for=condition=ready pod -l app=openldap -n opencloud --timeout=120s

# Check OpenLDAP pod status
kubectl get pods -n opencloud -l app=openldap
kubectl logs -n opencloud -l app=openldap -f
```

### 3. Initialize LDAP Directory Structure

Once OpenLDAP is running, initialize the directory with required OUs:

```bash
# Get the OpenLDAP pod name
LDAP_POD=$(kubectl get pods -n opencloud -l app=openldap -o jsonpath='{.items[0].metadata.name}')

# Copy the LDIF file to the pod
kubectl cp ldap-init-structure.ldif opencloud/$LDAP_POD:/tmp/init-structure.ldif

# Apply the LDIF (replace <admin-password> with your actual password)
kubectl exec -n opencloud $LDAP_POD -- \
  ldapadd -x -D "cn=admin,dc=basicstack,dc=de" -w "<admin-password>" -f /tmp/init-structure.ldif

# Verify structure was created
kubectl exec -n opencloud $LDAP_POD -- \
  ldapsearch -x -D "cn=admin,dc=basicstack,dc=de" -w "<admin-password>" -b "dc=basicstack,dc=de" -LLL
```

### 4. Deploy OpenCloud

**Important:** Make sure the old OpenCloud PVC is deleted first to ensure fresh initialization with new LDAP configuration.

```bash
# Scale down existing OpenCloud deployment (if running)
kubectl scale deployment -n opencloud opencloud --replicas=0

# Delete old PVC
kubectl delete pvc -n opencloud opencloud-data

# Apply updated deployment
kubectl apply -f opencloud-deployment.yaml
kubectl apply -f opencloud-configmap.yaml

# Scale up
kubectl scale deployment -n opencloud opencloud --replicas=1

# Watch initialization
kubectl logs -n opencloud -l app=opencloud -f
```

### 5. Verify Configuration

```bash
# Check all pods are running
kubectl get pods -n opencloud

# Verify OpenCloud can connect to LDAP
kubectl exec -n opencloud deployment/opencloud -- \
  ldapsearch -x -H ldap://openldap.opencloud.svc.cluster.local:389 \
  -D "cn=admin,dc=basicstack,dc=de" -w "<admin-password>" \
  -b "dc=basicstack,dc=de" -LLL

# Check OpenCloud logs for LDAP connection
kubectl logs -n opencloud -l app=opencloud | grep -i ldap
```

### 6. Test OIDC Authentication

1. Open browser to `https://opencloud.basicstack.de`
2. Should redirect to `https://auth.basicstack.de`
3. Login with Pocket ID credentials
4. Should redirect back to OpenCloud
5. User auto-provisioned in OpenLDAP

## LDAP Directory Structure

```
dc=basicstack,dc=de
├── cn=admin (admin user)
├── ou=users
│   └── (auto-provisioned users from OIDC)
└── ou=groups
    ├── cn=opencloudUsers (default users group)
    └── cn=opencloudAdmins (administrators group)
```

## Configuration Details

### OpenLDAP Connection Details

- **Service:** `openldap.opencloud.svc.cluster.local`
- **Port:** 389 (LDAP), 636 (LDAPS - disabled for internal use)
- **Base DN:** `dc=basicstack,dc=de`
- **Admin DN:** `cn=admin,dc=basicstack,dc=de`
- **User Base:** `ou=users,dc=basicstack,dc=de`
- **Group Base:** `ou=groups,dc=basicstack,dc=de`

### OpenCloud Services Excluded

- **search** - Broken in v7.2.0
- **idp** - Using external Pocket ID for authentication
- **idm** - Using external OpenLDAP for user storage

### OIDC Configuration

- **Issuer:** `https://auth.basicstack.de`
- **Client ID:** (from `opencloud-oidc-secret`)
- **Scopes:** `openid profile email groups offline_access`
- **Auto-provisioning:** Enabled
- **User claim:** `email`
- **Role claim:** `groups`

### Role Mapping

OIDC groups → OpenCloud roles:
- `opencloudAdmin` → admin
- `opencloudSpaceAdmin` → spaceadmin
- `opencloudUser` → user
- `opencloudGuest` → guest

## Troubleshooting

### OpenLDAP not starting

```bash
# Check logs
kubectl logs -n opencloud -l app=openldap

# Check PVCs
kubectl get pvc -n opencloud

# Check events
kubectl get events -n opencloud --sort-by='.lastTimestamp' | tail -20
```

### OpenCloud can't connect to LDAP

```bash
# Test LDAP connectivity from OpenCloud pod
kubectl exec -n opencloud deployment/opencloud -- \
  nc -zv openldap.opencloud.svc.cluster.local 389

# Check LDAP service
kubectl get svc -n opencloud openldap

# Check LDAP endpoints
kubectl get endpoints -n opencloud openldap
```

### Users not auto-provisioning

```bash
# Check OpenCloud proxy logs
kubectl logs -n opencloud -l app=opencloud | grep -i provision

# Check OIDC flow
kubectl logs -n opencloud -l app=opencloud | grep -i oidc

# Verify LDAP directory structure
kubectl exec -n opencloud deployment/openldap -- \
  ldapsearch -x -D "cn=admin,dc=basicstack,dc=de" -w "<password>" \
  -b "ou=users,dc=basicstack,dc=de" -LLL
```

### View auto-provisioned users

```bash
# List all users in LDAP
kubectl exec -n opencloud deployment/openldap -- \
  ldapsearch -x -D "cn=admin,dc=basicstack,dc=de" -w "<password>" \
  -b "ou=users,dc=basicstack,dc=de" -LLL "(objectClass=inetOrgPerson)"
```

## Backup and Maintenance

### Backup LDAP Data

```bash
# Backup entire LDAP directory
kubectl exec -n opencloud deployment/openldap -- \
  slapcat -l /tmp/backup.ldif

kubectl cp opencloud/$LDAP_POD:/tmp/backup.ldif ./ldap-backup-$(date +%Y%m%d).ldif
```

### Monitor LDAP Performance

```bash
# Check LDAP stats
kubectl exec -n opencloud deployment/openldap -- \
  ldapsearch -x -H ldapi:/// -Y EXTERNAL -b "cn=Monitor" -LLL
```

## Files

- `openldap-deployment.yaml` - OpenLDAP Kubernetes deployment
- `openldap-admin-sealed.yaml` - Admin credentials (sealed secret)
- `ldap-init-structure.ldif` - Initial directory structure
- `opencloud-deployment.yaml` - OpenCloud deployment (updated for external LDAP)
- `opencloud-configmap.yaml` - OpenCloud configuration (updated for external LDAP)

## References

- OpenLDAP: https://www.openldap.org/
- OpenCloud LDAP Configuration: https://docs.opencloud.eu/
- Pocket ID: https://github.com/stonith404/pocket-id