auth

Documentation

Overview

Package auth provides a set of user authentication handlers for the ozzo routing package.

Index

• Constants
• Variables
• func Basic(fn BasicAuthFunc, realm ...string) routing.Handler
• func Bearer(fn TokenAuthFunc, realm ...string) routing.Handler
• func DefaultJWTTokenHandler(c *routing.Context, token *jwt.Token) error
• func JWT(verificationKey string, options ...JWTOptions) routing.Handler
• func NewJWT(claims jwt.MapClaims, signingKey string, signingMethod ...jwt.SigningMethod) (string, error)
• func Query(fn TokenAuthFunc, tokenName ...string) routing.Handler
• type BasicAuthFunc
• type Identity
• type JWTOptions
• type JWTTokenHandler
• type TokenAuthFunc
• type VerificationKeyHandler

Constants

const User = "User"

User is the key used to store and retrieve the user identity information in routing.Context

Variables

var DefaultRealm = "API"

DefaultRealm is the default realm name for HTTP authentication. It is used by HTTP authentication based on Basic and Bearer.

var TokenName = "access-token"

TokenName is the query parameter name for auth token.

Functions

func Basic

func Basic(fn BasicAuthFunc, realm ...string) routing.Handler

Basic returns a routing.Handler that performs HTTP basic authentication. It can be used like the following:

import (
  "errors"
  "fmt"
  "net/http"
  "github.com/go-ozzo/ozzo-routing"
  "github.com/go-ozzo/ozzo-routing/auth"
)
func main() {
  r := routing.New()
  r.Use(auth.Basic(func(c *routing.Context, username, password string) (auth.Identity, error) {
    if username == "demo" && password == "foo" {
      return auth.Identity(username), nil
    }
    return nil, errors.New("invalid credential")
  }))
  r.Get("/demo", func(c *routing.Context) error {
    fmt.Fprintf(res, "Hello, %v", c.Get(auth.User))
    return nil
  })
}

By default, the auth realm is named as "API". You may customize it by specifying the realm parameter.

When authentication fails, a "WWW-Authenticate" header will be sent, and an http.StatusUnauthorized error will be returned.

func Bearer

func Bearer(fn TokenAuthFunc, realm ...string) routing.Handler

Bearer returns a routing.Handler that performs HTTP authentication based on bearer token. It can be used like the following:

import (
  "errors"
  "fmt"
  "net/http"
  "github.com/go-ozzo/ozzo-routing"
  "github.com/go-ozzo/ozzo-routing/auth"
)
func main() {
  r := routing.New()
  r.Use(auth.Bearer(func(c *routing.Context, token string) (auth.Identity, error) {
    if token == "secret" {
      return auth.Identity("demo"), nil
    }
    return nil, errors.New("invalid credential")
  }))
  r.Get("/demo", func(c *routing.Context) error {
    fmt.Fprintf(res, "Hello, %v", c.Get(auth.User))
    return nil
  })
}

By default, the auth realm is named as "API". You may customize it by specifying the realm parameter.

When authentication fails, a "WWW-Authenticate" header will be sent, and an http.StatusUnauthorized error will be returned.

func DefaultJWTTokenHandler

func DefaultJWTTokenHandler(c *routing.Context, token *jwt.Token) error

DefaultJWTTokenHandler stores the parsed JWT token in the routing context with the key named "JWT".

func JWT

func JWT(verificationKey string, options ...JWTOptions) routing.Handler

JWT returns a JWT (JSON Web Token) handler which attempts to parse the Bearer header into a JWT token and validate it. If both are successful, it will call a JWTTokenHandler to further handle the token. By default, the token will be stored in the routing context with the key named "JWT". Other handlers can retrieve this token to obtain the user identity information. If the parsing or validation fails, a "WWW-Authenticate" header will be sent, and an http.StatusUnauthorized error will be returned.

JWT can be used like the following:

import (
  "errors"
  "fmt"
  "net/http"
  "github.com/dgrijalva/jwt-go"
  "github.com/go-ozzo/ozzo-routing"
  "github.com/go-ozzo/ozzo-routing/auth"
)
func main() {
  signingKey := "secret-key"
  r := routing.New()

  r.Get("/login", func(c *routing.Context) error {
    id, err := authenticate(c)
    if err != nil {
      return err
    }
    token, err := auth.NewJWT(jwt.MapClaims{
      "id": id
    }, signingKey)
    if err != nil {
      return err
    }
    return c.Write(token)
  })

  r.Use(auth.JWT(signingKey))
  r.Get("/restricted", func(c *routing.Context) error {
    claims := c.Get("JWT").(*jwt.Token).Claims.(jwt.MapClaims)
    return c.Write(fmt.Sprint("Welcome, %v!", claims["id"]))
  })
}

func NewJWT

func NewJWT(claims jwt.MapClaims, signingKey string, signingMethod ...jwt.SigningMethod) (string, error)

NewJWT creates a new JWT token and returns it as a signed string that may be sent to the client side. The signingMethod parameter is optional. It defaults to the HS256 algorithm.

func Query

func Query(fn TokenAuthFunc, tokenName ...string) routing.Handler

Query returns a routing.Handler that performs authentication based on a token passed via a query parameter. It can be used like the following:

import (
  "errors"
  "fmt"
  "net/http"
  "github.com/go-ozzo/ozzo-routing"
  "github.com/go-ozzo/ozzo-routing/auth"
)
func main() {
  r := routing.New()
  r.Use(auth.Query(func(token string) (auth.Identity, error) {
    if token == "secret" {
      return auth.Identity("demo"), nil
    }
    return nil, errors.New("invalid credential")
  }))
  r.Get("/demo", func(c *routing.Context) error {
    fmt.Fprintf(res, "Hello, %v", c.Get(auth.User))
    return nil
  })
}

When authentication fails, an http.StatusUnauthorized error will be returned.

Types

type BasicAuthFunc

type BasicAuthFunc func(c *routing.Context, username, password string) (Identity, error)

BasicAuthFunc is the function that does the actual user authentication according to the given username and password.

type Identity

type Identity interface{}

Identity represents an authenticated user. If a user is successfully authenticated by an auth handler (Basic, Bearer, or Query), an Identity object will be made available for injection.

type JWTOptions

type JWTOptions struct {
	// auth realm. Defaults to "API".
	Realm string
	// the allowed signing method. This is required and should be the actual method that you use to create JWT token. It defaults to "HS256".
	SigningMethod string
	// a function that handles the parsed JWT token. Defaults to DefaultJWTTokenHandler, which stores the token in the routing context with the key "JWT".
	TokenHandler JWTTokenHandler
	// a function to get a dynamic VerificationKey
	GetVerificationKey VerificationKeyHandler
}

JWTOptions represents the options that can be used with the JWT handler.

type JWTTokenHandler

type JWTTokenHandler func(*routing.Context, *jwt.Token) error

JWTTokenHandler handles the parsed JWT token.

type TokenAuthFunc

type TokenAuthFunc func(c *routing.Context, token string) (Identity, error)

TokenAuthFunc is the function for authenticating a user based on a secret token.

type VerificationKeyHandler

type VerificationKeyHandler func(*routing.Context) string

Get a dynamic VerificationKey