prole/docs/oidc-path-b.md

knoe-auth Path B — OIDC Provider Implementation

This document outlines the design and implementation of Path B for knoe authentication: GitLab → knoe-auth (OIDC OP) → Google Workspace.

Overview

In Path B, knoe-auth (running at api.knoe.dev/auth) acts as an OpenID Connect Provider (OP). GitLab (the Relying Party, RP) is configured to trust knoe-auth as its identity issuer.

Motivation

• Unified Identity: Consolidates Kerberos/SPNEGO and Google Workspace identities.
• Protocol Translation: Allows legacy or internal apps to use OIDC while maintaining Kerberos support.
• Extensibility: Provides a single point to inject additional auth factors or logic before reaching the end application.

Endpoints to Implement

Endpoint	Path	Description
Discovery	/.well-known/openid-configuration	Returns OIDC metadata.
JWKS	/jwks	Serves public keys for token verification.
Authorize	/authorize	Initiates the auth flow. Redirects to Google if no session exists.
Token	/token	Exchanges authorization codes for ID/Access/Refresh tokens.
UserInfo	/userinfo	(Optional but recommended) Returns user claims.
Callback	/callback/google	Receives the redirect from Google Workspace.

Data Mapping

User Identification

knoe-auth must normalize identities to a consistent sub (subject) claim.

• Kerberos: user@REALM → user (via PrincipalNormalizer)
• Google: user@knoey.com → user (assuming knoey.com is the primary domain)

GitLab will receive sub: user and JIT-create/map the user accordingly.

State Management

• Authorization Codes: Short-lived, stored in memory or DB (PostgreSQL).
• Sessions: knoe-auth already uses a knoe_session cookie. The OIDC flow will leverage this session.

Configuration (Path B)

GitLab omni_auth (in conf/gke.cfg)

GITLAB_OIDC_ISSUER = https://api.knoe.dev/auth
GITLAB_OIDC_CLIENT_ID = <knoe-auth-client-id>
GITLAB_OIDC_CLIENT_SECRET = <knoe-auth-client-secret>

knoe-auth application.yml

knoe:
  auth:
    oidc:
      enabled: true
      issuer: https://api.knoe.dev/auth
      # RSA key for signing JWTs
      signingKey: ${KNOE_AUTH_OIDC_SIGNING_KEY}

Implementation Plan

1. JWK Management: Generate or load an RSA key pair for JWT signing.
2. Discovery Endpoint: Hardcoded JSON returning the implemented endpoints and supported claims/scopes.
3. Authorize Logic:
   • Validate client_id, redirect_uri, state.
   • Check for knoe_session.
   • If missing, redirect to /login (which redirects to Google).
   • If present, generate an auth code, associate it with the session, and redirect back to GitLab.
4. Token Logic:
   • Validate auth code.
   • Generate JWT signed with the private key.
   • Include sub, email, preferred_username claims.
5. Secret Handling: Update etc/init_gitlab.sh and etc/init_knoe_auth.sh to handle the new client credentials and signing keys.

Verification Steps

To verify Path B is working correctly:

1. Discovery:

   curl -s https://api.knoe.dev/auth/.well-known/openid-configuration | jq .
   

   Should return JSON with issuer: "https://api.knoe.dev/auth" and other OIDC endpoints.

2. JWKS:

   curl -s https://api.knoe.dev/auth/jwks | jq .
   

   Should return an RSA public key in JWKS format.

3. GitLab Redirect: Visit https://git.knoe.dev/users/sign_in. Click on the "OpenID Connect" button.

   • You should be redirected to https://api.knoe.dev/auth/authorize?....
   • If not logged in, you should be redirected to https://api.knoe.dev/auth/login.
   • Click "Login with Google". After Google authentication, you should be redirected back to knoe-auth and then to GitLab.

4. GitLab Login: After the flow, you should be logged into GitLab as your Google Workspace user. Verify in GitLab profile that the email matches.