OIDC Provider - green-ecolution/backend GitHub Wiki

What is an OpenID Connect (OIDC) Provider?

An OpenID Connect (OIDC) provider is a service that helps with identity and authentication. It is based on the OAuth 2.0 protocol and provides a standard way to verify users securely. It allows Single Sign-On (SSO), so users can log in once and access different services. It also provides tokens that allow users to access APIs securely. More about it you can folow datatracker.ietf.org

OIDC Configuration in our System

In our backend system, the OIDC provider is set up using a central configuration structure. This structure defines all important endpoints and access details. These values are loaded from a YAML configuration file. The file contains:

  • The base URL of the Keycloak server
  • The name of the realm
  • Authentication and token endpoints
  • Client IDs and secrets for the frontend and backend

Here is the struct used for this configuration in our system:

type OidcProvider struct {
	BaseURL    string        `mapstructure:"base_url"`
	DomainName string        `mapstructure:"domain_name"`
	AuthURL    string        `mapstructure:"auth_url"`
	TokenURL   string        `mapstructure:"token_url"`
	PublicKey  OidcPublicKey `mapstructure:"public_key"`
	Frontend   OidcClient    `mapstructure:"frontend"`
	Backend    OidcClient    `mapstructure:"backend"`
}

General Expectations from the OIDC Provider

Our backend does not rely on a specific OIDC provider. Instead, it is designed to work with any provider that follows the OIDC standard and supports the required core features, such as:

  • Redirecting users to a login page
  • Exchanging an authorization code for access and refresh tokens
  • Validating tokens (e.g. using introspection or signature verification)
  • Managing users and roles

This generic setup gives us the flexibility to switch to a different OIDC provider in the future with minimal changes, as long as the new provider complies with the OIDC specification.

That said, in our current implementation we use Keycloak as the OIDC provider, and we integrate it in our backend using the Go client library gocloak, which provides a convenient way to communicate with the Keycloak REST API.

Authentication Flow: Authorization Code

The Authorization Code Flow is the main login process we use with OIDC. It is secure and widely used in modern web apps.

The flow works like this:

  • The user is redirected to the OIDC provider’s login page.
  • After logging in, the user is redirected back to the application with an authorization code.
  • The backend then sends this code to the OIDC provider to receive access and refresh tokens.

This keeps credentials secure, as the app never sees the user's password.

For the full technical description, refer to: Section 4.1 Authorization Code Grant

Login Flow

image

Keycloack

For Identity and Access Management Keycloack is used. Keycloack supports multiple Realms which acts as a security domain, meaning that users, roles, and clients within one realm are completely separate from those in another. In this way it is possible to separate development, stage, and production environment.

A Client in Keycloak represents an application or service that relies on Keycloak for authentication and authorization. To specify:

  • flasher-client
  • argocd
  • minio
  • green-ecolution-backend (backend API)
  • green-ecolution-frontend (web app)
  • plugins

A User represents a person who logs into a Keycloak-protected system. Users can have roles, groups, and permissions assigned to them. The project added multiple custom attributes to keycloack user profile:

  • minio_policy: Access S3
  • user_roles: The company of the user (green-ecolution, tbz, smarte-grenzregion)
  • status: User status (available or absent)
  • driving_licenses: B, BE, C, CE
  • ttn: Used for Flasher to access API-Key