generated from thegrind/laravel-dockerized
370 lines
11 KiB
Markdown
370 lines
11 KiB
Markdown
# 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. |