Authentication Setup🔗

This guide provides detailed instructions for configuring your own OAuth 2.0 / OpenID Connect (OIDC) identity provider to work with the Apheris Hub.

For more information on authentication scenarios and how the Hub uses authentication, refer to the Docker Deployment Guide.

Identity Provider Requirements🔗

Your identity provider must meet the following requirements:

OIDC Discovery: Must provide a standard OIDC discovery endpoint at {domain}/.well-known/openid-configuration
JWKS Endpoint: Must expose a JWKS (JSON Web Key Set) endpoint for token signature validation
JWT Token Format: Must issue standard JWT access tokens
Required Token Claims: - iss (issuer): Must match the configured domain - aud (audience): Must include the configured audience - email: Must contain the user's email address (used for user identification and data segregation) - exp (expiration): Token expiration time

The Hub has been tested with Auth0. Other OIDC-compliant providers should work but have not been validated.

Setup Steps🔗

1. Create an Application🔗

Create a new Single Page Application (SPA) in your identity provider:

For Auth0:

Log in to your Auth0 Dashboard
Navigate to Applications → Create Application
Choose "Single Page Web Applications"
Note down the following values from the application settings (you'll need these later): - Domain: Found under the "Settings" tab (e.g., your-tenant.auth0.com or your-tenant.us.auth0.com) - Client ID: Found under the "Settings" tab (a long alphanumeric string)
Configure the application with the following settings:

Allowed Callback URLs:

Configure the following callback URL patterns, replacing https://your-hub-domain.com with your actual Hub URL:

https://your-hub-domain.com
https://your-hub-domain.com/login

Allowed Logout URLs:

Configure the following logout URL patterns, replacing https://your-hub-domain.com with your actual Hub URL:

https://your-hub-domain.com/login
https://your-hub-domain.com/terms-of-use

The /terms-of-use endpoint is where users are redirected after logging out to view the terms of service.

Allowed Web Origins:

Configure the origin URL, replacing https://your-hub-domain.com with your actual Hub URL:

https://your-hub-domain.com

2. Create an API🔗

Create an API identifier that represents your Apheris Hub backend:

For Auth0:

Navigate to Applications → APIs → Create API
Set a name (e.g., "Apheris Hub API")
Set a unique URL-like Identifier (e.g., https://hub.yourdomain.com/api) - This identifier becomes your Audience value (note down this value, you'll need it later)
Keep the signing algorithm as RS256

3. Configure Your Deployment🔗

Add the credentials to your config.yaml using the values you noted from the previous steps:

config.yaml

hub:
  auth:
    enabled: true
    domain: "https://your-tenant.auth0.com/"      # Your Auth0 domain (include trailing slash)
    audience: "https://hub.yourdomain.com/api"     # Your API identifier
    clientId: "your-application-client-id"         # Your SPA client ID
    browserUrl: "https://dex.yourdomain.com"       # Optional: public URL the browser uses to reach Auth0 or another IdP

Domain🔗

The issuer URL of your identity provider. This is used to discover the JWKS endpoint for token validation. - Where to find (Auth0): Applications → [Your Application] → Settings tab → Domain - Format: Must include https:// and a trailing slash (e.g., https://your-tenant.auth0.com/) - Example: If your Auth0 domain shows your-tenant.auth0.com, use https://your-tenant.auth0.com/

Audience🔗

The API identifier that tokens must be issued for. This ensures tokens are intended for the Apheris Hub API. - Where to find (Auth0): Applications → APIs → [Your API] → Settings tab → Identifier - Format: The exact identifier you specified when creating the API - Example: https://hub.yourdomain.com/api

Client ID🔗

The OAuth 2.0 client ID used by the Hub's frontend to authenticate users. - Where to find (Auth0): Applications → [Your Application] → Settings tab → Client ID - Format: A long alphanumeric string - Example: aBc123XyZ456def789GhI012jkL345Mn

Complete Auth0 Configuration Example

hub:
  auth:
    enabled: true
    domain: "https://your-tenant.auth0.com/"
    audience: "https://hub.yourdomain.com/api"
    clientId: "aBc123XyZ456def789GhI012jkL345Mn"
    browserUrl: "https://dex.yourdomain.com"

If your Hub runs behind Docker, Kubernetes, or another enterprise network where the browser reaches Dex/Auth0 via a public DNS name or ingress, set browserUrl (or the equivalent APH_HUB_AUTH_BROWSER_URL environment variable / Helm value from chart/templates/hub-deployment.yaml lines 64-83). The discovery proxy will fetch metadata using the configured issuer but rewrite URLs for the browser using this public address, keeping IdP working while preventing SSRF.

Next Steps🔗

After configuring your identity provider, return to the Docker Deployment Guide to continue with deploying the Hub.