Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
93 changes: 89 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -405,6 +405,83 @@ services, and a token issued for the expense tool would otherwise be a valid
credential here. The user is real, the token is real, and they never intended to
authenticate against this.

### Signing in

```bash
modelforgectl login
# to sign in, visit:
#
# https://idp.example.com/authorize?...
#
# opening your browser at https://idp.example.com...
# signed in as sahil@example.com (admin)
# this session expires at 2026-08-31T20:34:32Z

modelforgectl whoami
# sahil@example.com (user)
# scopes admin
# subject sub-sahil
# issuer https://idp.example.com
# expires 2026-08-31T20:34:32Z
```

The credential is stored at `~/.config/modelforge/credential`, mode 0600 in a
0700 directory — both set explicitly rather than left to the umask, since a
umask of 022 leaves a readable credential in a home directory other accounts on
the machine can list. An existing directory is tightened rather than trusted,
because `MkdirAll` leaves the mode of one that already exists alone.
`MODELFORGE_TOKEN` still wins if set, so a script can override whoever happens
to be signed in on the machine it runs on.

`--no-browser` prints the URL and waits, for a headless box, a remote shell, or
anyone who would rather paste a URL into a browser they trust than have a
process launch one.

**This is the RFC 8252 native-application flow**, and its shape is dictated by
what a command-line tool can safely do:

- **No client secret.** One shipped inside a binary is a string every user can
read out of it. The client is public and **PKCE** takes the secret's place —
the test provider recomputes the challenge from the verifier and refuses a
mismatch, so the CLI cannot ship without it and still pass.
- **`state` on every request**, checked before the code is touched. Without it
anybody who can make your browser load a URL can complete a login of their
choosing, and you end up holding *their* session.
- **`nonce` bound to the login**, so a token captured from somewhere else cannot
be replayed into it.
- **Redirect to `127.0.0.1`, not `localhost`.** `localhost` resolves through
DNS, and a hostile resolver points it elsewhere — at which point the
authorization code is delivered to somebody else's machine. The literal
address cannot be redirected. The port is ephemeral, which RFC 8252 requires
providers to accept for exactly this reason.
- **The callback page interpolates nothing.** A provider's `error_description`
reflected into it would be cross-site scripting on a page that has just
handled an authorization code.

The server advertises where to sign in at `GET /v1/auth/config`, which is
deliberately unauthenticated: a client cannot present a credential before it
knows where to obtain one, and every value there is visible to anybody watching
a browser perform a login.

`logout` deletes the local file and says plainly that this is **not**
revocation — the token stays valid at the provider until it expires.

### A bug worth recording

The first version left `Endpoint.AuthStyle` unset. `x/oauth2` then probes for
the server's preferred client-authentication style: it tries one, and if that
is rejected, retries with the other.

An authorization code is single-use. So the probe **burns the code**, and the
error you see is the *second* attempt's `invalid_grant` — which points at the
code, when the real problem was whatever made the first request fail. I spent a
while chasing a phantom double-exchange because of it.

Setting `AuthStyleInParams` explicitly is both correct — RFC 6749 says a public
client sends its id in the body, having no secret for a Basic header — and
removes the failure mode. Verified: one token request per login, where there
had been two.

### Why a library for the JWT part

I wrote the XGBoost scorer rather than binding to libxgboost, and did not write
Expand Down Expand Up @@ -541,7 +618,7 @@ and a fake agrees with whatever the code happens to do.
same database and truncate it between cases, so running packages concurrently
has them resetting the database underneath each other.

Coverage is **91.7%** of `internal/`, measured with `-coverpkg` so that code is
Coverage is **90.9%** of `internal/`, measured with `-coverpkg` so that code is
attributed to the package that owns it rather than the package running the test
— without it the end-to-end suites, which exercise serving and routing through
HTTP, would report those packages as untested.
Expand Down Expand Up @@ -570,6 +647,9 @@ fail silently:
| `TestUnsignedTokenIsRejected` | the `alg:none` bypass |
| `TestWrongAudienceIsRejected` | a token minted for another service working here |
| `TestAuthenticatedButNotAuthorised` | a valid login becoming access by default |
| `TestPKCEIsActuallySent` | a login flow shipping without PKCE |
| `TestCallbackRejectsAForgedState` | a forged callback completing somebody else's login |
| `TestStoredCredentialIsPrivate` | a world-readable credential in a home directory |

## Known limitations

Expand All @@ -589,9 +669,14 @@ I would rather write these down than let someone discover them.
- **The rollout guard reacts to errors, not to quality.** It catches a version
that is throwing, not one that is quietly predicting badly — that needs
labels, which arrive long after the request.
- **There is no login flow.** The server verifies a JWT somebody already holds;
obtaining one is the identity provider's job. That is the right split, but it
means a browser hitting this API directly gets a 401 rather than a redirect.
- **The login flow is for a terminal, not a browser session.** `modelforgectl
login` gets a person a credential; the server itself has no cookies and no
sign-in page, so a browser pointed straight at the API gets a 401 rather than
a redirect. Adding sessions would mean cookie handling and CSRF defence for
the sake of an API with no UI in front of it.
- **There is no refresh.** When the token expires you log in again. Storing a
refresh token on disk is a longer-lived secret than the one it replaces, and
the sessions here are hours rather than minutes.
- **Static-token revocation is as fast as the reload.** A withdrawn token stops
working on the next `SIGHUP` or within the poll interval, not instantly across
a fleet. OIDC logins do not have this problem — they expire on their own.
Expand Down
2 changes: 2 additions & 0 deletions cmd/modelforge/main.go
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,8 @@ func main() {
"identity provider URL, enabling per-user login alongside static tokens")
flag.StringVar(&cfg.OIDCAudience, "oidc-audience", os.Getenv("MODELFORGE_OIDC_AUDIENCE"),
"value a token's aud claim must contain; required with -oidc-issuer")
flag.StringVar(&cfg.OIDCClientID, "oidc-client-id", os.Getenv("MODELFORGE_OIDC_CLIENT_ID"),
"public OAuth client id the CLI logs in as; enables `modelforgectl login`")
flag.StringVar(&cfg.OIDCGroupsClaim, "oidc-groups-claim", envOr("MODELFORGE_OIDC_GROUPS_CLAIM", "groups"),
"claim carrying group membership")
scopeMap := flag.String("oidc-scope-map", os.Getenv("MODELFORGE_OIDC_SCOPE_MAP"),
Expand Down
68 changes: 68 additions & 0 deletions internal/api/api.go
Original file line number Diff line number Diff line change
Expand Up @@ -99,6 +99,16 @@ func NewServer(deps Deps) *Server {
s.mux.Handle(pattern, mw.RequireFunc(auth.ScopeAdmin, h))
}

// Who am I. Requires only that the caller authenticated at all, so any
// valid credential can ask; the answer is about the caller and reveals
// nothing they do not already hold.
s.mux.Handle("GET /v1/auth/whoami", mw.RequireFunc(auth.ScopePredict, s.handleWhoAmI))

// Login metadata, deliberately unauthenticated: a client cannot present a
// credential before it knows where to obtain one, and every value here is
// visible to anybody who watches a browser perform a login.
s.mux.HandleFunc("GET /v1/auth/config", s.handleAuthConfig)

// Operations. Deliberately unauthenticated.
//
// A liveness probe that needs a credential is a probe that starts failing
Expand Down Expand Up @@ -558,6 +568,64 @@ func (s *Server) handleReady(w http.ResponseWriter, r *http.Request) {
writeJSON(w, http.StatusOK, map[string]any{"status": "ok", "loaded": len(loaded)})
}

// WhoAmIResponse describes the caller.
type WhoAmIResponse struct {
Name string `json:"name"`
Kind string `json:"kind"`
Scopes []auth.Scope `json:"scopes"`
Subject string `json:"subject,omitempty"`
Issuer string `json:"issuer,omitempty"`
Email string `json:"email,omitempty"`
Expires string `json:"expires,omitempty"`
}

// handleWhoAmI reports the identity behind the current credential.
//
// It exists because "am I logged in, as whom, and with what access" is the
// first question anybody asks when a request is refused, and answering it by
// decoding a JWT locally would report what the token claims rather than what
// this server accepts — which is precisely the thing in doubt.
func (s *Server) handleWhoAmI(w http.ResponseWriter, r *http.Request) {
tok, ok := auth.FromContext(r.Context())
if !ok {
writeError(w, http.StatusInternalServerError, errors.New("no identity on the request"))
return
}

kind := "service"
if tok.Human() {
kind = "user"
}
resp := WhoAmIResponse{
Name: tok.Name, Kind: kind, Scopes: tok.Scopes,
Subject: tok.Subject, Issuer: tok.Issuer, Email: tok.Email,
}
if !tok.NotAfter.IsZero() {
resp.Expires = tok.NotAfter.UTC().Format(time.RFC3339)
}
writeJSON(w, http.StatusOK, resp)
}

// handleAuthConfig advertises where to log in.
func (s *Server) handleAuthConfig(w http.ResponseWriter, r *http.Request) {
if s.deps.Auth.IsDisabled() {
writeJSON(w, http.StatusOK, map[string]any{"login": false, "reason": "authentication is disabled"})
return
}
v := s.deps.Auth.OIDC()
if v == nil || !v.LoginEnabled() {
writeJSON(w, http.StatusOK, map[string]any{
"login": false,
"reason": "this server has no identity provider configured for interactive login",
})
return
}
cfg := v.PublicConfig()
writeJSON(w, http.StatusOK, map[string]any{
"login": true, "issuer": cfg.Issuer, "client_id": cfg.ClientID, "audience": cfg.Audience,
})
}

// --- helpers ---

func modelVersion(r *http.Request) (string, int, error) {
Expand Down
6 changes: 6 additions & 0 deletions internal/app/app.go
Original file line number Diff line number Diff line change
Expand Up @@ -78,6 +78,11 @@ type Config struct {
// other service would authenticate here.
OIDCAudience string

// OIDCClientID is the public OAuth client the CLI logs in as. Without it
// tokens can still be verified, but nobody can obtain one through this
// server.
OIDCClientID string

// OIDCGroupsClaim names the claim carrying group membership.
OIDCGroupsClaim string

Expand Down Expand Up @@ -333,6 +338,7 @@ func buildAuth(ctx context.Context, cfg Config) (*auth.Authenticator, *auth.OIDC
verifier, err = auth.NewOIDCVerifier(ctx, auth.OIDCConfig{
Issuer: cfg.OIDCIssuer,
Audience: cfg.OIDCAudience,
ClientID: cfg.OIDCClientID,
GroupsClaim: cfg.OIDCGroupsClaim,
ScopeMap: scopeMap,
}, cfg.Logger)
Expand Down
3 changes: 3 additions & 0 deletions internal/auth/auth.go
Original file line number Diff line number Diff line change
Expand Up @@ -194,6 +194,9 @@ func Disabled() *Authenticator {
return a
}

// OIDC returns the identity provider verifier, or nil if none is configured.
func (a *Authenticator) OIDC() *OIDCVerifier { return a.oidc }

// IsDisabled reports whether authentication is off.
func (a *Authenticator) IsDisabled() bool { return a.disabled }

Expand Down
33 changes: 33 additions & 0 deletions internal/auth/oidc.go
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,16 @@ type OIDCConfig struct {
// and they never intended to authenticate here.
Audience string

// ClientID is the public OAuth client the CLI authenticates as. It is
// advertised to clients so they do not have to be configured separately
// from the server they are talking to.
//
// There is no client secret. The login flow is a native application on a
// user's machine, and a secret shipped inside one is not a secret — it is
// a string every user can read out of the binary. PKCE replaces it, which
// is what RFC 8252 says to do for exactly this case.
ClientID string

// GroupsClaim names the claim carrying a user's group or role
// memberships. Providers disagree: Okta and Auth0 commonly use "groups",
// Keycloak "roles", Entra ID "roles" or a mapped claim.
Expand Down Expand Up @@ -74,6 +84,29 @@ type OIDCVerifier struct {
ready chan struct{}
}

// PublicConfig is the metadata a client needs to start a login. It is
// deliberately public: every value in it is visible to anybody who watches a
// browser perform a login, and withholding it would only stop legitimate
// clients from configuring themselves.
type PublicConfig struct {
Issuer string `json:"issuer"`
ClientID string `json:"client_id"`
Audience string `json:"audience"`
}

// PublicConfig returns the metadata a client needs to log in.
func (v *OIDCVerifier) PublicConfig() PublicConfig {
return PublicConfig{
Issuer: v.cfg.Issuer,
ClientID: v.cfg.ClientID,
Audience: v.cfg.Audience,
}
}

// LoginEnabled reports whether a client can start an interactive login, which
// needs a client id as well as an issuer.
func (v *OIDCVerifier) LoginEnabled() bool { return v.cfg.ClientID != "" }

// Validate checks an OIDC configuration.
func (c OIDCConfig) Validate() error {
if c.Issuer == "" {
Expand Down
32 changes: 30 additions & 2 deletions internal/cli/cli.go
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,7 @@ package cli

import (
"bytes"
"context"
"encoding/json"
"fmt"
"io"
Expand Down Expand Up @@ -38,14 +39,24 @@ type Client struct {
func NewClient(baseURL string, out io.Writer) *Client {
return &Client{
BaseURL: strings.TrimRight(baseURL, "/"),
Token: os.Getenv("MODELFORGE_TOKEN"),
// The environment wins over a stored login, so a script can override
// whoever happens to be signed in on the machine it runs on.
Token: credential(),
// The timeout is generous because pushing a model uploads its
// artifact, which is the slowest thing this client does by far.
HTTP: &http.Client{Timeout: 2 * time.Minute},
Out: out,
}
}

// credential resolves which token to send.
func credential() string {
if t := os.Getenv("MODELFORGE_TOKEN"); t != "" {
return t
}
return LoadCredential()
}

// Usage is the help text.
const Usage = `modelforgectl — client for a modelforge server

Expand All @@ -67,12 +78,16 @@ Commands:
drift <model> <version> show drift readings
stats <model> <version> show batching and health counters
token <name> <scope>[+<scope>] [--env] mint an API token and print its config entry
login [--no-browser] sign in through your identity provider
logout remove the stored login from this machine
whoami show who the current credential belongs to

Flags:
-addr URL server address (default http://localhost:8080, or MODELFORGE_ADDR)

Environment:
MODELFORGE_TOKEN bearer token sent with every request
MODELFORGE_TOKEN bearer token sent with every request; overrides a stored login
MODELFORGE_CREDENTIAL_FILE where the login command stores its result

Scopes: predict (call the serving endpoint), read (inspect models, policies,
drift and metrics), admin (everything, including changing what serves traffic).
Expand Down Expand Up @@ -152,6 +167,19 @@ func Run(args []string, addr string, out io.Writer) int {
if v, err = versionArg(args, "stats"); err == nil {
err = c.ShowStats(args[1], v)
}
case "login":
open := OpenBrowser
if len(args) > 1 && args[1] == "--no-browser" {
// For a headless machine, a remote shell, or anyone who would
// rather paste the URL into a browser they trust than have a
// process launch one for them.
open = func(string) error { return errNoBrowserRequested }
}
err = c.Login(context.Background(), open)
case "logout":
err = c.Logout()
case "whoami":
err = c.WhoAmI()
case "token":
if len(args) < 3 {
err = fmt.Errorf("token needs a name and at least one scope")
Expand Down
Loading
Loading