OIDC Authentication

Apex Home supports OpenID Connect (OIDC) authentication, allowing you to integrate with external identity providers like Auth0, Okta, Keycloak, or any standard OIDC provider.

Configuring OIDC Authentication

To enable and configure OIDC authentication in Apex Home:

1. Navigate to the server where Apex Home is installed.

2. Edit the environment variables for your Apex Home instance:

   If using Docker, edit your docker-compose.yml file to add the following environment variables:

   environment:
     # ... existing environment variables ...
     OIDC_ENABLED: "true"
     OIDC_PROVIDER_NAME: "Your Provider Name"
     OIDC_CLIENT_ID: "your-client-id"
     OIDC_CLIENT_SECRET: "your-client-secret"
     OIDC_ISSUER_URL: "https://your-oidc-provider.com"
     OIDC_REDIRECT_URI: "http://your-server:8000/auth/callback"
     OIDC_SCOPES: "openid profile email"
     OIDC_AUTO_REGISTRATION: "true"  # Optional - allows new users to be auto-registered on first login

   If installing directly on a server, add these variables to your .env file.

3. Restart your Apex Home instance to apply the changes:

   docker-compose down
   docker-compose up -d

4. After restarting, you should see an "Log in with OIDC" option on the login page.

OIDC Configuration Parameters

Parameter	Description	Required	Default
OIDC_ENABLED	Set to "true" to enable OIDC authentication	Yes	false
OIDC_PROVIDER_NAME	Display name for your OIDC provider	Yes	-
OIDC_CLIENT_ID	Client ID from your OIDC provider	Yes	-
OIDC_CLIENT_SECRET	Client secret from your OIDC provider	Yes	-
OIDC_ISSUER_URL	URL of your OIDC provider's issuer	Yes	-
OIDC_REDIRECT_URI	Callback URL for authentication	Yes	-
OIDC_SCOPES	Space-separated list of scopes to request	No	"openid profile email"
OIDC_AUTO_REGISTRATION	Allow new users to be created on first login	No	false

Provider-Specific Setup

Auth0

1. Create a new application in Auth0 dashboard.
2. Set Application Type to "Regular Web Application".
3. Add http://your-server:8000/auth/callback to Allowed Callback URLs.
4. Copy Client ID and Client Secret to your configuration.
5. Use https://your-auth0-domain.auth0.com as your OIDC_ISSUER_URL.

Okta

1. Create a new application in Okta Admin dashboard.
2. Choose "Web" as the platform.
3. Set Sign-in redirect URIs to http://your-server:8000/auth/callback.
4. Copy Client ID and Client Secret to your configuration.
5. Use https://your-okta-domain.okta.com as your OIDC_ISSUER_URL.

Keycloak

1. Create a new client in your Keycloak realm.
2. Set Client Protocol to "openid-connect".
3. Set Access Type to "confidential".
4. Add http://your-server:8000/auth/callback to Valid Redirect URIs.
5. Copy Client ID from the "Settings" tab.
6. Get Client Secret from the "Credentials" tab.
7. Use http://your-keycloak-server:8080/realms/your-realm as your OIDC_ISSUER_URL.

User Mapping

When a user authenticates via OIDC for the first time:

1. If OIDC_AUTO_REGISTRATION is enabled and the user doesn't exist, a new user is created using:

   • Username: From the "preferred_username" or "email" claim
   • Full Name: From the "name" claim
   • Site Name: Default "Apex Home"

2. If the user already exists (matching by username), they are logged in to their existing account.

3. If the user doesn't exist and OIDC_AUTO_REGISTRATION is disabled, login will fail.

Security Considerations

• Always use HTTPS in production environments to protect authentication data.
• Limit the scopes requested to only what's needed.
• Consider implementing additional security measures like rate limiting.
• Review OIDC provider logs regularly for suspicious activities.