# Phase 2: knoe-auth as OIDC Provider

## Architecture
knoe-auth (the Authority) acts as the central Identity Authority for the cluster.

### OIDC Provider (OP)
- Issuer: `https://api.knoe.dev/auth`
- Endpoints:
  - `GET /.well-known/openid-configuration`: Discovery
  - `GET /jwks.json`: Public keys for token verification
  - `GET /authorize`: Authorization endpoint (supports `response_type=code`)
  - `POST /token`: Token exchange endpoint

### Upstream Identity (Google Workspace)
- knoe-auth acts as an OAuth client to Google.
- User flow: Service → knoe-auth → Google → knoe-auth → Service.
- Identity is mapped from Google `email` to internal `canonical user id`.

### Kerberos/SPNEGO Integration
- knoe-auth preserves Kerberos flows.
- If a user has a valid SPNEGO session, they can be transparently logged into the OIDC flow.
- Form login (Kerberos password) is available as a fallback.

## Identity Model
- **Canonical User ID**: Lowercase, stable identifier (e.g., `jdoe`).
- **Email**: User's Google Workspace email (e.g., `jdoe@knoey.com`).
- **Principal**: Kerberos principal (e.g., `jdoe@KNOE.DEV`).
- **Normalization**: `PrincipalNormalizer` ensures consistency across all auth methods.

## Namespace & Domains
- **Java Package**: `dev.knoe.authority.*`
- **Service DNS**: `knoe.dev` (e.g., `api.knoe.dev`, `git.knoe.dev`)
- **OIDC Issuer**: `https://api.knoe.dev/auth`
- **Identity Domain**: `knoey.com`
- **Kerberos Realm**: `KNOE.DEV`

## Token Model
### ID Token (JWT)
- Signed using RS256.
- Claims:
  - `iss`: `https://api.knoe.dev/auth`
  - `sub`: Canonical user ID
  - `email`: User's email
  - `preferred_username`: Canonical user ID
  - `aud`: Client ID
  - `exp`, `iat`, `nonce`

### Access Token
- Currently minimal (opaque or static) as the primary focus is identity (OIDC).

## Session Model
- Stateless where possible.
- Short-lived browser session via secure, HttpOnly, SameSite=Lax cookies.
- Authorization codes are short-lived and one-time use.

## Implementation Details
- Stack: Java / Spring Boot (Lightweight).
- Signing: RS256 with key rotation support (via multiple keys in JWKS).
- Configurable via `application.yml` and environment variables.

## Deployment & Configuration
- `KNOE_AUTH_OIDC_ENABLED`: Enable OIDC surface.
- `KNOE_AUTH_OIDC_ISSUER`: Issuer URL.
- `KNOE_AUTH_OIDC_SIGNING_KEY`: Base64 encoded private key (PKCS#8).
- `KNOE_AUTH_GOOGLE_CLIENT_ID`: Upstream Google client ID.
- `KNOE_AUTH_GOOGLE_CLIENT_SECRET`: Upstream Google client secret.

## GitLab Integration (Path B)
To switch GitLab to use knoe-auth as OIDC provider:
1. Update GitLab `omniauth` configuration.
2. Change `issuer` to `https://api.knoe.dev/auth`.
3. Update `client_id` and `client_secret` to match knoe-auth config.
4. Verify flow: GitLab → knoe-auth → Google → knoe-auth → GitLab.