# 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`)
```ini
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`
```yaml
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:** 
   ```bash
   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:**
   ```bash
   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.