Module auth

Authentication and Authorization Layer

This module implements the authentication and authorization middleware for the GC Hub REST API. For end-user setup and configuration guidance, see the user-facing documentation.

Architecture Overview

The authentication/authorization layer is implemented as a Tower middleware (AuthLayer) that intercepts all incoming HTTP requests before they reach endpoint handlers. This centralized approach ensures consistent security enforcement without scattering authentication/authorization logic across individual endpoints.

Request Lifecycle

1. Authentication Phase (AuthMiddleware::authenticated)

   • Passive checks: session cookie (AuthMiddleware::by_session), then API key (AuthMiddleware::by_api_key)
   • Active fallback: LDAP/Kerberos negotiation (AuthMiddleware::authenticate) if no passive auth succeeded
   • Result: UserID or authentication challenge (401)

2. Authorization Phase (AuthMiddleware::is_authorized)

   • HTTP method → Access type mapping
   • Resource pattern matching against user’s effective policies
   • Result: proceed (200-3xx) or forbidden (403)

3. Handler Execution

   • UserID injected into request extensions for use by endpoint handlers

Authentication Methods

The system supports three authentication mechanisms, checked in order of efficiency:

Session Cookie (session-id)

• Fastest check (simple cookie lookup)
• Set after successful login (basic auth) or LDAP/Kerberos negotiation
• No expiration currently implemented
• Implementation: AuthMiddleware::by_session

API Key Header (API_KEY)

• Header format: API_KEY: Bearer <opaque-key> (note: Bearer prefix is currently used but not standard)
• User-scoped, created via REST API
• No expiration currently implemented
• Implementation: AuthMiddleware::by_api_key

LDAP/Kerberos (SPNEGO)

• Multi-round negotiation using WWW-Authenticate: Negotiate (RFC 4559)
• Temporary spnego-id cookie tracks negotiation state across rounds
• On success: principal name extracted, LDAP groups queried, session created
• LDAP groups prefixed GC_ map to application roles (e.g., GC_Admin → Admin)
• Periodic role sync for managed users
• Implementation: AuthMiddleware::authenticate, ldap module, spnego_kerberos module

sequenceDiagram
    autonumber
    participant U as User
    participant M as Middleware
    participant L as LDAP Server
    participant D as User Database
    participant E as Endpoint

    %% Step 1 - Initial Request
    U->>M: Request access to protected endpoint

    %% Step 2 - Kerberos / SPNEGO Flow
    M->>M: Check Authorization header (Negotiate)
    M->>U: 401 Unauthorized (WWW-Authenticate: Negotiate)

    %% Step 3 - Client Responds with Token
    U->>M: Authorization: Negotiate <kerberos-token>
    M->>M: Validate Kerberos token
    M-->>U: 401 Unauthorized (WWW-Authenticate: Negotiate <token>, Set-Cookie: spnego-id)

    %% Step 4 - Negotiation Loop
    loop SPNEGO negotiation (RFC 4559)
        U->>M: Authorization: Negotiate <kerberos-token>
        M-->>U: 401 Unauthorized (WWW-Authenticate: Negotiate <token>)
    end

    %% Step 5 - LDAP Role Resolution
    M->>L: Query user security groups via LDAP (GC_* groups)
    L-->>M: Return security groups
    M->>M: Map security groups to internal roles

    %% Step 6 - Session Persistence
    M->>D: Store user principal with mapped roles
    D-->>M: Returns a session id

    %% Step 7 - Success
    M->>U: Set session cookie and redirect to original endpoint
    U->>M: Request same endpoint again
    M->>M: Validate the session cookie
    M->>E: Forward request to endpoint
    E-->>M: Endpoint response
    M-->>U: Return response

Authorization (RBAC)

Role-Based Access Control is enforced in AuthMiddleware::is_authorized.

Data Model

• Resource: URL path pattern with wildcards (* = one segment, ** = zero or more segments)
• Access Type: READ, WRITE, EXECUTE (from gc_config_db::db_user_management::Access)
• Policy: Named set of (resource pattern, allowed access types) pairs
• Role: Named set of policy references
• User: Has zero or more roles
  • Local users: role assignments via API
  • Managed LDAP users: roles from GC_* LDAP groups (immutable via API)

HTTP Method → Access Type Mapping

See Access::from_request for implementation.

Managed Users

Users authenticated via LDAP/Kerberos are “managed” users with special semantics:

• User ID format: ldap/<samAccountName> (provider namespace)
• Roles synchronized from LDAP groups (prefix GC_)
• Role assignments cannot be modified via API (enforced in user management endpoints)
• Periodic sync every 5 minutes (see LDAP_SYNC_INTERVAL_SECS in ldap module)

Implementation Notes

Constants

• SESSION_COOKIE_ID: - name of the session cookie
• API_KEY_HEADER: - name of the API key header
• SPNEGO_COOKIE_ID: - negotiation state cookie
• SEC_GROUPS_PREFIX: - LDAP group prefix for role mapping (case insensitive)
• LDAP_SYNC_INTERVAL_SECS: - interval for managed user role sync

Response Codes

• 401 Unauthorized: Authentication required or negotiation in progress
• 403 Forbidden: Authenticated but not authorized for resource

Database Integration

All user management operations are delegated to DBUserManagement.

Modules

auth_tower_layer 🔒

ldap 🔒

ldap_utils 🔒

spnego_kerberos 🔒

Structs

AuthLayer

Creates an AuthService that in turn manages a AuthMiddleware modules handles authentication and authorization.

AuthMiddleware

Authentication middleware This struct should holds all authentication methods.

LdapConfigBuilder

Builder for LDAP configuration If the search base DN is not set, it will be derived from the server FQDN. Keep in mind that only up, to two domain components will be used starting from the end of the FQDN. For example, for “host.subdomain.example.com”, the base DN will be “dc=example,dc=com”.

Constants

API_KEY_HEADER

LDAP_SYNC_INTERVAL_SECS

SEC_GROUPS_PREFIX

SESSION_COOKIE_ID

SPNEGO_COOKIE_ID

Functions

set_session_cookie