---
title: Authentication
---

# 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](./overview).

See also the [Pharos AAI Architecture](https://docs.google.com/document/d/1uCtNpVdVDI9DJbG0FpTDbFpbpBl-dv_NWAnT4lwP7rY/edit?pli=1&tab=t.0#heading=h.mqvai74mmir9) 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](https://rciam.github.io/rciam-docs/) (also known as [RCIAM](../../terms/rciam)). This system proxies institutional identity providers including [MyAccessID](../../terms/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.

```mermaid
sequenceDiagram
    autonumber
    actor User
    participant Web as Themelio Web (NextAuth)
    participant IDP as Pharos AAI (OIDC)
    participant GitLab as GitLab API
    participant Valkey as Valkey Store
    participant Cookie as Browser Cookie

    Note over User, IDP: Authentication Phase
    User->>Web: Click Sign In
    Web->>IDP: Redirect to Login (Scope: openid, email, profile...)
    IDP->>User: Prompt for Credentials
    User->>IDP: Authenticate
    IDP->>Web: Callback with Authorization Code
    Web->>IDP: Exchange Code for Tokens
    IDP-->>Web: ID Token & Access Token

    Note over Web, Valkey: signIn Callback (Provisioning)
    Web->>Web: signIn({ profile, account })
    Web->>GitLab: ensureInitializedUser(username, email, sub)
    GitLab-->>Web: gitlabUser Object
    Web->>GitLab: createImpersonationToken(gitlabUser)
    GitLab-->>Web: impersonationToken
    Web->>Valkey: createValkeySession(impersonationToken)
    Valkey-->>Web: sessionId
    Web->>Cookie: setSessionCookie(sessionId)

    Note over Web, Cookie: JWT & Session Callbacks
    Web->>Web: jwt() callback (strips accessToken for size)
    Web->>Web: session() callback (maps sub to user.id)
    Web-->>User: Authentication Successful

    Note over User, GitLab: Sign Out Phase (Events)
    User->>Web: Click Sign Out
    Web->>Cookie: deleteSessionCookie()
    Web->>Valkey: deleteValkeySession(sessionId)
    Valkey-->>Web: returns impersonationToken
    Web->>GitLab: deleteImpersonationToken(impersonationToken)
    Web-->>User: Signed Out
```

### 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](./gitlab-groups-and-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