Add OIDC / external authentication support for OpenEMS Edge UI

[Christoph-87]

Component

Edge

Description

Use case

I run OpenEMS Edge in a self-hosted environment and would like to use an external identity provider, in my case Authentik, as the primary authentication mechanism for the OpenEMS UI.

Instead of using the built-in OpenEMS Edge password login page, I would like users to authenticate through Authentik/SSO and then be logged into OpenEMS automatically.

For a home or small commercial installation, this would make it possible to manage access centrally in the identity provider, avoid sharing or managing a separate OpenEMS Edge password, and integrate OpenEMS into an existing self-hosted SSO setup.

Current behavior

OpenEMS appears to have OAuth/OIDC-related authentication support for OpenEMS Backend, but the Edge UI / Edge WebSocket authentication path seems to only support local password/token based authentication.

In an Edge-only deployment, OIDC cannot currently be enabled just by configuration.

Desired behavior

OpenEMS Edge should support an external authentication mechanism, so that users who are already authenticated by an identity provider can be logged into the OpenEMS UI automatically.

Possible approaches could be:

Option 1: Native OIDC support for OpenEMS Edge

Add OIDC login support to OpenEMS Edge, similar in spirit to the existing backend OAuth/OIDC support.

Useful configuration options could include:

• OIDC issuer URL / discovery URL
• client ID
• client secret, if needed
• redirect URI
• scopes
• claim mapping for username/display name
• group or role mapping to OpenEMS roles
• logout behavior

This would allow providers such as Authentik, Keycloak, Authelia, Zitadel, etc. to be used directly.

Option 2: Trusted reverse proxy authentication

Alternatively, OpenEMS Edge could support a trusted reverse proxy authentication mode.

In this model, an external proxy or identity provider outpost authenticates the user and forwards identity headers to OpenEMS, for example:

• X-authentik-username
• X-authentik-email
• X-authentik-groups

OpenEMS Edge would only trust these headers when the request comes from explicitly configured trusted proxy IPs or networks.

Useful configuration options could include:

• enable/disable external header authentication
• trusted proxy IPs/CIDRs
• header names for username/email/groups
• mapping from external groups to OpenEMS roles
• fallback behavior for local password login

Security considerations

If reverse proxy header authentication is implemented, it should be disabled by default and only work when trusted proxy addresses are explicitly configured. OpenEMS should never blindly trust authentication headers from arbitrary clients.

OIDC would probably be the cleaner general-purpose solution, while trusted proxy authentication may be simpler for self-hosted deployments that already rely on Authentik/Authelia/Traefik.

Why this would be useful

This would make OpenEMS easier to integrate into existing self-hosted identity setups and avoid maintaining a separate OpenEMS password for every user.

It would also allow access control to be managed centrally through the identity provider, while OpenEMS continues to enforce its own roles/permissions internally.

[Christoph-87]

I had a quick look at the current code to see whether the existing Backend OAuth/OIDC support could be used as a reference for Edge.

There is already Backend-side OAuth/OIDC support, especially in:

• io.openems.backend.authentication.oauth2
• io.openems.backend.uiwebsocket.impl.OAuthAuthenticationHandler
• the UI OAuthService, which is currently gated for environment.backend === "OpenEMS Backend"

From what I can see, this is useful as a reference for the general flow:

• Authorization Code Flow with PKCE
• token exchange via the token endpoint
• JWT validation through JWKs
• JSON-RPC methods such as initiateConnect, getTokenByCode and getTokenByRefreshToken

However, it does not look directly reusable for Edge without adaptation. The Backend implementation depends on Backend-specific metadata and user lookup, for example Metadata.getUserByExternalId(...), as well as Backend/OEM OAuth configuration.

The Edge WebSocket authentication path seems to be separate and currently local-session based, mainly via authenticateWithPassword and authenticateWithToken in the Edge WebSocket handler. Edge also has its own local UserService model.

So my current understanding is:

• the existing Backend OIDC code can be used as a conceptual reference;
• some helper logic and the UI flow may be reusable or portable;
• an Edge implementation would still need an Edge-specific authentication handler;
• role/claim/group mapping to OpenEMS Edge roles would need to be defined;
• local password/setup-key login should probably remain available as fallback.

A smaller first step might still be trusted reverse proxy authentication, because it would avoid implementing a full OIDC client in Edge. But if native OIDC for Edge is preferred, the Backend implementation seems like the right place to start from.