basic

Documentation

Overview

Package basic provides authentication strategy, to authenticate HTTP requests using the standard basic scheme.

Example

package main

import (
	"context"
	"fmt"
	"net/http"

	"github.com/Sosivio/go-guardian/v2/auth"
	"github.com/Sosivio/go-guardian/v2/auth/strategies/basic"
	_ "github.com/Sosivio/libcache/lru"
)

func main() {
	strategy := basic.New(exampleAuthFunc)

	// user request
	req, _ := http.NewRequest("GET", "/", nil)
	req.SetBasicAuth("test", "test")
	user, err := strategy.Authenticate(req.Context(), req)
	fmt.Println(user.GetID(), err)

	req.SetBasicAuth("test", "1234")
	_, err = strategy.Authenticate(req.Context(), req)
	fmt.Println(err)

}

func exampleAuthFunc(ctx context.Context, r *http.Request, userName, password string) (auth.Info, error) {

	if userName == "test" && password == "test" {
		return auth.NewDefaultUser("test", "10", nil, nil), nil
	}

	return nil, fmt.Errorf("Invalid credentials")
}

Output:

10 <nil>
Invalid credentials

Example (Second)

package main

import (
	"context"
	"fmt"
	"net/http"

	"github.com/Sosivio/libcache"

	"github.com/Sosivio/go-guardian/v2/auth"
	"github.com/Sosivio/go-guardian/v2/auth/strategies/basic"
	_ "github.com/Sosivio/libcache/lru"
)

func main() {
	// This example show how to caches the result of basic auth.
	// With LRU cache
	cache := libcache.LRU.New(1)
	strategy := basic.NewCached(exampleAuthFunc, cache)

	// user request
	req, _ := http.NewRequest("GET", "/", nil)
	req.SetBasicAuth("test", "test")
	user, err := strategy.Authenticate(req.Context(), req)
	fmt.Println(user.GetID(), err)

	req.SetBasicAuth("test", "1234")
	_, err = strategy.Authenticate(req.Context(), req)
	fmt.Println(err)

}

func exampleAuthFunc(ctx context.Context, r *http.Request, userName, password string) (auth.Info, error) {

	if userName == "test" && password == "test" {
		return auth.NewDefaultUser("test", "10", nil, nil), nil
	}

	return nil, fmt.Errorf("Invalid credentials")
}

Output:

10 <nil>
strategies/basic: Invalid user credentials

Index

• Constants
• Variables
• func New(fn AuthenticateFunc, opts ...auth.Option) auth.Strategy
• func NewCached(f AuthenticateFunc, cache auth.Cache, opts ...auth.Option) auth.Strategy
• func SetComparator(c Comparator) auth.Option
• func SetHash(h crypto.Hash) auth.Option
• func SetParser(p Parser) auth.Option
• func SetUserNameHash(h crypto.Hash, key []byte) auth.Option
• type AuthenticateFunc
• type Comparator
• type Parser
  • func AuthorizationParser() Parser

Examples

• Package
• Package (Second)
• SetHash
• SetUserNameHash

Constants

const ExtensionKey = "x-go-guardian-basic-password"

ExtensionKey represents a key for the password in info extensions. Typically used when basic strategy cache the authentication decisions.

Variables

var (
	// ErrMissingPrams is returned by Authenticate Strategy method,
	// when failed to retrieve user credentials from request.
	ErrMissingPrams = errors.New("strategies/basic: Request missing BasicAuth")

	// ErrInvalidCredentials is returned by Authenticate Strategy method,
	// when user password is invalid.
	ErrInvalidCredentials = errors.New("strategies/basic: Invalid user credentials")
)

Functions

func New

func New(fn AuthenticateFunc, opts ...auth.Option) auth.Strategy

New return new auth.Strategy.

func NewCached

func NewCached(f AuthenticateFunc, cache auth.Cache, opts ...auth.Option) auth.Strategy

NewCached return new auth.Strategy. The returned strategy, caches the invocation result of authenticate function.

func SetComparator

func SetComparator(c Comparator) auth.Option

SetComparator set password comparator, to be used when caching the auth decision.

func SetHash

func SetHash(h crypto.Hash) auth.Option

SetHash apply password hashing using h, SetHash only used when caching the auth decision, to mitigates brute force attacks.

Example

package main

import (
	"context"
	"crypto"
	"fmt"
	"net/http"

	"github.com/Sosivio/libcache"

	"github.com/Sosivio/go-guardian/v2/auth"
	"github.com/Sosivio/go-guardian/v2/auth/strategies/basic"
	_ "github.com/Sosivio/libcache/lru"
)

func main() {
	opt := basic.SetHash(crypto.SHA256) // import _ crypto/sha256
	cache := libcache.LRU.New(1)
	basic.NewCached(exampleAuthFunc, cache, opt)
}

func exampleAuthFunc(ctx context.Context, r *http.Request, userName, password string) (auth.Info, error) {

	if userName == "test" && password == "test" {
		return auth.NewDefaultUser("test", "10", nil, nil), nil
	}

	return nil, fmt.Errorf("Invalid credentials")
}

func SetParser

func SetParser(p Parser) auth.Option

SetParser set credentials parser.

func SetUserNameHash

func SetUserNameHash(h crypto.Hash, key []byte) auth.Option

SetUserNameHash apply username hashing based on HMAC with h and key, SetUserNameHash only used when caching the auth decision, to prevent precomputation and length extension attacks, and to mitigates hash map DOS attacks via collisions.

Example

package main

import (
	"context"
	"crypto"
	"fmt"
	"net/http"

	"github.com/Sosivio/libcache"

	"github.com/Sosivio/go-guardian/v2/auth"
	"github.com/Sosivio/go-guardian/v2/auth/strategies/basic"
	_ "github.com/Sosivio/libcache/lru"
)

func main() {
	opt := basic.SetUserNameHash(crypto.SHA256, []byte("<32 byte key>")) // import _ crypto/sha256
	cache := libcache.LRU.New(1)
	basic.NewCached(exampleAuthFunc, cache, opt)
}

func exampleAuthFunc(ctx context.Context, r *http.Request, userName, password string) (auth.Info, error) {

	if userName == "test" && password == "test" {
		return auth.NewDefaultUser("test", "10", nil, nil), nil
	}

	return nil, fmt.Errorf("Invalid credentials")
}

Types

type AuthenticateFunc

type AuthenticateFunc func(ctx context.Context, r *http.Request, userName, password string) (auth.Info, error)

AuthenticateFunc declare custom function to authenticate request using user credentials. the authenticate function invoked by Authenticate Strategy method after extracting user credentials to compare against DB or other service, if extracting user credentials from request failed a nil info with ErrMissingPrams returned, Otherwise, return Authenticate invocation result.

type Comparator

type Comparator interface {
	Hash(password string) (string, error)
	Compare(hashedPassword, password string) error
}

Comparator is the interface implemented by types, that can generate password hash and compares the hashed password with its possible plaintext equivalent

type Parser

type Parser interface {
	Credentials(r *http.Request) (string, string, error)
}

Parser parse and extract user credentials from incoming HTTP request.

func AuthorizationParser

func AuthorizationParser() Parser

AuthorizationParser return a credentials parser, where credentials extracted form Authorization header.