For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt, and this page is available as Markdown at /product/architecture/authentication.md.

Themelio compatibility reference. This page describes the retained Themelio implementation or its historical design. Check the parallel-operation guide before applying it to the current platform.

Authentication

This page covers how Themelio handles authentication — identity providers, the login and logout flow, token lifecycle, and session management.

For a broader view of how authentication fits into the system, see the Architecture Overview.

See also the Pharos AAI Architecture for a deep dive into the authentication and authorization layer.

Identity Providers

Themelio authenticates users via OpenID Connect (OIDC). The available providers depend on the environment:

GRNET e-Infra Service Registry (Production)

The primary production provider is the GRNET e-Infra Service Registry (also known as RCIAM). This system proxies institutional identity providers including MyAccessID, an Identity and Access Management Service provided by GEANT that offers a common Identity Layer for Infrastructure Service Domains.

Users authenticate with their institutional credentials — no platform-specific password is required.

Other Providers

Additional OIDC providers (e.g., Google, eIDAS) may be configured for specific environments or development purposes.

Authentication Flow

Authentication is handled by NextAuth v5 with an OIDC provider. The flow provisions GitLab access on login and cleans up on logout.

Key Steps

  1. OIDC Authentication: User authenticates with their identity provider (RCIAM, institutional IdP). NextAuth handles the OIDC dance (redirect → credentials → authorization code → token exchange).

  2. User Provisioning: On successful authentication, gitlab-root-actor ensures the user exists in GitLab (ensureInitializedUser) — creating the account and group structure if needed (see GitLab Groups & Visibility).

    Warning

    User provisioning is likely to change — GitLab users may be provisioned through a site agent instead of gitlab-root-actor.

  3. Impersonation Token: A GitLab impersonation token is created for the user via gitlab-root-actor. This token allows Themelio Web to make GitLab API calls on behalf of the user.

  4. Session Storage: The impersonation token is stored in Valkey, keyed by a session ID. The session ID is set as a browser cookie.

  5. Request Authentication: The Next.js middleware (services/web/src/middleware.ts) intercepts API requests, retrieves the impersonation token from Valkey using the session cookie, and injects it as a PRIVATE-TOKEN header for downstream GitLab API calls.

  6. Logout Cleanup: On sign-out, the session is deleted from Valkey and the impersonation token is revoked from GitLab — ensuring no stale credentials remain.

Token Lifecycle

Impersonation Tokens

  • Created: On every login, by gitlab-root-actor
  • Stored: In Valkey, associated with the user's session ID
  • Used: Injected by middleware into every authenticated API request
  • Deleted: On logout (both from Valkey and from GitLab)

Impersonation tokens are never exposed to the browser. The browser only holds a session cookie that maps to the token in Valkey.

Personal Access Tokens

Users can create Personal Access Tokens (PATs) for git operations over HTTPS. These are managed through Themelio Web UI and stored by GitLab directly. PATs are the recommended way for users to perform git push and similar operations without SSH key setup.

GitLab Root Access

Direct GitLab sign-in (gitlab.<your-domain>/users/sign_in) is restricted to VPN or whitelisted IPs. This provides admin panel access for operational tasks — user management, impersonation, and GitLab internals inspection — without exposing it to end users.

Architecture Decisions

  • NextAuth v5 over direct OIDC: Provides session management, JWT handling, and provider abstraction out of the box
  • Valkey sessions over JWT-only: Allows server-side token revocation on logout; avoids exposing GitLab tokens in browser-accessible JWTs
  • Impersonation tokens over OAuth delegation: GitLab CE doesn't support fine-grained OAuth scopes; impersonation tokens provide full API access scoped to the user
  • Middleware injection over client-side tokens: Centralizes authentication logic, prevents token leakage, enables audit logging
Page source

Source snapshot · Revision f928834c8.