authelia/docs/OAUTH_SETUP.md

# OAuth/OIDC Client Setup Guide

This guide covers setting up OAuth/OIDC authentication for services like Portainer and Gitea using Authelia as the identity provider.

## 🔧 Overview

Authelia provides OpenID Connect (OIDC) support, allowing services to authenticate users through OAuth flows instead of using Traefik middleware. This provides better integration and user experience.

## 🔑 Client Secrets Management

### Generate Client Secrets
```bash
# Generate secrets for new OAuth clients
./scripts/generate-oauth-secrets.sh
```

This script creates:
- `secrets/oauth-secrets.env` - Environment variables for local testing
- Individual secret files in `secrets/clients/` directory
- All files are automatically gitignored

### Required CI/CD Vault Secrets

Add these to your Woodpecker CI vault:

#### Portainer OAuth
- **Variable**: `CLIENT_SECRET_PORTAINER`
- **Value**: Generated from `secrets/clients/portainer-secret.txt`

#### Gitea OAuth  
- **Variable**: `CLIENT_SECRET_GITEA`
- **Value**: Generated from `secrets/clients/gitea-secret.txt`

## 📱 Client Configurations

### Portainer OAuth Setup

#### 1. Authelia Configuration
Already configured in `docker/authelia/config/configuration.oidc.clients.yml`:

```yaml
- client_id: portainer
  client_name: Portainer
  client_secret: {{ secret "/run/secrets/CLIENT_SECRET_PORTAINER" }}
  public: false
  authorization_policy: one_factor
  consent_mode: implicit
  scopes:
    - openid
    - email
    - profile
    - groups
  redirect_uris:
    - https://portainer.{{ env "TRAEFIK_DOMAIN" }}/
  userinfo_signed_response_alg: none
```

#### 2. Portainer OAuth Settings
Configure in Portainer → Settings → Authentication:

- **OAuth Provider**: Custom
- **Client ID**: `portainer`
- **Client Secret**: `<from CI vault>`
- **Authorization URL**: `https://login.nixc.us/api/oidc/authorization`
- **Token URL**: `https://login.nixc.us/api/oidc/token`
- **User Info URL**: `https://login.nixc.us/api/oidc/userinfo`
- **Scopes**: `openid email profile groups`
- **Redirect URL**: `https://portainer.nixc.us/`

#### 3. Remove Traefik Middleware (Optional)
Once OAuth is working, remove middleware protection:

```yaml
# Remove this line from Portainer service:
# traefik.http.routers.portainer.middlewares: authelia_authelia
```

### Gitea OAuth Setup

#### 1. Authelia Configuration
Already configured in `docker/authelia/config/configuration.oidc.clients.yml`:

```yaml
- client_id: gitea
  client_name: Gitea
  client_secret: {{ secret "/run/secrets/CLIENT_SECRET_GITEA" }}
  public: false
  authorization_policy: one_factor
  consent_mode: implicit
  scopes:
    - openid
    - email
    - profile
    - groups
  redirect_uris:
    - https://git.{{ env "TRAEFIK_DOMAIN" }}/user/oauth2/authelia/callback
  userinfo_signed_response_alg: none
```

#### 2. Gitea OAuth Settings
Configure in Gitea → Site Administration → Authentication Sources:

- **Authentication Type**: OAuth2
- **Authentication Name**: `Authelia`
- **OAuth2 Provider**: OpenID Connect
- **Client ID**: `gitea`
- **Client Secret**: `<from CI vault>`
- **OpenID Connect Auto Discovery URL**: `https://login.nixc.us/.well-known/openid_configuration`
- **Icon URL**: `https://login.nixc.us/static/media/logo.png` (optional)

## 🔄 Deployment Process

### 1. Generate Secrets
```bash
./scripts/generate-oauth-secrets.sh
```

### 2. Update CI/CD Vault
Add the generated secrets to your Woodpecker CI vault:
- `CLIENT_SECRET_PORTAINER`
- `CLIENT_SECRET_GITEA`

### 3. Deploy Authelia
Push changes to trigger CI/CD deployment with new OAuth clients.

### 4. Configure Services
Set up OAuth in each service's admin interface using the URLs and client IDs above.

## 🔍 Testing OAuth Flow

### Test Authentication Flow
1. **Visit protected service** (e.g., `https://portainer.nixc.us`)
2. **Click OAuth login** button
3. **Redirect to Authelia** (`https://login.nixc.us`)
4. **Authenticate** with your credentials
5. **Redirect back** to service with authentication
6. **Access granted** with user information

### Troubleshooting
- **Check redirect URIs** match exactly (including trailing slashes)
- **Verify client secrets** in CI vault match generated values
- **Confirm Authelia** is accessible at `https://login.nixc.us`
- **Check service logs** for OAuth-specific error messages

## 🛡️ Security Considerations

### Client Secrets
- **Never commit** client secrets to git (automatically gitignored)
- **Rotate secrets** periodically using the generation script
- **Use secure transmission** when adding to CI vault

### Redirect URIs
- **Exact matching** required - include/exclude trailing slashes consistently
- **HTTPS only** in production
- **Specific paths** rather than wildcards

### Scopes
- **Minimal necessary** scopes for each client
- **Groups scope** enables role-based access control
- **Profile/email** scopes for user information

## 📋 Available Scopes

- **`openid`**: Required for OIDC, provides user identifier
- **`email`**: User's email address
- **`profile`**: User's display name and profile information  
- **`groups`**: User's group memberships for authorization

## 🔧 Advanced Configuration

### Custom Authorization Policies
Create service-specific policies in `configuration.oidc.clients.yml`:

```yaml
authorization_policies:
  portainer_admin:
    default_policy: deny
    rules:
      - policy: one_factor
        subject: group:portainer-admins
```

### Group-Based Access Control
Map LDAP groups to service permissions:
- **`portainer-admins`**: Full Portainer access
- **`developers`**: Git repository access
- **`users`**: Basic service access

## 📞 Support

### Common Issues
1. **Redirect URI mismatch**: Check exact URL format
2. **Client secret mismatch**: Regenerate and update vault
3. **Scope errors**: Verify service supports requested scopes
4. **Network issues**: Confirm Authelia accessibility

### Logs and Debugging
```bash
# Check Authelia OIDC logs
ssh macmini7 'docker service logs authelia_authelia | grep -i oidc'

# Check service-specific OAuth logs
ssh macmini7 'docker service logs <service_name> | grep -i oauth'
```