docs: Implement separate clients architecture for Keycloak integration

Implements proper OAuth 2.0 separation following RFC 8707 best practices
with distinct resource server and OAuth client configurations.

## Architecture Changes

- Create separate "nextcloud" bearer-only client (resource server)
- Configure "nextcloud-mcp-server" OAuth client with audience mapper
- Audience mapper targets "nextcloud" resource server
- Token flow: aud="nextcloud", azp="nextcloud-mcp-server"

## Benefits

- Proper OAuth client vs resource server separation
- Support for future multi-resource tokens: aud=["nextcloud", "other-service"]
- RFC 8707 Resource Indicators compliance
- Clear requester identification via azp claim

## Documentation Updates

- Correct OAuth flow: MCP Client initiates, handles redirect, shares tokens
- Explain MCP Server as protected resource architecture
- Document offline_access with refresh tokens (Tier 1, current)
- Document token exchange with delegation (Tier 2, future when Keycloak adds support)
- Reference Keycloak issue #38279 for delegation status

## Files

- keycloak/realm-export.json: Add separate clients configuration
- app-hooks/post-installation/15-setup-keycloak-provider.sh: Setup user_oidc with "nextcloud" client
- docs/audience-validation-setup.md: Comprehensive documentation with corrected OAuth flow and delegation comparison
- docker-compose.yml: Fix Keycloak healthcheck (bash TCP instead of curl)
- scripts/test_separate_clients.sh: Verification script for architecture

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

scripts/test_separate_clients.sh

@@ -0,0 +1,90 @@
+#!/bin/bash
+set -e
+
+echo "=== Testing Separate Clients Architecture ==="
+echo ""
+
+# Check both clients exist in Keycloak
+echo "1. Verifying Keycloak clients..."
+docker compose exec -T app curl -s http://keycloak:8080/realms/nextcloud-mcp/.well-known/openid-configuration > /dev/null && echo "✓ Keycloak realm available"
+
+# Check user_oidc provider configuration
+echo ""
+echo "2. Checking user_oidc provider..."
+PROVIDER_INFO=$(docker compose exec -T app php occ user_oidc:provider keycloak)
+echo "$PROVIDER_INFO" | grep -q "nextcloud" && echo "✓ user_oidc configured with 'nextcloud' client"
+
+# Get token from nextcloud-mcp-server client
+echo ""
+echo "3. Getting token from 'nextcloud-mcp-server' client..."
+TOKEN=$(curl -s -X POST "http://localhost:8888/realms/nextcloud-mcp/protocol/openid-connect/token" \
+  -d "grant_type=password" \
+  -d "client_id=nextcloud-mcp-server" \
+  -d "client_secret=mcp-secret-change-in-production" \
+  -d "username=admin" \
+  -d "password=admin" \
+  -d "scope=openid profile email offline_access" | jq -r '.access_token')
+
+if [ "$TOKEN" = "null" ] || [ -z "$TOKEN" ]; then
+    echo "✗ Failed to get token"
+    exit 1
+fi
+
+echo "✓ Got token from nextcloud-mcp-server client"
+
+# Check token claims
+echo ""
+echo "4. Inspecting token claims..."
+CLAIMS=$(echo "$TOKEN" | cut -d'.' -f2 | base64 -d 2>/dev/null | jq '{aud, azp, iss, preferred_username}')
+echo "$CLAIMS"
+
+AUD=$(echo "$CLAIMS" | jq -r '.aud')
+AZP=$(echo "$CLAIMS" | jq -r '.azp')
+
+echo ""
+echo "Architecture validation:"
+if [ "$AUD" = "nextcloud" ]; then
+    echo "  ✓ aud='nextcloud' - Token intended for Nextcloud resource server"
+else
+    echo "  ✗ FAILED: aud='$AUD', expected 'nextcloud'"
+    exit 1
+fi
+
+if [ "$AZP" = "nextcloud-mcp-server" ]; then
+    echo "  ✓ azp='nextcloud-mcp-server' - Token requested by MCP Server client"
+else
+    echo "  ✗ FAILED: azp='$AZP', expected 'nextcloud-mcp-server'"
+    exit 1
+fi
+
+# Test with Nextcloud API
+echo ""
+echo "5. Testing token with Nextcloud API..."
+HTTP_CODE=$(curl -s -w "%{http_code}" -o /tmp/nc_response.json \
+    -H "Authorization: Bearer $TOKEN" \
+    "http://localhost:8080/ocs/v2.php/cloud/capabilities?format=json")
+
+echo "HTTP Status: $HTTP_CODE"
+
+if [ "$HTTP_CODE" = "200" ]; then
+    echo "✓ Token validated successfully!"
+    echo ""
+    echo "===================================================================="
+    echo "SUCCESS: Separate Clients Architecture Working!"
+    echo "===================================================================="
+    echo ""
+    echo "Summary:"
+    echo "  - MCP Server client: 'nextcloud-mcp-server' (requests tokens)"
+    echo "  - Resource server: 'nextcloud' (validates tokens via user_oidc)"
+    echo "  - Token audience: 'nextcloud' (proper resource targeting)"
+    echo "  - Token azp: 'nextcloud-mcp-server' (identifies requester)"
+    echo ""
+    echo "This architecture supports:"
+    echo "  - Future multi-resource tokens: aud=['nextcloud', 'other-service']"
+    echo "  - Clear separation of OAuth client vs resource server"
+    echo "  - RFC 8707 Resource Indicators compliance"
+else
+    echo "✗ Token validation failed"
+    cat /tmp/nc_response.json
+    exit 1
+fi