chrisfu/prole
1
0
Fork 0
mirror of https://github.com/dredx/prole.git synced 2026-09-23 12:03:59 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity
6d484ef13e
prole/docs/knoe-auth-phase-2.md
chrisfu 9daa94b860 refactor(authority): rebrand package org.prole → dev.knoe; raise test coverage to 50% 
- Move all 31 Java files from org/prole/authority to dev/knoe/authority
- Update all package declarations, imports, pom.xml groupId, and docs
- Add 11 new test classes (PrincipalNormalizerTest, OidcCodeServiceTest, KadminClientTest, TotpServiceTest, HealthControllerTest, EnrollValueTypesTest, KerberosSpnegoResultTest, SessionServiceTest, EnrollmentControllerTest, AdminControllerTest, LoginControllerTest)
- Add JaCoCo 0.8.12 + maven-surefire-plugin with Java 25 / Byte Buddy compat flags
- Fix LoginController CSS format string bug (100% -> 100%%)
- Result: 96 tests, 0 failures; 50.2% line / 46.5% instruction / 37.1% branch coverage

Co-authored-by: Junie <junie@jetbrains.com>
2026-04-30 22:42:53 -07:00

2.8 KiB
Raw Blame History

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.