united-tattoo/docs/NEXTCLOUD-OAUTH-SETUP.md

Nextcloud OAuth Authentication Setup Guide

This guide explains how to set up Nextcloud OAuth authentication for United Tattoo Studio and migrate existing artist accounts.

Table of Contents

1. Nextcloud OAuth App Registration
2. Environment Configuration
3. Nextcloud Group Setup
4. Migrating Existing Artists
5. Testing the Integration
6. Troubleshooting

---

Nextcloud OAuth App Registration

Step 1: Access OAuth Settings in Nextcloud

1. Log in to your Nextcloud instance as an administrator: https://portal.united-tattoos.com
2. Navigate to Settings → Security → OAuth 2.0 clients (bottom of the page)

Step 2: Create New OAuth App

1. Click "Add client"
2. Fill in the following details:
   • Name: United Tattoo Studio (or any descriptive name)
   • Redirection URI: https://united-tattoos.com/api/auth/callback/nextcloud
     • For local development: http://localhost:3000/api/auth/callback/nextcloud
     • For preview/staging: https://your-preview-url.pages.dev/api/auth/callback/nextcloud
3. Click "Add"

Step 3: Save Credentials

After creating the OAuth app, Nextcloud will display:

• Client Identifier (Client ID)
• Secret (Client Secret)

IMPORTANT: Copy these values immediately and store them securely. The secret will not be shown again.

---

Environment Configuration

Step 1: Update Environment Variables

Add the following variables to your .env.local file (or production environment):

# Nextcloud Configuration
NEXTCLOUD_BASE_URL="https://portal.united-tattoos.com"

# Nextcloud OAuth Authentication
NEXTCLOUD_OAUTH_CLIENT_ID="your-client-id-from-step-3"
NEXTCLOUD_OAUTH_CLIENT_SECRET="your-client-secret-from-step-3"

# Group names for auto-provisioning (customize if needed)
NEXTCLOUD_ARTISTS_GROUP="artists"
NEXTCLOUD_ADMINS_GROUP="shop_admins"

# Nextcloud CalDAV Integration (existing, for calendar sync)
NEXTCLOUD_USERNAME="your-service-account-username"
NEXTCLOUD_PASSWORD="your-service-account-app-password"
NEXTCLOUD_CALENDAR_BASE_PATH="/remote.php/dav/calendars"

Step 2: Verify Configuration

Run the following command to check for configuration errors:

npm run build

If there are missing environment variables, the build will fail with a helpful error message from lib/env.ts.

---

Nextcloud Group Setup

Step 1: Create Required Groups

1. In Nextcloud, navigate to Settings → Users
2. Click "Add group" and create the following groups:
   • artists - For tattoo artists who need access to their portfolios
   • shop_admins - For shop administrators

Step 2: Assign Users to Groups

For each existing artist or admin:

1. Go to Settings → Users
2. Find the user in the list
3. Click on their row and select the appropriate group(s):
   • Artists: Add to artists group
   • Shop admins: Add to shop_admins group
   • Super admins: Add to both shop_admins AND admins (or admin) group

Note: Users can be in multiple groups. For example, a shop owner who is also an artist should be in both artists and shop_admins.

---

Migrating Existing Artists

Understanding the Migration

When an artist signs in via Nextcloud OAuth for the first time:

1. The system checks if a user with that email already exists in the database
2. If user exists: The existing user account is linked to the Nextcloud OAuth session
3. If user doesn't exist: A new user and artist profile are auto-created based on Nextcloud group membership

Step 1: Match Email Addresses

Ensure that each artist's email in Nextcloud matches their email in the United Tattoo database:

-- Query to check existing artist emails in D1 database
SELECT u.email, a.name, a.slug
FROM users u
JOIN artists a ON u.id = a.user_id
WHERE u.role = 'ARTIST';

Run this via:

wrangler d1 execute united-tattoo --command="SELECT u.email, a.name, a.slug FROM users u JOIN artists a ON u.id = a.user_id WHERE u.role = 'ARTIST';"

Step 2: Create Nextcloud Accounts (If Needed)

If an artist doesn't have a Nextcloud account yet:

1. Go to Settings → Users in Nextcloud
2. Click "New user"
3. Fill in:
   • Username: Artist's preferred username (e.g., amari.kyss)
   • Display name: Artist's full name (e.g., "Amari Kyss")
   • Email: Must match the email in the database
   • Groups: Add to artists group
4. Set a temporary password and send it to the artist
5. Ask the artist to change their password on first login

Step 3: Notify Artists

Send an email to all artists with the following information:

Email Template:

Subject: New Login Process for United Tattoo Studio Dashboard

Hello [Artist Name],

We've updated the artist dashboard login process to use your Nextcloud account for easier access.

What's Changed:
- You now sign in using your Nextcloud credentials (same account you use for [calendar/files/etc])
- No need to remember a separate password for the artist dashboard
- More secure authentication via OAuth

How to Sign In:
1. Go to https://united-tattoos.com/auth/signin
2. Click "Sign in with Nextcloud"
3. Use your Nextcloud username and password
4. You'll be redirected to your artist dashboard

Your Nextcloud Credentials:
- Username: [their Nextcloud username]
- Email: [their email]
- If you forgot your Nextcloud password, you can reset it at: https://portal.united-tattoos.com/login

Need Help?
Contact [admin contact] if you have any issues signing in.

Thanks,
United Tattoo Studio Team

---

Testing the Integration

Test 1: New Artist Sign In

1. Ensure a test user is in the artists group in Nextcloud
2. Go to /auth/signin on your website
3. Click "Sign in with Nextcloud"
4. Authorize the OAuth app
5. Verify:
   • User is created in the users table
   • Artist profile is created in the artists table
   • Redirect to /artist-dashboard works
   • Artist can view/edit their profile

Test 2: Existing Artist Sign In

1. Use an artist whose email matches an existing database record
2. Follow the same sign-in process
3. Verify:
   • No duplicate user/artist created
   • Existing artist profile is accessible
   • Portfolio images are preserved

Test 3: Admin Sign In

1. Ensure a test user is in the shop_admins group
2. Sign in via Nextcloud OAuth
3. Verify:
   • User is created with SHOP_ADMIN role
   • Redirect to /admin dashboard works
   • Admin can access all admin features

Test 4: Unauthorized User

1. Create a Nextcloud user NOT in any authorized group
2. Attempt to sign in via OAuth
3. Verify:
   • Sign-in is rejected with an error message
   • User is not created in the database
   • Error message suggests joining the 'artists' or 'shop_admins' group

Test 5: Admin Fallback (Emergency Access)

1. Go to /auth/signin?admin=true
2. Verify the credentials form is shown
3. Sign in with nicholai@biohazardvfx.com (or any email in dev mode)
4. Verify admin access works

---

Troubleshooting

Issue: "Unable to sign in with Nextcloud"

Possible causes:

• User not in artists or shop_admins group
• OAuth app not configured correctly in Nextcloud
• Redirect URI mismatch

Solution:

1. Check user's group membership in Nextcloud
2. Verify NEXTCLOUD_OAUTH_CLIENT_ID and NEXTCLOUD_OAUTH_CLIENT_SECRET are correct
3. Ensure redirect URI in Nextcloud matches your domain exactly

Issue: "Nextcloud API error" in server logs

Possible causes:

• Service account credentials (NEXTCLOUD_USERNAME/NEXTCLOUD_PASSWORD) are incorrect
• Nextcloud OCS API is not accessible

Solution:

1. Test service account credentials manually:

   curl -u "username:password" https://portal.united-tattoos.com/ocs/v1.php/cloud/users/testuser
   

2. Ensure the service account has admin privileges in Nextcloud
3. Check Nextcloud logs for any API access errors

Issue: Duplicate artist profiles created

Possible causes:

• Email mismatch between Nextcloud and database
• User signed in before email was matched

Solution:

1. Identify duplicate records:

   SELECT * FROM artists WHERE user_id IN (
     SELECT user_id FROM artists GROUP BY user_id HAVING COUNT(*) > 1
   );
   

2. Manually merge duplicates by updating portfolio images to point to the correct artist

3. Delete the duplicate artist profile

Issue: Artist can't access dashboard after sign-in

Possible causes:

• Artist profile not created during auto-provisioning
• Database transaction failed

Solution:

1. Check if user exists:

   SELECT * FROM users WHERE email = 'artist@example.com';
   

2. Check if artist profile exists:

   SELECT * FROM artists WHERE user_id = 'user-id-from-above';
   

3. If user exists but artist doesn't, manually create artist:

   INSERT INTO artists (id, user_id, name, bio, specialties, is_active, slug)
   VALUES ('uuid', 'user-id', 'Artist Name', '', '[]', 1, 'artist-name');
   

---

Next Steps

After completing this setup:

1. Monitor sign-ins: Check server logs for any authentication errors
2. Gather feedback: Ask artists about their experience with the new login process
3. Update documentation: Keep this guide updated with any changes to the process
4. Consider enhancements:
   • Sync artist profile photos from Nextcloud
   • Enable calendar integration for all artists
   • Add two-factor authentication requirement

---

Support

For technical support or questions about this integration, contact the development team or file an issue in the project repository.

Last updated: 2025-10-22