# Nextcloud Integration

This guide shows how to integrate Nextcloud with AuthentiKate using the OpenID Connect app for seamless single sign-on.

## Prerequisites

- AuthentiKate running and accessible
- Nextcloud instance with admin access
- Nextcloud OpenID Connect app installed

## Step 1: Install OpenID Connect App

### Via Nextcloud App Store

1. Log into Nextcloud as an administrator
2. Go to **Apps** → **Authentication**
3. Find and install **"OpenID Connect user backend"**
4. Enable the app

### Via Command Line

```bash
# Install via occ command
sudo -u www-data php occ app:install user_oidc
sudo -u www-data php occ app:enable user_oidc
```

## Step 2: Create Application in AuthentiKate

1. Log into your AuthentiKate admin panel
2. Navigate to **Applications** → **Create Application**
3. Fill in the application details:

```
Name: Nextcloud
Redirect URI: https://cloud.yourdomain.com/apps/user_oidc/code
Icon: https://cdn.jsdelivr.net/gh/selfhst/icons/webp/nextcloud.webp
```

4. Click **Save** and note the generated:
   - **Client ID**
   - **Client Secret**

## Step 3: Configure Nextcloud OIDC

### Via Web Interface

1. Go to **Settings** → **Administration** → **OpenID Connect**
2. Configure the OIDC provider:

```
Provider Name: AuthentiKate
Identifier: authentikate
Client ID: your-client-id
Client Secret: your-client-secret
Discovery endpoint: https://auth.yourdomain.com/.well-known/openid_configuration
```

3. **Advanced Settings** (click to expand):
```
Scope: openid profile email
Unique user identifier: preferred_username
```

4. Click **Save**

### Via Command Line

```bash
# Set OIDC configuration
sudo -u www-data php occ config:app:set user_oidc provider-authentikate-clientId --value="your-client-id"
sudo -u www-data php occ config:app:set user_oidc provider-authentikate-clientSecret --value="your-client-secret"
sudo -u www-data php occ config:app:set user_oidc provider-authentikate-discoveryUrl --value="https://auth.yourdomain.com/.well-known/openid_configuration"
sudo -u www-data php occ config:app:set user_oidc provider-authentikate-scope --value="openid profile email"

# Set unique identifier
sudo -u www-data php occ config:app:set user_oidc provider-authentikate-uniqueUid --value="1"
sudo -u www-data php occ config:app:set user_oidc provider-authentikate-uniqueUidMapping --value="preferred_username"
```

## Step 4: User Attribute Mapping

Configure how AuthentiKate user attributes map to Nextcloud:

### Via Web Interface

In **Settings** → **Administration** → **OpenID Connect** → **Advanced**:

```
Display name mapping: name
Email mapping: email
Unique user identifier: preferred_username
```

### Via Command Line

```bash
# User attribute mapping
sudo -u www-data php occ config:app:set user_oidc provider-authentikate-displayNameMapping --value="name"
sudo -u www-data php occ config:app:set user_oidc provider-authentikate-emailMapping --value="email"
sudo -u www-data php occ config:app:set user_oidc provider-authentikate-quotaMapping --value=""
```

## Step 5: Auto-Provisioning (Optional)

Enable automatic user creation on first login:

### Via Web Interface

In the OIDC settings, enable:
- **Auto provision users**
- **Respect email verified claim**

### Via Command Line

```bash
# Enable auto-provisioning
sudo -u www-data php occ config:app:set user_oidc auto-provision --value="1"
sudo -u www-data php occ config:app:set user_oidc provider-authentikate-provisioningEnabled --value="1"

# Respect email verification
sudo -u www-data php occ config:app:set user_oidc provider-authentikate-checkEmailVerification --value="1"
```

## Step 6: Group Mapping (Optional)

If you plan to add groups to AuthentiKate in the future:

```bash
# Enable group provisioning
sudo -u www-data php occ config:app:set user_oidc provider-authentikate-groupProvisioning --value="1"
sudo -u www-data php occ config:app:set user_oidc provider-authentikate-groupMapping --value="groups"
```

## Step 7: Login Button Customization

Customize the OAuth login button:

### Via Config

```bash
# Set custom button text
sudo -u www-data php occ config:app:set user_oidc provider-authentikate-buttonText --value="Login with AuthentiKate"

# Hide default login form (optional)
sudo -u www-data php occ config:system:set hide_login_form --value=true
```

### Custom CSS (Optional)

Add custom styling in **Settings** → **Administration** → **Theming**:

```css
/* Style the OIDC login button */
.oidc-login-button {
    background-color: #3b82f6 !important;
    border-color: #3b82f6 !important;
}

.oidc-login-button:hover {
    background-color: #2563eb !important;
    border-color: #2563eb !important;
}
```

## Complete Configuration Example

Here's a complete command-line setup:

```bash
#!/bin/bash

# Install and enable OIDC app
sudo -u www-data php occ app:install user_oidc
sudo -u www-data php occ app:enable user_oidc

# Configure OIDC provider
sudo -u www-data php occ config:app:set user_oidc provider-authentikate-clientId --value="your-client-id"
sudo -u www-data php occ config:app:set user_oidc provider-authentikate-clientSecret --value="your-client-secret"
sudo -u www-data php occ config:app:set user_oidc provider-authentikate-discoveryUrl --value="https://auth.yourdomain.com/.well-known/openid_configuration"
sudo -u www-data php occ config:app:set user_oidc provider-authentikate-scope --value="openid profile email"

# User mapping
sudo -u www-data php occ config:app:set user_oidc provider-authentikate-uniqueUid --value="1"
sudo -u www-data php occ config:app:set user_oidc provider-authentikate-uniqueUidMapping --value="preferred_username"
sudo -u www-data php occ config:app:set user_oidc provider-authentikate-displayNameMapping --value="name"
sudo -u www-data php occ config:app:set user_oidc provider-authentikate-emailMapping --value="email"

# Auto-provisioning
sudo -u www-data php occ config:app:set user_oidc auto-provision --value="1"
sudo -u www-data php occ config:app:set user_oidc provider-authentikate-provisioningEnabled --value="1"
sudo -u www-data php occ config:app:set user_oidc provider-authentikate-checkEmailVerification --value="1"

# Button customization
sudo -u www-data php occ config:app:set user_oidc provider-authentikate-buttonText --value="Login with AuthentiKate"

echo "Nextcloud OIDC integration configured successfully!"
```

## Docker Compose Example

Complete Docker setup with Nextcloud and AuthentiKate:

```yaml
version: '3.8'

services:
  nextcloud:
    image: nextcloud:latest
    container_name: nextcloud
    restart: unless-stopped
    ports:
      - "80:80"
    environment:
      - NEXTCLOUD_ADMIN_USER=admin
      - NEXTCLOUD_ADMIN_PASSWORD=secure_password
      - NEXTCLOUD_TRUSTED_DOMAINS=cloud.yourdomain.com
      - OVERWRITEPROTOCOL=https
      - OVERWRITEHOST=cloud.yourdomain.com
    volumes:
      - nextcloud_data:/var/www/html
      - ./setup-oidc.sh:/docker-entrypoint-hooks.d/pre-installation/setup-oidc.sh:ro
    labels:
      # Traefik labels
      - "traefik.enable=true"
      - "traefik.http.routers.nextcloud.rule=Host(`cloud.yourdomain.com`)"
      - "traefik.http.routers.nextcloud.entrypoints=websecure"
      - "traefik.http.routers.nextcloud.tls.certresolver=letsencrypt"

volumes:
  nextcloud_data:
```

## Testing the Integration

1. **Log out** of Nextcloud (if currently logged in)
2. **Navigate to** your Nextcloud login page
3. **Click "Login with AuthentiKate"** button
4. **Authenticate** with your AuthentiKate credentials
5. **Verify** you're logged into Nextcloud with correct user information

## Advanced Configuration

### Custom User Provisioning

Control how users are created:

```bash
# Set default quota for new users
sudo -u www-data php occ config:app:set user_oidc provider-authentikate-defaultQuota --value="5GB"

# Set default group for new users
sudo -u www-data php occ config:app:set user_oidc provider-authentikate-defaultGroup --value="users"
```

### Backup Users

Prevent deletion of users not found in OIDC:

```bash
# Enable soft delete (backup users)
sudo -u www-data php occ config:app:set user_oidc provider-authentikate-softAutoUpdate --value="1"
```

### Admin Users

Make specific users administrators:

```bash
# Add users to admin group (run after first login)
sudo -u www-data php occ group:adduser admin "admin_username"
```

## Troubleshooting

### Common Issues

#### "Invalid redirect URI" Error
Ensure the redirect URI in AuthentiKate exactly matches:
```
https://cloud.yourdomain.com/apps/user_oidc/code
```

#### OIDC Login Button Missing
Check that the app is enabled:
```bash
sudo -u www-data php occ app:list | grep user_oidc
```

#### Users Not Auto-Created
Verify auto-provisioning is enabled:
```bash
sudo -u www-data php occ config:app:get user_oidc auto-provision
sudo -u www-data php occ config:app:get user_oidc provider-authentikate-provisioningEnabled
```

#### Wrong User Information
Check the attribute mapping:
```bash
sudo -u www-data php occ config:app:get user_oidc provider-authentikate-displayNameMapping
sudo -u www-data php occ config:app:get user_oidc provider-authentikate-emailMapping
```

### Debug Mode

Enable debugging in Nextcloud:

```bash
# Enable debug mode
sudo -u www-data php occ config:system:set debug --value=true

# Check logs
sudo -u www-data php occ log:tail
```

### Configuration Check

Verify your OIDC configuration:

```bash
# List all OIDC settings
sudo -u www-data php occ config:list user_oidc

# Test OIDC discovery endpoint
curl https://auth.yourdomain.com/.well-known/openid_configuration
```

### Reset Configuration

If you need to start over:

```bash
# Remove OIDC configuration
sudo -u www-data php occ config:app:delete user_oidc provider-authentikate-clientId
sudo -u www-data php occ config:app:delete user_oidc provider-authentikate-clientSecret
sudo -u www-data php occ config:app:delete user_oidc provider-authentikate-discoveryUrl

# Disable auto-provisioning
sudo -u www-data php occ config:app:set user_oidc auto-provision --value="0"
```

## Security Considerations

### Trusted Domains

Ensure your domain is in Nextcloud's trusted domains:

```bash
sudo -u www-data php occ config:system:set trusted_domains 0 --value="cloud.yourdomain.com"
```

### HTTPS Configuration

Force HTTPS in Nextcloud:

```bash
sudo -u www-data php occ config:system:set overwriteprotocol --value="https"
sudo -u www-data php occ config:system:set overwrite.cli.url --value="https://cloud.yourdomain.com"
```

### Session Security

Configure secure sessions:

```bash
sudo -u www-data php occ config:system:set session_lifetime --value=3600
sudo -u www-data php occ config:system:set session_keepalive --value=false
```

Your Nextcloud instance is now integrated with AuthentiKate! Users can sign in with their AuthentiKate credentials and access their Nextcloud files and applications.