golemcloud/golem/golem-add-http-auth-go

Requiring Authentication on Go HTTP Endpoints

Overview

Golem authenticates HTTP endpoints via OIDC providers. Auth is declared on the agent definition — mount-wide with Mount.Auth, or per route with golem.EndpointAuth — and then wired to a security scheme in the manifest's (golem.yaml) httpApi deployment. Declaring auth in code without a matching deployment configuration only advertises the requirement; serving it needs the deployment.

Steps

1. Require auth at the mount (Mount{Auth: true}) or per endpoint (golem.EndpointAuth(true)).
2. Override where needed — a per-endpoint golem.EndpointAuth(...) beats the mount default.
3. Configure a security scheme in golem.yaml under the httpApi deployment.

Auth on all endpoints (mount level)

Set Auth: true on the Mount to require authentication for every endpoint of the agent:

type ID struct{ Name string }
 
var Agent = golem.DefineAgent[ID](golem.Spec{
	Name: "SecureAgent",
	HTTP: &golem.Mount{Path: "/secure/{name}", Auth: true}, // all endpoints require auth
})

Auth on individual endpoints

With no mount-level default, require auth on a specific route with golem.EndpointAuth(true):

var Agent = golem.DefineAgent[ID](golem.Spec{
	Name: "ApiAgent",
	HTTP: &golem.Mount{Path: "/api/{name}"},
})
 
var (
	// GET /api/{name}/public  — open
	Public = Agent.Method[golem.Unit, string]("public", golem.HTTP(golem.GET("/public")))
 
	// GET /api/{name}/private  — requires auth
	Private = Agent.Method[golem.Unit, string]("private", golem.HTTP(golem.GET("/private", golem.EndpointAuth(true))))
)

Overriding the mount default

A per-endpoint golem.EndpointAuth overrides the mount's Auth. Use false to open a single route on an otherwise-protected agent:

var Agent = golem.DefineAgent[ID](golem.Spec{
	Name: "MostlySecureAgent",
	HTTP: &golem.Mount{Path: "/api/{name}", Auth: true}, // default: auth required
})
 
var (
	// GET /api/{name}/health  — override to open
	Health = Agent.Method[golem.Unit, string]("health", golem.HTTP(golem.GET("/health", golem.EndpointAuth(false))))
 
	// GET /api/{name}/data  — inherits the mount default (auth required)
	GetData = Agent.Method[golem.Unit, Data]("getData", golem.HTTP(golem.GET("/data")))
)

Receiving the principal

Read who is calling from a golem.Principal field of the method's input struct. The host fills it for every invocation (an OidcPrincipal for an authenticated user), so it is never mapped from the path, query, headers or body, and callers leave it nil. ctx.Principal() is the principal the agent was initialized with:

type ProfileIn struct {
	Principal golem.Principal
}
 
var Profile = Agent.Method[ProfileIn, string]("profile", golem.HTTP(golem.GET("/profile")))
 
agent.Handle(Profile, func(ctx *golem.Context[state], in ProfileIn) string {
	switch p := in.Principal.(type) {
	case golem.OidcPrincipal:
		return "hello " + p.Sub
	default:
		return "hello stranger"
	}
})

The principal is one of golem.OidcPrincipal, golem.AgentPrincipal (another agent over RPC), golem.GolemUserPrincipal (a Golem account, e.g. the CLI) and golem.AnonymousPrincipal.

Deployment configuration

After declaring auth in code, configure a security scheme in golem.yaml under the httpApi deployment (this is where subdomain versus domain is chosen). Quick reference:

httpApi:
  deployments:
    local:
    - subdomain: my-app  # resolves to my-app.localhost:9006 by default
      agents:
        SecureAgent:
          securityScheme: my-oidc            # production OIDC
        # or for development:
        # SecureAgent:
        #   testSessionHeaderName: X-Test-Auth

Key Constraints

• Mount.Auth is a plain bool; golem.EndpointAuth(required bool) takes an explicit value (true to require, false to open).
• Setting golem.EndpointAuth more than once on one endpoint is a definition error, not a silent overwrite — set it exactly once per route.
• An endpoint with no golem.EndpointAuth inherits the mount's Auth.
• A golem.Principal field cannot be bound to a {var}, query parameter or header; that is a definition error.
• Declaring auth requires an httpApi deployment with a security scheme to actually enforce it — mounting alone only advertises the requirement.

Related Skills