api-auth

command
v0.17.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 15, 2026 License: Apache-2.0 Imports: 17 Imported by: 0

README

API authentication

An API protected by JWT validation, principal extraction and a role check.

Route Needs
GET /whoami any valid token; returns the principal and its roles
GET /admin the api-admins role, granted by the groups claim

The code is in main.go. The same chain appears as runnable examples next to the packages: ExampleOAuth2ValidatorHandler in http/server, ExamplePrincipalExtractionHandler in http/middleware, and ExampleCheck_roleAuthorizer in authz.

Configuration

Variable Meaning Default
LISTEN_ADDR address to listen on 127.0.0.1:8080
AUDIENCE accepted token audience api-auth
ISSUER OIDC issuer to validate tokens from
HMAC_SECRET validate tokens with this shared secret instead of an issuer

Set ISSUER for a real deployment. HMAC_SECRET is for local development and CI only: a shared secret lets anyone who knows it mint a token.

Tokens are read from the Authorization header only. A valid token sent in a cookie is refused.

Try it

Start the server in shared-secret mode:

HMAC_SECRET=local-secret go run ./examples/api-auth

In another terminal, mint a token with the matching secret and audience. The api-admins group is the one that /admin accepts:

export SMOKE_JWT_SECRET=local-secret SMOKE_JWT_AUDIENCE=api-auth
ADMIN=$(./scripts/gen_smoke_token.py --group api-admins)
USER=$(./scripts/gen_smoke_token.py)

A token that passes:

curl -i -H "Authorization: Bearer $ADMIN" http://127.0.0.1:8080/admin
# HTTP/1.1 200 OK
# welcome, admin

A token that is refused, because the principal has no role for /admin:

curl -i -H "Authorization: Bearer $USER" http://127.0.0.1:8080/admin
# HTTP/1.1 403 Forbidden

No token, or one that does not validate, is refused earlier:

curl -i http://127.0.0.1:8080/whoami
# HTTP/1.1 401 Unauthorized

Stop the server with Ctrl-C or SIGTERM. It finishes in-flight requests and exits 0.

Documentation

Overview

Command main is an API protected by JWT validation, principal extraction and a role check.

It runs against either a real OIDC issuer (ISSUER and AUDIENCE) or, for local development and CI, a shared secret (HMAC_SECRET). See the README.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL