authentikate/docs/integrations/nextcloud.md

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

# 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

# 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

# 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

# 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:

# 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

# 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:

/* 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:

#!/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:

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:

# 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:

# 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:

# 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:

sudo -u www-data php occ app:list | grep user_oidc

Users Not Auto-Created

Verify auto-provisioning is enabled:

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:

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:

# 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:

# 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:

# 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:

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

HTTPS Configuration

Force HTTPS in Nextcloud:

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:

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.