ActiveDebianSync Web Console OAuth Authentication

• Back to the ActiveDebianSync main section

The web console supports two authentication methods: Local Authentication (default) - with Username/password stored in the local database
and the OAuth 2.0 Authentication, a- Single Sign-On via an external identity provider.
You can enable both methods simultaneously or use OAuth exclusively.

Manual configuration

Edit config.json

{
    "web_console_enabled": true,
    "web_console_port": 8090,

    "web_console_oauth_enabled": true,
    "web_console_oauth_provider": "Keycloak",
    "web_console_oauth_client_id": "activedebiansync-console",
    "web_console_oauth_client_secret": "your-client-secret",
    "web_console_oauth_auth_url": "https://auth.example.com/realms/main/protocol/openid-connect/auth",
    "web_console_oauth_token_url": "https://auth.example.com/realms/main/protocol/openid-connect/token",
    "web_console_oauth_userinfo_url": "https://auth.example.com/realms/main/protocol/openid-connect/userinfo",
    "web_console_oauth_scopes": "openid profile email",
    "web_console_oauth_redirect_url": "",
    "web_console_oauth_admin_group": "admin",
    "web_console_oauth_allow_local": true
}

Setup Examples

Keycloak

• Create a new client in your Keycloak realm:
•  Client ID: activedebiansync-console
• Client Protocol: openid-connect
• Access Type: confidential
• Valid Redirect URIs: https://your-server:8090/oauth/callback
   
• Get the client secret from the Credentials tab
• Configure ActiveDebianSync:

{
  "web_console_oauth_provider": "Keycloak",
  "web_console_oauth_auth_url": "https://keycloak.example.com/realms/{realm}/protocol/openid-connect/auth",
  "web_console_oauth_token_url": "https://keycloak.example.com/realms/{realm}/protocol/openid-connect/token",
  "web_console_oauth_userinfo_url": "https://keycloak.example.com/realms/{realm}/protocol/openid-connect/userinfo"
}

• To grant admin access, add users to a group named admin (or configure web_console_oauth_admin_group)

Azure AD / Entra ID

• Register an application in Azure AD:
  • Name: ActiveDebianSync Console
  • Redirect URI: https://your-server:8090/oauth/callback (Web platform)
  • Supported account types: Choose based on your needs
• Create a client secret under Certificates & secrets
• Configure ActiveDebianSync

{
  "web_console_oauth_provider": "Microsoft",
  "web_console_oauth_auth_url": "https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize",
  "web_console_oauth_token_url": "https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token",
  "web_console_oauth_userinfo_url": "https://graph.microsoft.com/oidc/userinfo",
  "web_console_oauth_scopes": "openid profile email"
}

Google

• Create OAuth credentials in Google Cloud Console:
  • Application type: Web application
  • Authorized redirect URIs: https://your-server:8090/oauth/callback
• Configure ActiveDebianSync:

{
  "web_console_oauth_provider": "Google",
  "web_console_oauth_auth_url": "https://accounts.google.com/o/oauth2/v2/auth",
  "web_console_oauth_token_url": "https://oauth2.googleapis.com/token",
  "web_console_oauth_userinfo_url": "https://openidconnect.googleapis.com/v1/userinfo",
  "web_console_oauth_scopes": "openid profile email"
}

Auth0

• Create a Regular Web Application in Auth0
• Configure ActiveDebianSync:

{
  "web_console_oauth_provider": "Auth0",
  "web_console_oauth_auth_url": "https://{tenant}.auth0.com/authorize",
  "web_console_oauth_token_url": "https://{tenant}.auth0.com/oauth/token",
  "web_console_oauth_userinfo_url": "https://{tenant}.auth0.com/userinfo"
}

GitHub

• Create an OAuth App in GitHub Settings > Developer settings
• Configure ActiveDebianSync:

{
  "web_console_oauth_provider": "GitHub",
  "web_console_oauth_auth_url": "https://github.com/login/oauth/authorize",
  "web_console_oauth_token_url": "https://github.com/login/oauth/access_token",
  "web_console_oauth_userinfo_url": "https://api.github.com/user",
  "web_console_oauth_scopes": "read:user user:email"
}

User Provisioning

When a user logs in via OAuth:

• If the user doesn't exist in the local database, they are automatically created
• The username is extracted from the OAuth response (in order of preference):
  • preferred_username
  • username
  • login (GitHub)
  • email
  • name
  • sub (subject identifier)

Admin status is determined by group/role membership

Admin Group Mapping

The web_console_oauth_admin_group setting specifies which group or role grants admin access:

• For Keycloak: Users in the specified group
• For Azure AD: Users with the specified role assigned
• For Auth0: Users with the specified role in the roles claim

Users without admin privileges can still view most pages but cannot modify settings.

Login Page Modes

Both OAuth and Local Login (Default)

When web_console_oauth_allow_local is true:

• Login page shows username/password form
• "Sign in with {Provider}" button appears below
• Users can choose either method

OAuth Only

When web_console_oauth_allow_local is false:

• Login page only shows the OAuth button
• Local username/password form is hidden
• Direct access to /login redirects to /oauth/login

Redirect URL Configuration

The redirect URL must match exactly what's configured in your OAuth provider.

If web_console_oauth_redirect_url is empty, it's automatically generated:

{scheme}://{listen_addr}:{port}{base_path}/oauth/callback

For production with a reverse proxy, you should explicitly set this:

{
  "web_console_oauth_redirect_url": "https://admin.example.com/oauth/callback"
}