Oxicloud/doc/oidc-config-examples.md

31 - OIDC Config Examples

Configuration examples for integrating with different OIDC (OpenID Connect) providers. One OIDC provider per instance.

Table of Contents

1. General OIDC Configuration
2. Authentik
3. Authelia
4. KeyCloak
5. Troubleshooting

General OIDC Configuration

To enable OIDC, set these environment variables:

# Enable OIDC
OXICLOUD_OIDC_ENABLED=true

# OIDC provider configuration
OXICLOUD_OIDC_PROVIDER_NAME="Display Name"
OXICLOUD_OIDC_ISSUER_URL="https://provider.example.com/realms/your-realm"
OXICLOUD_OIDC_CLIENT_ID="your-client-id"
OXICLOUD_OIDC_CLIENT_SECRET="your-client-secret"
OXICLOUD_OIDC_REDIRECT_URI="https://your-oxicloud.example.com/api/auth/oidc/callback"
OXICLOUD_OIDC_SCOPES="openid profile email"
OXICLOUD_OIDC_FRONTEND_URL="https://your-oxicloud.example.com"
OXICLOUD_OIDC_AUTO_PROVISION="true"
OXICLOUD_OIDC_ADMIN_GROUPS="admin-group"
OXICLOUD_OIDC_DISABLE_PASSWORD_LOGIN="false"

Authentik

Authentik is an open-source identity platform providing authentication, authorization, and user management.

1. Create an Application in Authentik

1. Log into the Authentik admin panel
2. Go to "Applications" -> "Create"
3. Enter a name for the application (e.g. "OxiCloud")
4. Select "OAuth2/OpenID Provider" as the provider type
5. In the OAuth2 configuration:
   • Redirect URI/Callback URL: https://your-oxicloud.example.com/api/auth/oidc/callback
   • Client Type: Confidential
   • Client ID: auto-generated (note it down)
   • Client Secret: auto-generated (note it down)
   • Scopes: openid, email, profile
6. In the UI configuration:
   • Launch URL: https://your-oxicloud.example.com/
   • Icon: optional

2. Configure for Authentik

# docker-compose.yml
version: '3'
services:
  oxicloud:
    image: oxicloud:latest
    environment:
      OXICLOUD_OIDC_ENABLED: "true"
      OXICLOUD_OIDC_PROVIDER_NAME: "Authentik"
      OXICLOUD_OIDC_ISSUER_URL: "https://authentik.example.com/application/o/oxicloud"
      OXICLOUD_OIDC_CLIENT_ID: "your-authentik-client-id"
      OXICLOUD_OIDC_CLIENT_SECRET: "your-authentik-client-secret"
      OXICLOUD_OIDC_REDIRECT_URI: "https://oxicloud.example.com/api/auth/oidc/callback"
      OXICLOUD_OIDC_SCOPES: "openid profile email"
      OXICLOUD_OIDC_FRONTEND_URL: "https://oxicloud.example.com"
      OXICLOUD_OIDC_AUTO_PROVISION: "true"
      OXICLOUD_OIDC_ADMIN_GROUPS: ""
      OXICLOUD_OIDC_DISABLE_PASSWORD_LOGIN: "false"
    ports:
      - "8086:8086"
    volumes:
      - ./storage:/app/storage

Authelia

Authelia is an open-source multi-factor authentication solution.

1. Configure Authelia

Edit your Authelia configuration (configuration.yml):

identity_providers:
  oidc:
    hmac_secret: your-secure-secret  # Change to a secure random value
    issuer_private_key: /config/private.pem  # Path to your private key
    cors:
      endpoints: ['authorization', 'token', 'revocation', 'introspection']
      allowed_origins:
        - https://oxicloud.example.com
    clients:
      - id: oxicloud
        description: OxiCloud
        secret: your-secure-client-secret  # Change this
        public: false
        authorization_policy: two_factor
        redirect_uris:
          - https://oxicloud.example.com/api/auth/oidc/callback
        scopes: ['openid', 'profile', 'email', 'groups']
        userinfo_signing_algorithm: none

2. Configure for Authelia

# docker-compose.yml
version: '3'
services:
  oxicloud:
    image: oxicloud:latest
    environment:
      OXICLOUD_OIDC_ENABLED: "true"
      OXICLOUD_OIDC_PROVIDER_NAME: "Authelia"
      OXICLOUD_OIDC_ISSUER_URL: "https://authelia.example.com"
      OXICLOUD_OIDC_CLIENT_ID: "oxicloud"
      OXICLOUD_OIDC_CLIENT_SECRET: "your-secure-client-secret"
      OXICLOUD_OIDC_REDIRECT_URI: "https://oxicloud.example.com/api/auth/oidc/callback"
      OXICLOUD_OIDC_SCOPES: "openid profile email groups"
      OXICLOUD_OIDC_FRONTEND_URL: "https://oxicloud.example.com"
      OXICLOUD_OIDC_AUTO_PROVISION: "true"
      OXICLOUD_OIDC_ADMIN_GROUPS: ""
      OXICLOUD_OIDC_DISABLE_PASSWORD_LOGIN: "false"
    ports:
      - "8086:8086"
    volumes:
      - ./storage:/app/storage

KeyCloak

KeyCloak is an open-source identity and access management solution.

1. Create a Client in KeyCloak

1. Log into the KeyCloak admin console
2. Select your Realm
3. Go to "Clients" -> "Create"
4. Fill in the form:
   • Client ID: oxicloud
   • Client Protocol: openid-connect
   • Root URL: https://oxicloud.example.com
5. In the client configuration:
   • Access Type: confidential
   • Valid Redirect URIs: https://oxicloud.example.com/api/auth/oidc/callback
   • Web Origins: https://oxicloud.example.com (or + to allow all origins)
6. Save the configuration
7. Go to the "Credentials" tab and copy the generated "Secret"

2. Configure for KeyCloak

# docker-compose.yml
version: '3'
services:
  oxicloud:
    image: oxicloud:latest
    environment:
      OXICLOUD_OIDC_ENABLED: "true"
      OXICLOUD_OIDC_PROVIDER_NAME: "KeyCloak"
      OXICLOUD_OIDC_ISSUER_URL: "https://keycloak.example.com/realms/your-realm"
      OXICLOUD_OIDC_CLIENT_ID: "oxicloud"
      OXICLOUD_OIDC_CLIENT_SECRET: "your-keycloak-client-secret"
      OXICLOUD_OIDC_REDIRECT_URI: "https://oxicloud.example.com/api/auth/oidc/callback"
      OXICLOUD_OIDC_SCOPES: "openid profile email"
      OXICLOUD_OIDC_FRONTEND_URL: "https://oxicloud.example.com"
      OXICLOUD_OIDC_AUTO_PROVISION: "true"
      OXICLOUD_OIDC_ADMIN_GROUPS: "oxicloud-admins"
      OXICLOUD_OIDC_DISABLE_PASSWORD_LOGIN: "false"
    ports:
      - "8086:8086"
    volumes:
      - ./storage:/app/storage

Troubleshooting

Error: "Failed to discover OIDC provider"

The backend cannot reach the provider's discovery endpoint.

Fixes:

1. Verify the discovery URL is correct
2. Check that the backend can reach the URL (firewalls, DNS, etc.)
3. If using a self-signed certificate, configure the appropriate trust

Error: "Invalid redirect URI"

The OIDC provider is rejecting the redirect URI.

Fixes:

1. Make sure the redirect URI configured in the backend matches exactly what is registered in the provider
2. Check for protocol differences (http vs https), port, or path mismatches

Error: "User does not exist and auto-creation is disabled"

Fixes:

1. Enable auto-provisioning: OXICLOUD_OIDC_AUTO_PROVISION="true"
2. Or manually create the user before attempting OIDC login

Error: "Could not extract user ID from claim"

The backend cannot find the user ID attribute in the token claims.

Fixes:

1. Verify the provider returns the sub claim in tokens
2. Make sure scopes in OXICLOUD_OIDC_SCOPES include openid
3. Configure the provider to include the required claims in tokens

See oidc-architecture.md and oidc-integration.md for deeper technical details.