Learn Authelia - OpenID Connect Provider

#Introduction

For the last four episodes, you've placed Authelia at the gateway: the proxy asks, Authelia answers with permission, and the application receives the Remote-User header. This pattern is great for applications that can sit behind a proxy. But there's a category of applications that can't simply be protected that way — modern applications that actually run their own login and want that login to be unified with other systems. The answer is a standard you've almost certainly heard of: OpenID Connect (OIDC).

This episode opens a new phase and Authelia's most underrated capability: Authelia as an OIDC provider. Besides guarding the door via forward authentication, Authelia can become an identity provider — the authority that proves a user's identity to other applications via the standard OAuth2/OIDC protocol.

An analogy: forward auth is like a guard at the door. OIDC is like a nationally standardized ID card — issued once by an official institution (Authelia), and accepted by every office (application) willing to check the card. You log in once, and every application trusts the same proof.

#What is OIDC in the Authelia Context

OpenID Connect is an identity layer on top of OAuth 2.0. OAuth 2.0 handles authorization — "this application may access that resource". OIDC adds authentication — "the user logging in is named this" — via an ID token containing claims.

When Authelia becomes an OIDC provider, its role changes from receiving verification requests to issuing identity proof:

• Authorization server — Authelia validates the login and MFA, then issues tokens.
• Client — the application requesting login from Authelia (Grafana, Nextcloud, Proxmox, and many more).
• Resource server — the destination application that verifies the token to prove the user's identity.

The big consequence: applications don't need to know anything about the Remote-User header format. They just need to follow the OIDC standard — and almost all modern applications understand that standard.

#Enabling OIDC in configuration.yml

OIDC doesn't turn on by itself; you enable it by defining the identity_providers.oidc block in configuration.yml:

identity_providers:
  oidc:
    hmac_secret: "very-long-random-hmac-secret"
    issuer_private_key: |
      -----BEGIN RSA PRIVATE KEY-----
      ...RSA private key for signing tokens...
      -----END RSA PRIVATE KEY-----

These two secrets determine the security of the whole system:

• hmac_secret — the key used to sign and validate authorization codes and tokens. Without this value, Authelia refuses to enable OIDC.
• issuer_private_key — the RSA private key that signs ID tokens. Its public key is published via the JWKS endpoint so applications can verify the signature. In modern versions, Authelia can generate this key automatically if not provided, but providing your own gives you full control over key rotation.

#Registering Clients

The core of OIDC configuration is the clients list — applications allowed to request login. An example for Grafana:

identity_providers:
  oidc:
    hmac_secret: "very-long-random-hmac-secret"
    clients:
      - id: grafana
        client_name: "Grafana"
        client_secret: "$pbkdf2-sha512$..."
        authorization_policy: two_factor
        redirect_uris:
          - "https://grafana.example.com/login/generic_oauth"
        scopes:
          - openid
          - profile
          - email
          - groups
        grant_types:
          - authorization_code
        response_types:
          - code

Let's break down each field:

• id — the client's unique identity. Applications refer to this value when starting the login flow; this is what the application calls client_id.
• client_name — the display name shown on the consent screen to users.
• client_secret — the client's "password", also stored as a hash (PBKDF2-SHA512), not plaintext. Generate the hash with authelia crypto hash generate pbkdf2 --variant sha512 --password 'client-secret'.
• authorization_policy — determines the required authentication strength: one_factor means password is enough, two_factor requires MFA. For sensitive applications, two_factor is the right choice.
• redirect_uris — the list of URLs allowed to receive the redirect after login. This is one of the anti-hijack mechanisms: if a redirect URL isn't in the list, Authelia refuses the login flow.
• scopes — the scope of claims that may be requested. openid is required (it marks this as an OIDC flow); profile, email, and groups carry identity and group membership.
• grant_types and response_types — the allowed protocol flows. authorization_code + code is the standard and safest combination for web applications.

#The Token Flow: From Redirect to Session

When a user presses the "log in with Authelia" button in Grafana, this is what happens:

1. Authorization request — Grafana redirects the user's browser to the Authelia endpoint /api/oidc/authorization with the client_id, redirect_uri, scope, and response_type=code.
2. Authentication — Authelia shows the portal. The user logs in (and completes MFA if authorization_policy: two_factor). Authelia asks for consent if needed.
3. Authorization code — Authelia redirects the browser back to the redirect_uri with a one-time authorization code.
4. Token exchange — Grafana (on the server side) exchanges that code at the /api/oidc/token endpoint, including the client_secret. Authelia replies with an access token, an ID token, and a refresh token.
5. UserInfo — Grafana can fetch additional claims from /api/oidc/userinfo, or read the ID token directly.
6. Session — from then on, the Grafana and Authelia logins are linked. Logging out of one can propagate to the other.

Other endpoints Authelia supports: /api/oidc/jwks (public keys to verify tokens), /api/oidc/introspection (server-side token validation), and /api/oidc/revocation (revoking tokens).

#OIDC Discovery

One of the things that makes integration so easy is discovery: applications don't need to be configured with each endpoint detail one by one. Authelia publishes its metadata at:

curl https://auth.example.com/.well-known/openid-configuration

This JSON document contains the issuer, the location of the authorization, token, userinfo, and jwks endpoints, and the list of supported scopes. In most modern applications, you just fill in the discovery URL (for example https://auth.example.com/.well-known/openid-configuration) along with client_id and client_secret — the application will find all the other endpoints itself.

#Configuring Token Lifespans

Authelia allows controlling the lifetime of each token type — an important security decision:

identity_providers:
  oidc:
    access_token_lifespan: "1h"
    authorize_code_lifespan: "1m"
    id_token_lifespan: "1h"
    refresh_token_lifespan: "90m"

The principle is the same as sessions in episode 7: the shorter, the smaller the window of misuse if a token leaks. Authorization codes are intentionally very short (one minute) because they only live between the redirect and the token exchange. Refresh tokens may be longer, but remember: a refresh token is the power to obtain new access tokens — don't let it live longer than needed.

#Closing

This episode turned Authelia from just a gateway into an identity provider: understanding the authorization server and client concepts in OIDC, enabling the identity_providers.oidc block with hmac_secret and issuer_private_key, registering clients with authorization_policy, redirect_uris, scopes, grant_types, and response_types, following the flow from authorization code to token exchange, and leveraging OIDC discovery for quick integration.

This capability completes Authelia's two faces: in front of the door via forward authentication, and behind the scenes via OIDC. In episode 18, we dive deeper into the claims tokens carry: OIDC scopes and claims — how user identity, email, and group membership are translated into claims that applications read. See you there!