SSO Setup (OpenID Connect)

MeshMonitor supports Single Sign-On (SSO) via OpenID Connect (OIDC), allowing you to integrate with enterprise identity providers like Auth0, Okta, Keycloak, Azure AD, and more.

Overview

OIDC integration provides:

• Centralized Authentication: Use your existing identity provider
• Auto-User Creation: Automatically create users on first login
• Authorization Code Flow with PKCE: Secure authentication flow
• ID Token Verification: Validates tokens from the identity provider
• Multiple Providers: Support for any OIDC-compliant provider

Prerequisites

Before configuring SSO, you need:

1. An OIDC-compliant identity provider (IdP)
2. A registered OAuth/OIDC application/client in your IdP
3. The following information from your IdP:
   • Issuer URL
   • Client ID
   • Client Secret
   • Redirect URI (callback URL)

Configuration

Environment Variables

Configure OIDC using these environment variables:

Variable	Description	Required
OIDC_ISSUER	Your identity provider's issuer URL	Yes
OIDC_CLIENT_ID	OAuth client ID from your IdP	Yes
OIDC_CLIENT_SECRET	OAuth client secret from your IdP	Yes
OIDC_REDIRECT_URI	Callback URL for OIDC authentication	Yes

Optional variables:

Variable	Default	Description
OIDC_SCOPES	openid profile email	Scopes requested from the IdP. Add groups (or your provider's equivalent) if you use group→role mapping.
OIDC_AUTO_CREATE_USERS	true	Create a MeshMonitor user automatically on first OIDC login.
OIDC_GROUPS_CLAIM	groups	ID-token claim containing the user's groups. Supports dot notation for nested claims (e.g. realm_access.roles for Keycloak).
OIDC_ADMIN_GROUPS	(empty)	Comma-separated group names that grant MeshMonitor admin rights. See Group → Role Mapping.
OIDC_ALLOWED_GROUPS	(empty)	Comma-separated group names allowed to log in at all. Empty = all OIDC users allowed.
DISABLE_LOCAL_AUTH	false	Disable username/password login entirely (see Disabling Local Authentication).

Example Configuration

Docker Compose

services:
  meshmonitor:
    image: meshmonitor:latest
    environment:
      - MESHTASTIC_NODE_IP=192.168.1.100
      - OIDC_ISSUER=https://your-domain.auth0.com
      - OIDC_CLIENT_ID=your_client_id_here
      - OIDC_CLIENT_SECRET=your_client_secret_here
      - OIDC_REDIRECT_URI=https://meshmonitor.example.com/api/auth/oidc/callback
    ports:
      - "8080:8080"

Environment File (.env)

MESHTASTIC_NODE_IP=192.168.1.100
OIDC_ISSUER=https://your-domain.auth0.com
OIDC_CLIENT_ID=your_client_id_here
OIDC_CLIENT_SECRET=your_client_secret_here
OIDC_REDIRECT_URI=https://meshmonitor.example.com/api/auth/oidc/callback

Group → Role Mapping

By default, every OIDC user is created as a regular user, and the first OIDC login is bootstrapped to admin so the deployment isn't locked out; subsequent users must be promoted manually in the admin UI.

To map identity-provider groups to MeshMonitor roles automatically, set OIDC_ADMIN_GROUPS (and optionally OIDC_ALLOWED_GROUPS):

OIDC_SCOPES=openid profile email groups
OIDC_GROUPS_CLAIM=groups
OIDC_ADMIN_GROUPS=meshmonitor-admins
OIDC_ALLOWED_GROUPS=meshmonitor-users,meshmonitor-admins

Behaviour:

• Admin status follows the group on every login. When OIDC_ADMIN_GROUPS is set, a user in one of those groups is made admin, and a user not in one is demoted (the IdP becomes authoritative — the first-login bootstrap no longer applies). When OIDC_ADMIN_GROUPS is empty, admin status is never changed by group membership and the bootstrap / manual-promotion behaviour is preserved.
• OIDC_ALLOWED_GROUPS gates who may log in at all. If set, a user in none of the listed groups is denied (admins always pass). Empty = all OIDC users allowed.
• Group changes take effect on the user's next login (OIDC rides a session; unlike proxy auth, it is not re-evaluated on every request).

WARNING

If you set OIDC_ADMIN_GROUPS, make sure your own account is in that group, or keep a local admin as a break-glass login — otherwise you can demote yourself out of admin. The groups claim must be present in the ID token (configure a mapper in your IdP), not only at the userinfo endpoint.

Keycloak

Add a Group Membership or Realm roles mapper to the client's dedicated scope and include it in the ID token. Realm roles arrive under a nested claim:

OIDC_GROUPS_CLAIM=realm_access.roles
OIDC_ADMIN_GROUPS=meshmonitor-admin

Authentik

Groups are emitted in the groups claim by default (ensure the groups scope is requested). The defaults work as-is:

OIDC_SCOPES=openid profile email groups
OIDC_GROUPS_CLAIM=groups
OIDC_ADMIN_GROUPS=meshmonitor admins

TIP

If you front Keycloak/Authentik with a reverse proxy such as oauth2-proxy, you can instead use proxy auth (PROXY_AUTH_ENABLED=true with PROXY_AUTH_ADMIN_GROUPS / PROXY_AUTH_NORMAL_USER_GROUPS / PROXY_AUTH_JWT_GROUPS_CLAIM), which re-evaluates group membership on every request. See the reverse-proxy documentation.

Provider-Specific Setup

Auth0

1. Log in to your Auth0 dashboard
2. Create a new application:
   • Type: "Regular Web Application"
   • Name: "MeshMonitor"
3. Configure the application:
   • Allowed Callback URLs: https://meshmonitor.example.com/api/auth/oidc/callback
   • Allowed Logout URLs: https://meshmonitor.example.com
4. Get your credentials from the "Settings" tab:
   • Domain: your-domain.auth0.com
   • Client ID: Copy the Client ID
   • Client Secret: Copy the Client Secret

Environment Variables:

OIDC_ISSUER=https://your-domain.auth0.com
OIDC_CLIENT_ID=<your-client-id>
OIDC_CLIENT_SECRET=<your-client-secret>
OIDC_REDIRECT_URI=https://meshmonitor.example.com/api/auth/oidc/callback

Keycloak

1. Log in to your Keycloak admin console
2. Create a new client:
   • Client ID: meshmonitor
   • Client Protocol: openid-connect
   • Access Type: confidential
3. Configure the client:
   • Valid Redirect URIs: https://meshmonitor.example.com/api/auth/oidc/callback
   • Web Origins: https://meshmonitor.example.com
4. Get your credentials from the "Credentials" tab

Environment Variables:

OIDC_ISSUER=https://keycloak.example.com/realms/your-realm
OIDC_CLIENT_ID=meshmonitor
OIDC_CLIENT_SECRET=<your-client-secret>
OIDC_REDIRECT_URI=https://meshmonitor.example.com/api/auth/oidc/callback

Azure AD (Entra ID)

1. Log in to Azure Portal
2. Navigate to Azure Active Directory → App registrations
3. Create a new registration:
   • Name: "MeshMonitor"
   • Supported account types: Choose appropriate option
   • Redirect URI: https://meshmonitor.example.com/api/auth/oidc/callback
4. Create a client secret in "Certificates & secrets"
5. Note your Tenant ID and Application (client) ID

Environment Variables:

OIDC_ISSUER=https://login.microsoftonline.com/<tenant-id>/v2.0
OIDC_CLIENT_ID=<application-id>
OIDC_CLIENT_SECRET=<client-secret>
OIDC_REDIRECT_URI=https://meshmonitor.example.com/api/auth/oidc/callback

Okta

1. Log in to your Okta admin dashboard
2. Create a new Web application:
   • Application type: "Web"
   • Grant type: "Authorization Code"
3. Configure the application:
   • Sign-in redirect URIs: https://meshmonitor.example.com/api/auth/oidc/callback
   • Sign-out redirect URIs: https://meshmonitor.example.com
4. Copy your Client ID and Client Secret

Environment Variables:

OIDC_ISSUER=https://your-domain.okta.com
OIDC_CLIENT_ID=<your-client-id>
OIDC_CLIENT_SECRET=<your-client-secret>
OIDC_REDIRECT_URI=https://meshmonitor.example.com/api/auth/oidc/callback

Google OAuth

1. Go to Google Cloud Console
2. Create a new project or select existing
3. Enable the Google+ API
4. Create OAuth 2.0 credentials:
   • Application type: "Web application"
   • Authorized redirect URIs: https://meshmonitor.example.com/api/auth/oidc/callback
5. Copy your Client ID and Client Secret

Environment Variables:

OIDC_ISSUER=https://accounts.google.com
OIDC_CLIENT_ID=<your-client-id>.apps.googleusercontent.com
OIDC_CLIENT_SECRET=<your-client-secret>
OIDC_REDIRECT_URI=https://meshmonitor.example.com/api/auth/oidc/callback

Authentication Flow

When OIDC is configured, users see a "Sign in with SSO" button on the login page.

Login Process

1. User clicks "Sign in with SSO"
2. User is redirected to the identity provider
3. User authenticates with their IdP credentials
4. IdP redirects back to MeshMonitor with an authorization code
5. MeshMonitor exchanges the code for an ID token
6. User account is created/updated automatically
7. User is logged in and redirected to the dashboard

User Attributes

MeshMonitor extracts these attributes from the ID token:

• Username: From preferred_username or email claim
• Email: From email claim
• Display Name: From name claim
• OIDC Subject: From sub claim (used for linking accounts)

User Management

Auto-User Creation

When a user logs in via OIDC for the first time:

• A new user account is automatically created
• The user is marked as using OIDC authentication
• The OIDC subject (sub claim) is stored for future logins

Admin Privileges

The first OIDC user to log in is automatically promoted to admin. This bootstrap exists so a deployment isn't locked out when local authentication is disabled — without it there would be no way to administer the instance via SSO. The first OIDC user receives full admin rights and permissions on all resources.

All subsequent OIDC users are created as regular (non-admin) accounts. SSO login does not elevate their privileges automatically; admin access must be granted explicitly by an existing admin.

WARNING

"First OIDC user" means the first user whose authentication method is OIDC — it is independent of any local accounts (such as the built-in admin account) that may already exist. If you do not want the first SSO sign-in to gain admin rights, create and configure your admins ahead of time, or keep local authentication enabled and manage permissions from a local admin account.

To grant admin to an additional OIDC user:

1. Log in as an existing admin (e.g. the built-in admin local account)
2. Navigate to Settings → Users
3. Select the user and grant admin / per-source permissions as needed

TIP

Keep at least one local admin account available as a break-glass login in case your OIDC provider is unreachable.

Disabling Local Authentication

To use OIDC (or proxy auth) exclusively, set:

DISABLE_LOCAL_AUTH=true

When enabled, username/password login is blocked entirely — the /api/auth/login endpoint returns 403 and the login UI hides the username/password form. There is no local API bypass.

DANGER

Because there is no local login bypass, make sure a working OIDC (or proxy) login exists before enabling this, or you can lock yourself out. The only safety net is the first-OIDC-login admin bootstrap (which does not apply if you have also set OIDC_ADMIN_GROUPS — in that case ensure your account is in an admin group). If you rely on a break-glass local admin, do not set DISABLE_LOCAL_AUTH=true.

Troubleshooting

Redirect URI Mismatch

Error: "redirect_uri_mismatch" or similar

Solution: Ensure the OIDC_REDIRECT_URI exactly matches the callback URL configured in your identity provider, including:

• Protocol (http vs https)
• Port number (if not standard)
• Path (/api/auth/oidc/callback)

Invalid Issuer

Error: "Discovery failed" or "Invalid issuer"

Solution:

• Verify the OIDC_ISSUER URL is correct
• Ensure the issuer has a publicly accessible .well-known/openid-configuration endpoint
• Test: curl https://your-issuer.com/.well-known/openid-configuration

Token Validation Failures

Error: "ID token validation failed"

Solution:

• Check that your client secret is correct
• Verify your identity provider's token signing algorithm is supported (RS256, HS256)
• Ensure system time is synchronized (NTP)

Users Not Being Created

If users can authenticate but don't appear in MeshMonitor:

1. Check the backend logs for errors
2. Verify the ID token contains required claims (sub, email or preferred_username)
3. Check database permissions

Security Best Practices

Use HTTPS

Always use HTTPS in production when using OIDC:

OIDC_REDIRECT_URI=https://meshmonitor.example.com/api/auth/oidc/callback

Protect Client Secret

Never commit your client secret to version control:

• Use environment variables
• Use secret management tools (Vault, AWS Secrets Manager, etc.)
• Rotate secrets regularly

Restrict Redirect URIs

In your identity provider, only whitelist the exact redirect URI you need. Do not use wildcards.

Monitor Authentication Logs

Regularly review authentication logs for suspicious activity:

# Docker
docker logs meshmonitor | grep "auth"

# Kubernetes
kubectl logs -f deployment/meshmonitor | grep "auth"

Combining OIDC with Local Auth

You can use both OIDC and local authentication simultaneously:

• OIDC for regular users
• Local auth for admin/service accounts

This provides a fallback if your identity provider becomes unavailable.

Next Steps

• Configure a reverse proxy for HTTPS
• Set up production deployment with proper monitoring
• Learn about HTTP vs HTTPS considerations