Eine Go-API schützen

Diese Schnellstartanleitung schützt eine Go-net/http-API mit KeenAuth-Zugriffstokens. Sie fügen die protect-Middleware des Go-SDKs hinzu, verlangen einen Scope auf einer Route und testen die API offline mit dem Test-Kit des SDKs. Die Middleware verwendet ausschließlich die Standardbibliothek und funktioniert mit jedem Router, der ein http.Handler akzeptiert.

Die API hat drei Endpunkte:

Bevor Sie beginnen

• Eine KeenAuth-Umgebung. Ihr Issuer sieht aus wie https://your-environment.eu.keenauth.app.
• Eine in der Umgebung registrierte API (API anlegen). Ihr identifier, zum Beispiel https://api.example.com, ist die Zielgruppe der Tokens, die Ihre API akzeptiert.
• Der Scope messages:read für diese API, gewährt an die Anwendung, die sie aufruft.
• Go 1.26 oder neuer.

1. Das SDK installieren

go get github.com/keenauth/keenauth-go

Das SDK ist noch nicht veröffentlicht. Bis dahin baut das Beispiel mit dem SDK-Quellcode über eine replace-Direktive in go.mod.

2. Konfigurieren

Die API liest ihre Konfiguration ausschließlich aus Umgebungsvariablen:

3. Ihre Routen schützen

NewHandler erstellt die Middleware und die Routen. m.Handler verlangt ein gültiges Token; m.Require verlangt zusätzlich Scopes. Der Handler liest die verifizierten Claims mit protect.ClaimsFrom.

// NewHandler builds the API. The verifier is a parameter so that tests can pass the offline test kit's verifier;
// main passes a real one. The revocation cache is fed from the token.revoked webhook.
func NewHandler(v protect.AccessTokenVerifier, publicBaseURL string, revocation protect.RevocationChecker) (http.Handler, error) {
	m, err := protect.New(v, protect.Options{
		PublicBaseURL: publicBaseURL,
		Revocation:    revocation,
		OnError: func(r *http.Request, err error) {
			// The error never contains the token or claim values; never log the Authorization or DPoP header.
			log.Printf("rejected %s %s: %v", r.Method, r.URL.Path, err)
		},
	})
	if err != nil {
		return nil, err
	}

	mux := http.NewServeMux()
	// No token needed.
	mux.HandleFunc("GET /api/public", func(w http.ResponseWriter, _ *http.Request) {
		writeJSON(w, map[string]string{"message": "Hello from a public endpoint."})
	})
	// Any valid access token for this API.
	mux.Handle("GET /api/private", m.Handler(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		claims, _ := protect.ClaimsFrom(r.Context())
		writeJSON(w, map[string]string{"message": "Hello from a private endpoint.", "sub": claims.Subject})
	})))
	// A valid access token that also carries the messages:read scope.
	mux.Handle("GET /api/messages", m.Require(protect.Requirement{Scopes: []string{"messages:read"}})(
		http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
			writeJSON(w, map[string]any{"messages": []string{"Hello from a scoped endpoint."}})
		})))
	return mux, nil
}

main erstellt aus der Konfiguration den echten Verifier. Der Verifier ruft die Signierschlüssel beim ersten gesehenen Token aus Ihrer Umgebung ab.

func main() {
	cfg, err := ConfigFromEnv(os.Getenv)
	if err != nil {
		log.Fatal(err)
	}
	// verify.New refuses an issuer under the reserved .invalid domain, so a test token can never pass here.
	v, err := verify.New(verify.Config{Issuer: cfg.Issuer, Audience: cfg.Audience})
	if err != nil {
		log.Fatal(err)
	}
	revocation := protect.NewMemoryRevocationCache(0, nil)
	api, err := NewHandler(v, cfg.PublicBaseURL, revocation)
	if err != nil {
		log.Fatal(err)
	}
	h := api
	if len(cfg.WebhookSecrets) > 0 {
		wv, err := webhook.NewVerifier(cfg.WebhookSecrets) // the error never contains the secret
		if err != nil {
			log.Fatalf("KEENAUTH_WEBHOOK_SECRET: %v", err)
		}
		h = WithWebhook(api, NewWebhookHandler(wv, revocation, nil))
	} else {
		log.Print("KEENAUTH_WEBHOOK_SECRET is not set: token.revoked events are not received, so revoked tokens stay valid until they expire")
	}
	srv := &http.Server{Addr: cfg.Addr, Handler: h, ReadHeaderTimeout: 10 * time.Second}
	log.Printf("listening on %s", cfg.Addr)
	log.Fatal(srv.ListenAndServe())
}

4. API starten und aufrufen

export KEENAUTH_ISSUER=https://your-environment.eu.keenauth.app
export KEENAUTH_AUDIENCE=https://api.example.com
export PUBLIC_BASE_URL=https://api.example.com
go run .

Für einen ersten Aufruf holen Sie sich ein Token über den Client-Credentials-Grant einer Machine-to-Machine-Anwendung, die den Scope messages:read für Ihre API besitzt:

ACCESS_TOKEN=$(curl -s -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d grant_type=client_credentials \
  -d resource=https://api.example.com \
  -d scope=messages:read \
  https://your-environment.eu.keenauth.app/oauth2/token | jq -r .access_token)

curl -i http://localhost:8080/api/messages -H "Authorization: Bearer $ACCESS_TOKEN"

5. Ohne Netzwerk testen

Das Test-Kit-Paket keenauthtest erstellt Tokens, die mit einem öffentlichen Testschlüssel signiert sind, und baut einen Verifier, der nur diese Tokens akzeptiert. Die Tests übergeben diesen Verifier an NewHandler, sodass sie weder Netzwerk noch ein KeenAuth-Konto benötigen. Siehe Offline-Test-Kit.

func newTestAPI(t *testing.T) (http.Handler, *protect.MemoryRevocationCache) {
	t.Helper()
	v, err := keenauthtest.NewVerifier(verify.Config{Audience: audience})
	if err != nil {
		t.Fatal(err)
	}
	cache := protect.NewMemoryRevocationCache(0, nil)
	h, err := NewHandler(v, baseURL, cache)
	if err != nil {
		t.Fatal(err)
	}
	return h, cache
}

go test ./...

Die Tests des Beispiels prüfen, dass ein gültiges Token akzeptiert wird und dass ein fehlendes, abgelaufenes oder für eine andere Zielgruppe ausgestelltes Token, ein fehlender Scope, ein Token in der URL-Abfrage und ein widerrufenes Token mit den unten stehenden Statuscodes abgelehnt werden. Außerdem senden sie ein DPoP-gebundenes Token mit einem Nachweis für PUBLIC_BASE_URL. Die Tests senden zudem signierte token.revoked-Zustellungen: Eine gültige widerruft das Token, eine gefälschte, manipulierte oder veraltete erhält 400 und widerruft nichts, und eine wiederholte hat genau eine Wirkung.

Antworten

Der Body ist application/problem+json, und der WWW-Authenticate-Header enthält die Standard-Challenge. Die vollständige Tabelle finden Sie unter Ihre API mit Middleware schützen.

Hinter einem Proxy

Wenn Clients DPoP verwenden, prüft die Middleware, dass jeder Nachweis für die URL erstellt wurde, die der Client aufgerufen hat. Setzen Sie PUBLIC_BASE_URL auf die externe URL, die Clients aufrufen, zum Beispiel https://api.example.com, auch hinter einem Proxy oder Load Balancer. Die Variable ist erforderlich und muss https verwenden (http nur für localhost, 127.0.0.1 oder [::1]); ohne sie startet die App nicht. Die Middleware vertraut X-Forwarded-*-Headern nie.

Widerrufene Tokens

Ein Zugriffstoken bleibt bis zu seinem Ablauf gültig, daher teilt KeenAuth Ihrer API mit, wann Tokens widerrufen werden. Das Beispiel übergibt der Middleware einen In-Memory-Widerrufs-Cache und stellt einen token.revoked-Webhook unter POST /webhooks/keenauth (main.go, webhook.go) bereit, der diesen Cache füllt.

1. Erstellen Sie im Dashboard einen Webhook-Endpunkt mit der URL https://<your host>/webhooks/keenauth, der token.revoked abonniert, und exportieren Sie sein Signiergeheimnis als KEENAUTH_WEBHOOK_SECRET.
2. Der Handler prüft die Signatur mit dem SDK auf dem rohen Body und antwortet mit 400, wenn sie ungültig ist oder der Zeitstempel mehr als fünf Minuten abweicht. Er ordnet den Selektor des Ereignisses (access_token, session, user, client, org, org_user, client_user) einer Widerrufsmarkierung zu und antwortet mit 204; die Middleware lehnt danach jedes passende Token ab, das vor not_before ausgestellt wurde.
3. KeenAuth liefert mindestens einmal aus, daher wendet der Handler jede webhook-id genau einmal an. Kann die Markierung nicht gespeichert werden, antwortet er mit 503, und KeenAuth stellt das Ereignis erneut zu. Andere Ereignistypen sowie Selektoren, die auf kein Zugriffstoken passen (refresh_family, api), ignoriert er.

Der Handler protokolliert die Ereignis-ID, den Selektortyp und den Grund, niemals den Body, eine Signatur oder das Geheimnis. Jeder Prozess hat seinen eigenen Cache; bei mehreren Instanzen legen Sie die Markierungen in einem gemeinsam genutzten Speicher hinter derselben Revoke-Methode ab. Siehe Widerrufs-Cache.

Nächste Schritte

• Ihre API mit Middleware schützen: Step-up-Anforderungen, DPoP und alle Optionen.
• Tokens verifizieren: der Verifier unter der Middleware.
• Offline-Test-Kit.