mirror of
https://github.com/hanzoai/iam.git
synced 2026-11-19 18:37:16 +00:00
250 lines
13 KiB
Go
250 lines
13 KiB
Go
// Copyright 2026 Hanzo AI, Inc.
|
|
// SPDX-License-Identifier: MIT OR Apache-2.0
|
|
|
|
// Package oidc serves the IAM OpenID Connect / OAuth2 surface on zip. The
|
|
// handlers are RAW zip handlers (func(c *zip.Ctx) error), not typed generics,
|
|
// because the auth surface needs query params, form bodies, redirects, and
|
|
// headers a JSON-in/JSON-out handler can't reach.
|
|
//
|
|
// The surface is the canonical hanzo.id contract, unchanged across the v1→v2
|
|
// backend swap: discovery + JWKS under .well-known, the oauth/{authorize,token,
|
|
// userinfo,logout} endpoints, and the native {get-app-login, auth/methods,
|
|
// login} the hosted UI calls. Tokens are signed JWTs (RS256 interop, ES/ML-DSA
|
|
// behind the same JWKS); every value is verified, never trusted.
|
|
package oidc
|
|
|
|
import (
|
|
"net/http"
|
|
|
|
"github.com/hanzoai/orm"
|
|
"github.com/zap-proto/zip"
|
|
)
|
|
|
|
// Canonical OIDC paths — the single source of truth the @hanzo/iam SDK and every
|
|
// existing relying party hard-code. iam serves them directly; the transition
|
|
// off v1 is a backend swap behind the same paths, never a parallel version.
|
|
const (
|
|
PathAuthorize = "/v1/iam/oauth/authorize"
|
|
PathToken = "/v1/iam/oauth/token"
|
|
PathUserInfo = "/v1/iam/oauth/userinfo"
|
|
PathLogout = "/v1/iam/oauth/logout"
|
|
PathJWKS = "/v1/iam/.well-known/jwks"
|
|
PathJWKSRoot = "/.well-known/jwks"
|
|
// PathDelegationKeys serves the public half of the delegation key to a client
|
|
// allowed to delegate, and to nobody else (delegate.go).
|
|
PathDelegationKeys = "/v1/iam/oauth/delegation/keys"
|
|
PathDiscovery = "/.well-known/openid-configuration"
|
|
PathDiscoveryV1 = "/v1/iam/.well-known/openid-configuration"
|
|
PathASMetadata = "/.well-known/oauth-authorization-server" // RFC 8414 (root)
|
|
PathASMetadataV1 = "/v1/iam/.well-known/oauth-authorization-server" // RFC 8414 (v1)
|
|
PathDevice = "/v1/iam/oauth/device" // RFC 8628 device authorization
|
|
// PathDeviceInfo names the application a pending user_code belongs to — what
|
|
// the approval page must show a human before they authorize it.
|
|
PathDeviceInfo = "/v1/iam/oauth/device/info"
|
|
// PathDeviceVerify is the user-facing device-approval PAGE (a route in the
|
|
// hosted SPA, on the application's sign-in origin: verificationOrigin), not an
|
|
// API path: RFC 8628's verification_uri is somewhere a human opens and signs
|
|
// in, which the JSON token API can never be.
|
|
PathDeviceVerify = "/login/oauth/device"
|
|
// PathAgentIdentity is where an agent registers to act for a person (WorkOS
|
|
// auth.md `agent_auth.identity_endpoint`, agent.go). Under the OAuth subtree
|
|
// because it is a protocol endpoint named by that profile, like token or device.
|
|
PathAgentIdentity = "/v1/iam/oauth/agent/identity"
|
|
)
|
|
|
|
// CodeLoginRequired is the STABLE machine-readable reason for "this needs a
|
|
// signed-in session and there isn't one". The human `msg` beside it is prose and
|
|
// several causes share it; a caller that must ROUTE on the cause — the device
|
|
// approval page deciding to show a sign-in form rather than an error — cannot
|
|
// parse prose.
|
|
//
|
|
// It exists because the alternative was a lie: an unauthenticated device approval
|
|
// used to fall through to the credential check and answer "organization, username
|
|
// and password are required", naming three fields that page has never rendered and
|
|
// never sends. An error must describe the thing the caller can actually do.
|
|
const CodeLoginRequired = "login_required"
|
|
|
|
// CodeAccountSelectionRequired is the `code` beside a session sign-in refused
|
|
// because several people are signed in on this browser and the request named none
|
|
// of them, or asked the person to choose (prompt=select_account): the page shows
|
|
// its account chooser and posts again naming the one picked (loginHint).
|
|
const CodeAccountSelectionRequired = "account_selection_required"
|
|
|
|
// CodeAccountNotPermitted is the `code` beside a sign-in refused because the
|
|
// account itself may not sign in — archived by an operator (isForbidden) or
|
|
// deleted — after its credential was proven. The client says the account is
|
|
// archived rather than reading it as a wrong password or a failed exchange.
|
|
const CodeAccountNotPermitted = "account_not_permitted"
|
|
|
|
// PathRefreshToken is the spelling signed-in clients POST their refresh to. It is
|
|
// the SAME handler as PathToken at a second address — grant_type=refresh_token
|
|
// travels in the body, so this is a second spelling of the endpoint, never a
|
|
// separate grant. Discovery advertises only PathToken.
|
|
//
|
|
// It is registered because callers hold it: refreshes arrive here continuously,
|
|
// and serving them anywhere else logs every signed-in session out. It is the only
|
|
// legacy token spelling kept — the Casdoor-era `access_token` path and the
|
|
// `/v1/iam/userinfo` spelling draw no traffic, so neither is registered.
|
|
const PathRefreshToken = "/v1/iam/oauth/refresh_token"
|
|
|
|
// Route registers the entire OIDC/OAuth2 surface on r, backed by db. This is the
|
|
//go:generate go run github.com/zap-proto/zip/cmd/zipdoc
|
|
|
|
// one entry point the route table calls — discovery, JWKS, the protocol
|
|
// endpoints, and the native surface are all bound here so it all lives in one
|
|
// place. r is the PUBLIC group (registered before the router's authentication
|
|
// Guard): the whole OIDC/OAuth + native surface is pre-authentication by
|
|
// construction, so membership in this group IS what makes it reachable without a
|
|
// bearer — there is no separate allow-list to keep in sync.
|
|
func Route(r *zip.Group, db orm.DB) {
|
|
// Discovery and the JWKS are each served at BOTH the root well-known path
|
|
// (RFC 8414 §3, where a bare-origin client and the gateway's default look)
|
|
// and the /v1/iam-prefixed path, matching the live hanzo.id surface. Both
|
|
// paths are the same handler over the same keys — one key set, two spellings
|
|
// of where to find it.
|
|
r.Raw(http.MethodGet, PathDiscovery, Discovery)
|
|
r.Raw(http.MethodGet, PathDiscoveryV1, Discovery)
|
|
// RFC 8414 OAuth Authorization Server Metadata — the same self-consistent
|
|
// document at the OAuth well-known path (a superset serves it), so an OAuth-only
|
|
// client that looks for `oauth-authorization-server` finds the AS too.
|
|
r.Raw(http.MethodGet, PathASMetadata, Discovery)
|
|
r.Raw(http.MethodGet, PathASMetadataV1, Discovery)
|
|
// One handler, two addresses: the same key set under the subsystem's prefix
|
|
// and at the host root, because a relying party configured with either must
|
|
// find it.
|
|
r.Raw(http.MethodGet, PathJWKS, jwksHandler(db))
|
|
r.Raw(http.MethodGet, PathJWKSRoot, jwksHandler(db))
|
|
// The delegation key, which the set above never carries: served only to a
|
|
// client allowed to delegate (delegate.go).
|
|
r.Raw(http.MethodGet, PathDelegationKeys, delegationKeysHandler(db))
|
|
|
|
// OAuth2 / OIDC protocol endpoints.
|
|
r.Raw(http.MethodGet, PathAuthorize, authorizeHandler(db))
|
|
r.Raw(http.MethodPost, PathAuthorize, authorizeHandler(db))
|
|
r.Raw(http.MethodGet, PathUserInfo, userinfoHandler(db))
|
|
r.Raw(http.MethodPost, PathUserInfo, userinfoHandler(db))
|
|
r.Raw(http.MethodGet, PathLogout, logoutHandler(db))
|
|
r.Raw(http.MethodPost, PathLogout, logoutHandler(db))
|
|
|
|
// The token endpoint, the credential login that mints codes, and the
|
|
// read-only endpoints the hosted <Login> self-configures from.
|
|
routeToken(r.Group(""), db)
|
|
routeLogin(r.Group(""), db)
|
|
routeFrontDoor(r, db)
|
|
|
|
// The two WebAuthn ceremonies: enroll a passkey, and sign in with one. Both
|
|
// are public — a passkey sign-in has no bearer to present, and the enrollment
|
|
// pair authenticates itself from the portal's session cookie.
|
|
routeWebauthn(r.Group(""), db)
|
|
|
|
// Identity federation: the external-IdP callback (Google/GitHub, …). The
|
|
// authorize endpoint kicks a federation off when the request names a
|
|
// `provider`; this registers the fixed return endpoint the IdP redirects to.
|
|
routeFederation(r.Group(""), db)
|
|
routeFederationMfa(r.Group(""), db)
|
|
// The two halves of the linking law: connect a provider to the account you
|
|
// already hold, and disconnect one.
|
|
routeLink(r.Group(""), db)
|
|
routeUnlink(r.Group(""), db)
|
|
|
|
// RFC 7662 introspection + RFC 7009 revocation — the standard token-management
|
|
// endpoints a resource server / confidential client uses (client-authenticated).
|
|
routeIntrospectRevoke(r.Group(""), db)
|
|
|
|
// RFC 8628 device authorization grant — the browserless CLI sign-in. The
|
|
// request endpoint is registered here; the poll rides the token endpoint and
|
|
// the approval rides the login endpoint, both already public above.
|
|
routeDevice(r.Group(""), db)
|
|
|
|
// Agent registration (WorkOS auth.md, service_auth only): an agent names the
|
|
// person it acts for, that person approves on the device page above, and the
|
|
// agent's poll and its later exchanges ride the token endpoint (agent.go).
|
|
routeAgent(r.Group(""), db)
|
|
|
|
// The confidential-client "act on behalf of a user" primitive (the console +
|
|
// keyless-AI proxies mint their forwarded bearer here). Authenticates the
|
|
// client itself, so it is not Bearer-gated.
|
|
routeIssueToken(r.Group(""), db)
|
|
|
|
// RFC 7591 dynamic client registration, for a deployment that turned it on
|
|
// (IAM_REGISTRATION): how an MCP client that holds no client_id gets one.
|
|
routeRegister(r.Group(""), db)
|
|
}
|
|
|
|
// Discovery returns the OpenID Connect discovery document — the one URL you
|
|
// point a standards-compliant client at so it can find every other endpoint on
|
|
// its own, instead of you configuring them by hand.
|
|
//
|
|
// It advertises only what is actually implemented, so a client that reads it
|
|
// cannot ask for a flow that will fail: the authorization-code flow, PKCE with
|
|
// S256, the supported grants, and the signing algorithms whose public keys the
|
|
// JWKS really publishes.
|
|
//
|
|
// The issuer is derived from the host you asked on and is the same value the
|
|
// tokens carry, so a client that pins the issuer never sees it change.
|
|
func Discovery(c *zip.Ctx) error {
|
|
iss, err := tokenIssuer(c)
|
|
if err != nil {
|
|
return c.JSON(503, map[string]string{"error": "temporarily_unavailable", "error_description": "this server has no issuer configured"})
|
|
}
|
|
// The document is fixed per host: the issuer comes from the trusted request
|
|
// host (part of every cache key), and nothing in it rotates — keys rotate in
|
|
// the JWKS, which keeps its own shorter lifetime. A sign-in page fetches this
|
|
// when a provider button is pressed, so a cached copy takes a round trip off
|
|
// every press.
|
|
c.SetHeader("Cache-Control", "public, max-age=3600")
|
|
doc := map[string]any{
|
|
"issuer": iss,
|
|
"authorization_endpoint": iss + PathAuthorize,
|
|
"token_endpoint": iss + PathToken,
|
|
"userinfo_endpoint": iss + PathUserInfo,
|
|
"introspection_endpoint": iss + PathIntrospect,
|
|
"revocation_endpoint": iss + PathRevoke,
|
|
"end_session_endpoint": iss + PathLogout,
|
|
"device_authorization_endpoint": iss + PathDevice,
|
|
"jwks_uri": iss + PathJWKS,
|
|
"response_types_supported": []string{"code"},
|
|
"response_modes_supported": []string{"query", "fragment", "form_post"},
|
|
"grant_types_supported": grantsSupported(iss),
|
|
// The sign-in modes a client may ask for. Advertised because a relying
|
|
// party CANNOT discover them by trying: a server that ignores prompt=none
|
|
// answers with a login page, which to the client is indistinguishable from
|
|
// a server that honoured it and found no session. Saying so here is what
|
|
// lets a client rely on the silent flow instead of guessing.
|
|
//
|
|
// `consent` is absent because there is no consent screen to show, and
|
|
// `create` because there is no signup-first mode on this endpoint. This
|
|
// document advertises only what is implemented.
|
|
"prompt_values_supported": promptValues,
|
|
"subject_types_supported": []string{"public"},
|
|
"id_token_signing_alg_values_supported": []string{"RS256", "RS512", "ES256", "ES384", "ES512", "MLDSA65"},
|
|
"scopes_supported": []string{"openid", "email", "profile", "address", "phone", "offline_access"},
|
|
"token_endpoint_auth_methods_supported": []string{"client_secret_basic", "client_secret_post", "none"},
|
|
"code_challenge_methods_supported": []string{"S256"},
|
|
"claims_supported": []string{
|
|
"iss", "sub", "aud", "iat", "exp", "nbf", "jti", "nonce", "azp", "act", "imp",
|
|
"owner", "organization", "scope", "tokenType",
|
|
// `name` and `preferred_username` are both the USERNAME here; the human's
|
|
// name is `displayName`. Advertising a claim nothing emits is what left
|
|
// consumers reading `name` as a display name for a year, so the list says
|
|
// exactly what a token carries.
|
|
"name", "preferred_username", "displayName", "email", "email_verified",
|
|
"picture", "address", "phone", "groups", "is_verified",
|
|
// The on-chain half of the same identity: the wallets this person
|
|
// proved control of, and the identifier derived from `sub`.
|
|
"wallets", "did",
|
|
},
|
|
}
|
|
// Advertised only where the endpoint is served: a client that reads it asks for
|
|
// a client_id there, and a 404 would be its answer.
|
|
if registration.Load() != nil {
|
|
doc["registration_endpoint"] = iss + PathRegister
|
|
}
|
|
// The auth.md bootstrap block, only where this issuer offers agent registration
|
|
// and only what is implemented (agentAuthMetadata).
|
|
if block := agentAuthMetadata(iss); block != nil {
|
|
doc["agent_auth"] = block
|
|
}
|
|
return c.JSON(200, doc)
|
|
}
|