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

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

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

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

- 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

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

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

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