libauth

README

libauth

LibAuth for Go - A modern authentication framework that feels as light as a library.

Example Usage

How to verify a valid, trusted token as chi middleware:

package main

import (
	"net/http"

	"github.com/go-chi/chi/v5"

	"git.rootprojects.org/root/keypairs/keyfetch"
	"git.rootprojects.org/root/libauth"
	"git.rootprojects.org/root/libauth/chiauth"
)

func main() {
	r := chi.NewRouter()

	whitelist, err := keyfetch.NewWhitelist([]string{"https://therootcompany.github.io/libauth/"})
	if nil != err {
		panic(err)
	}
	tokenVerifier := chiauth.NewTokenVerifier(chiauth.VerificationParams{
		Issuers:  whitelist,
		Optional: false,
	})
	r.Use(tokenVerifier)

	r.Post("/api/users/profile", func(w http.ResponseWriter, r *http.Request) {
		jws := chiauth.GetJWS(r)
		if nil == jws || !jws.Trusted {
			http.Error(w, "Unauthorized", http.StatusUnauthorized)
			return
		}

		userID := jws.Claims["sub"].(string)
		// ...
	})

    // ...
}

How to create a demo token with [keypairs][https://webinstall.dev/keypairs]:

my_key='./examples/privkey.ec.jwk.json'
my_claims='{
    "iss": "https://therootcompany.github.io/libauth/",
    "sub": "1",
    "email_verified": false,
    "email": "jo@example.com"
}'

keypairs sign \
    --exp 1h \
    "${my_key}" \
    "${my_claims}" \
    > jwt.txt
    2> jws.json

How to pass an auth token:

pushd ./examples
go run ./server.go

my_token="$(cat ./examples/jwt.txt)"

curl -X POST http://localhost:3000/api/users/profile \
    -H "Authorization: Bearer ${my_token}" \
    -H 'Content-Type: application/json' \
    --data-binary '{ "foo": "bar" }'

Example OIDC Discovery URLs

• Demo: https://therootcompany.github.io/libauth/.well-known/openid-configuration
• Auth0: https://example.auth0.com/.well-known/openid-configuration
• Okta: https://example.okta.com/.well-known/openid-configuration
• Google: https://accounts.google.com/.well-known/openid-configuration

Documentation

Index

• func ParseIssuerListString(issuerList string) []string
• type IssuerList
  • func ParseIssuerEnvs(issuersEnvName, internalEnvName string) (IssuerList, error)
• type JWS
  • func VerifyJWS(jws *JWS, issuers IssuerList, r *http.Request) (*JWS, error)
  • func VerifyJWT(jwt string, issuers IssuerList, r *http.Request) (*JWS, error)

Functions

func ParseIssuerListString

func ParseIssuerListString(issuerList string) []string

ParseIssuerListString will Split comma- and/or space-delimited list into a slice

Example:

"https://example.com/, https://therootcompany.github.io/libauth/"

Types

type IssuerList

type IssuerList = keyfetch.Whitelist

IssuerList is the trusted list of token issuers

func ParseIssuerEnvs

func ParseIssuerEnvs(issuersEnvName, internalEnvName string) (IssuerList, error)

ParseIssuerEnvs will parse ENVs (both comma- and space-delimited) to create a trusted IssuerList of public and/or internal issuer URLs.

Example:

OIDC_ISSUERS='https://example.com/ https://therootcompany.github.io/libauth/'
OIDC_ISSUERS_INTERNAL='http://localhost:3000/ http://my-service-name:8080/'

type JWS

type JWS struct {
	keypairs.JWS

	Trusted bool    `json:"trusted"`
	Errors  []error `json:"errors,omitempty"`
}

JWS is keypairs.JWS with added debugging information

func VerifyJWS

func VerifyJWS(jws *JWS, issuers IssuerList, r *http.Request) (*JWS, error)

VerifyJWS takes a fully decoded JWS and will return a verified InspectableToken if possible, or otherwise as much detail as possible, possibly including an InspectableToken with failed verification.

func VerifyJWT

func VerifyJWT(jwt string, issuers IssuerList, r *http.Request) (*JWS, error)

VerifyJWT will return a verified InspectableToken if possible, or otherwise as much detail as possible, possibly including an InspectableToken with failed verification.