introspection

README

OAuth2 Introspection Client

Go middleware client library for the OAuth2 Introspection Spec (rfc7662). Its 100% compatible with standard net/http. Can be used with a variety of routers. Built using the new content package in Go 1.7 and hence only works for Go 1.7+. Can be easily extended as allowed in the spec. For more advanced examples refer to the godoc.

Simple Example

package main

import (    
    "fmt"
    "log"
    "net/http"
    
    "github.com/srikrsna/oauth-introspection"
)

func main() {
    mux := http.NewServeMux()
    
    mux.HandleFunc("/secure/ping", func(w http.ResponseWriter, r*http.Request) {
        res, err := introspection.FromContext(r.Context())
        if err != nil {
            log.Fatal(err)
        }
        
        if !res.Active {
            http.Error(w, "Token Invalid", 401)
            return
        }
        
        // Check for Scopes and other values or use a middleware to all this
        
        fmt.Fprint(w, "secure pong")
    })
    
    intro := introspection.Introspection(
        introspection.Must(
            introspection.EndpointFromDiscovery("https://auth.example.com"), 
        ),        
        // Add Additional Headers, Form Parameters if needed
    )
    
    http.ListenAndServe(":8080", intro(mux))
}

Documentation

Index

• Variables
• func AuthFunc(endpoint string, opts ...Option) grpc_auth.AuthFunc
• func EndpointFromDiscovery(iss string) (string, error)
• func Introspection(endpoint string, opts ...Option) func(http.Handler) http.Handler
• func Must(v string, err error) string
• type Cache
  • func NewInMemoryCache() Cache
• type Option
  • func WithAddedBody(b url.Values) Option
  • func WithAddedHeaders(h http.Header) Option
  • func WithCache(cache Cache, exp time.Duration) Option
• type Options
• type Result
  • func FromContext(ctx context.Context) (*Result, error)

Variables

var (
	// ErrNoBearer is returned by FromContext function when no Bearer token was present
	ErrNoBearer = errors.New("no bearer")
	// ErrNoMiddleware is returned by FromContext when no value was set. It is due to the middleware not being called before this function.
	ErrNoMiddleware = errors.New("introspection middleware didn't execute")
)

Functions

func AuthFunc

func AuthFunc(endpoint string, opts ...Option) grpc_auth.AuthFunc

AuthFunc ...

func EndpointFromDiscovery

func EndpointFromDiscovery(iss string) (string, error)

EndpointFromDiscovery is helper function to get the introspection endpoint from the openid issuer/authority

func Introspection

func Introspection(endpoint string, opts ...Option) func(http.Handler) http.Handler

Introspection ...

func Must

func Must(v string, err error) string

Must is a helper function that panics if err != nil and returns v if err == nil. Typical use case is to wrap it with EndpointFromDiscovery function

Types

type Cache

type Cache interface {
	// Get gets the Result object associated with the key
	Get(key string) *Result

	// Store is used to store an introspection result associated with the key set to expire in specified duration
	Store(key string, res *Result, exp time.Duration)
}

Cache is used to store the introspection result

func NewInMemoryCache

func NewInMemoryCache() Cache

NewInMemoryCache returns an in memory implementation of the Cache. Useful for testing and single instance apps.

type Option

type Option func(*Options)

Option ...

func WithAddedBody

func WithAddedBody(b url.Values) Option

WithAddedBody ...

func WithAddedHeaders

func WithAddedHeaders(h http.Header) Option

WithAddedHeaders ...

func WithCache

func WithCache(cache Cache, exp time.Duration) Option

WithCache uses provided cache to store and retrieve objects, if this option is passed caching will be used otherwise not used exp is the expiry for each cache entry

type Options

type Options struct {
	Client *http.Client
	// contains filtered or unexported fields
}

Options ...

type Result

type Result struct {
	Active bool

	Optionals map[string]json.RawMessage
}

Result is the OAuth2 Introspection Result

func FromContext

func FromContext(ctx context.Context) (*Result, error)

FromContext ...