Embedded OIDC Authentication

Default on platform train v3.9.0

Datasance PoT v3.9.0 uses embedded OIDC as the default auth mode. You do not need an external IdP for a standard lab or production deploy. Upgrading from v3.8.0 usually keeps auth.mode: embedded; see Upgrading to v3.9.0.

Agent routes

Edgelet agent routes (/api/v3/agent/*) use fog-token auth. OIDC applies to operator and user APIs, not field agents.

Embedded OIDC ships inside the Controller image. The issuer runs at {CONTROLLER_PUBLIC_URL}/oidc. EdgeOps Console and potctl use the same OAuth BFF and RBAC model.

For enterprise IdP integration (Okta, Microsoft Entra ID, Keycloak, or any OIDC provider), see External OIDC Authentication.

When to use embedded OIDC

Scenario	Use embedded OIDC
New deploy on platform train v3.9.0	Yes (default)
Lab or single-site install	Yes
Quick start and tutorials	Yes
Corporate SSO required	No. Use External OIDC

Minimal Control Plane YAML

Set auth.mode: embedded and bootstrap credentials in your Control Plane manifest. potctl maps these fields to Controller environment variables at deploy time.

auth:
  mode: embedded
  bootstrap:
    username: admin
    password: "LocalTest12!"   # ≥12 chars, 1 uppercase, 1 special character
controller:
  publicUrl: https://controller.example.com:51121
  consoleUrl: https://console.example.com:8008

Local Docker installs can set auth.insecureAllowHttp: true when publicUrl uses http://. Production deploys should use HTTPS and valid TLS certificates.

Full YAML field reference: Control plane in Learn. Runtime env mapping: Controller configuration.

Core environment variables

These are the primary knobs for embedded auth. YAML keys under auth.* and controller.* map to the same names.

Environment variable	YAML key	Embedded mode
AUTH_MODE	auth.mode	Set to embedded (default)
CONTROLLER_PUBLIC_URL	controller.publicUrl	Required. Issuer base is {CONTROLLER_PUBLIC_URL}/oidc
CONSOLE_URL	controller.consoleUrl	Public EdgeOps Console URL for OAuth redirects
CONSOLE_PORT	controller.consolePort	Console listen port (default 8008)
OIDC_CLIENT_ID	auth.client.id	Default controller for the confidential API client
OIDC_BOOTSTRAP_ADMIN_USERNAME	auth.bootstrap.username	First admin login name
OIDC_BOOTSTRAP_ADMIN_PASSWORD	auth.bootstrap.password	Bootstrap admin password
AUTH_INSECURE_ALLOW_HTTP	auth.insecureAllowHttp	Allow http:// in CONTROLLER_PUBLIC_URL (dev only)
TRUST_PROXY	controller.trustProxy	Honor X-Forwarded-* behind a reverse proxy

Optional embedded-only settings (AUTH_SESSION_*, token TTL overrides, rate limits, optional Console public client flags) are listed in Controller configuration.

TLS environment variables

Controller renamed SSL_* to TLS_*. Listener certificates are used for HTTPS, agent trust on provision, and embedded OAuth token exchange.

Environment variable	YAML key	Purpose
TLS_PATH_CERT	controller.tls.cert or mounted secret	TLS certificate
TLS_PATH_KEY	controller.tls.key	TLS private key
TLS_PATH_INTERMEDIATE_CERT	controller.tls.intermediateCert	Intermediate / chain certificate
TLS_BASE64_CERT	base64 in YAML	Alternative to file paths
TLS_BASE64_KEY	base64 in YAML	Alternative to file paths

On Kubernetes, the operator can inject TLS from a Secret (controller.secretName) instead of path env vars.

First login

Bootstrap admin

On first startup, Controller creates the bootstrap admin when no admin user exists. Set credentials in deploy YAML or env before the first boot:

auth:
  mode: embedded
  bootstrap:
    username: admin
    password: "LocalTest12!"

If env credentials change later, Controller reconciles the bootstrap user. Plan credential rotation during a maintenance window.

EdgeOps Console (browser)

1. Open the Console at CONSOLE_URL, or run potctl view.
2. Click Sign in.
3. Complete the embedded login form at {CONSOLE_URL}/login/oauth?interaction=….
4. Enroll MFA when prompted (required for users in the admin group after first login).

Browser login uses the OAuth BFF (GET /api/v3/user/oauth/authorize) with prompt=login so each sign-in starts a fresh issuer interaction. The Console does not POST passwords directly to an external IdP.

Logout: POST /api/v3/user/logout revokes refresh tokens and clears embedded issuer and BFF session state. Access JWTs remain valid until they expire.

CLI

potctl login

Or call the REST API:

curl -sS -X POST "${CONTROLLER_PUBLIC_URL}/api/v3/user/login" \
  -H 'Content-Type: application/json' \
  -d '{"email":"admin","password":"LocalTest12!","totp":""}'

Use the bootstrap username as email when it is not an email address. MFA applies for users in the admin group when enrolled.

Embedded-only admin APIs

Endpoint	Purpose
POST /api/v3/auth/jwks/rotate	Rotate embedded OIDC signing keys (admin Bearer). Restart Controller after rotation.
POST /api/v3/auth/migration/export	Export users and groups for a one-way move to External OIDC
GET/POST /api/v3/users	Embedded user administration

External → embedded is not supported.

What embedded OIDC replaces

Removed (v1.6 / v3.7)	Current embedded
Keycloak realm setup before deploy	Not required
auth.url, auth.realm, viewerClient	auth.mode: embedded
ECN Viewer OAuth client	EdgeOps Console via Controller BFF
KC_* env vars	OIDC_*, AUTH_*, TLS_*

HA notes

Database	Controller replicas	Embedded issuer
SQLite (default)	1 only	Supported
MySQL / PostgreSQL	2+	Supported (shared DB)

For multi-replica browser login with an external IdP, use AUTH_SESSION_STORE_TYPE=database. Embedded mode with mysql/postgres auto-selects database-backed BFF sessions when configured.

Next steps

Document	Topic
Platform Deployment Introduction	Remote or Kubernetes Control Plane
Quick Start With Local Deployment	Local ECN with embedded auth
External OIDC Authentication	Optional enterprise IdP
External OIDC providers	IdP group mapping and recipes
EdgeOps Console configuration	consoleUrl and runtime auth.* paths
Controller configuration	Full env var tables

See anything wrong with the document? Help us improve it!

Edit this page on GitHub!