go

Go implementation of the aice-auth contract; currently provides an ES256 JWT verifier built on golang-jwt.

Go 100%

View on GitLab ↗

git@gitlab.com:aice-lab/auth/go.git

Latest release

v1.0.0 · May 11, 2026

README

aice-auth — Go

Go implementation of the aice-auth contract defined at https://gitlab.com/aice-lab/auth/spec.

This module provides the Go-side primitives a service needs to act as an OIDC relying party against an aice-auth issuer: JWT verification, with refresh-rotation, JWKS rotation, and OIDC client helpers landing in subsequent releases.

Status

Feature	State
ES256 JWT verification (kid lookup, iss/aud/exp/nbf)	Available (`jwtverify`)
JWKS fetch + TTL cache + on-demand refresh	Available (`jwks`)
Remote verify (JWKS fetch + cache + rotation)	Available (`jwks.Verifier`)
Refresh-token rotation client	Planned
OIDC discovery + token exchange	Planned

jwtverify is the low-level verifier; jwks.Verifier is the ergonomic high-level path.

Quickstart

High-level: `jwks.Verifier` (recommended)

Fetches the JWKS, caches it, and re-fetches automatically on unknown kid (key rotation):

import "gitlab.com/aice-lab/auth/go/jwks"

v := jwks.NewVerifier(
    "https://<issuer>",
    "<audience>",
    "https://<issuer>/.well-known/aice-auth-keys.json",
)

claims, err := v.Verify(ctx, accessToken)

Low-level: `jwtverify` (bring your own JWKS fetch)

package main

import (
    "fmt"

    "gitlab.com/aice-lab/auth/go/jwtverify"
)

func main() {
    jwksDoc := []byte(`{"keys":[...]}`) // fetched from issuer's jwks_uri
    tokenStr := "eyJhbGciOiJFUzI1NiIs..."

    jwks, err := jwtverify.FromJSON(jwksDoc)
    if err != nil {
        panic(err)
    }

    claims, err := jwtverify.Verify(tokenStr, jwks, jwtverify.VerifyOptions{
        Issuer:   "https://id.example.com",
        Audience: "example-app",
    })
    if err != nil {
        fmt.Println("invalid token:", err)
        return
    }

    fmt.Println("subject:", claims["sub"])
}

Install

go get gitlab.com/aice-lab/auth/go@latest

Module path: gitlab.com/aice-lab/auth/go. Go 1.23+.

Development

git clone git@gitlab.com:aice-lab/auth/go.git
cd go
go test ./...
go test -coverprofile=coverage.out ./... && go tool cover -func=coverage.out

License

Source: FSL-1.1-Apache-2.0 (see LICENSE and LICENSE.FAQ.md).

Documentation

Full documentation: https://auth.aice-lab.org

Contributing

See CONTRIBUTING.md. All commits require DCO sign-off.

Reporting security issues

See SECURITY.md. Do not open public issues for vulnerabilities.

This is a snapshot generated from GitLab. For the live README, see the project page.

go