a1

README

a1

 

a1 provides simple authentication and authorization helpers for a single user service in Go.

The generated GoDoc can be viewed at godoc.org/github.com/scheibo/a1.

Install

$ go install github.com/scheibo/a1
$ a1 password
$2a$10$LhB2d.LDKkLZG/fdk0Zie.LuThQcM/.B.rZi/GPH08qf0KVd/svFK

Usage

func handle(auth *a1.Client) http.Handler {
  return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
    path := r.URL.Path
    switch path {
    case "/login":
      switch r.Method {
      case "GET":
        auth.LoginPage().ServerHTTP(w, r)
      case "POST":
        auth.Login().ServeHTTP(w, r)
      default:
        httpError(w, 405)
      }
    case "/logout":
      auth.Logout("/").ServeHTTP(w, r)
    default:
      // auth.CheckXSRF(auth.EnsureAuth(...))
    }
  })
}

func main() {
  auth := a1.New(hash)

  srv := &http.Server{
    Addr:         fmt.Sprintf(":%v", port),
    Handler:      a1.RateLimit(10, handle(auth)),
  }
  srv.ListenAndServe()
}

Documentation

Overview

Package a1 provides simple authentication and authorization helpers for a single user service. Clients should use Hash to hash their password ahead of time, then initialize a Client with using New with the hash so that it may then be used to authenticate web sevices. a1 provides its own simple LoginPage which POSTS to /login to complete the Login flow, as well as a handler for Logout. a1 uses a secure cookie to store the client's login state. a1 also provides rate limiting and XSRF functionality.

Index

• Constants
• func Hash(password string) (string, error)
• func RateLimit(qps float64, handler http.Handler) http.Handler
• type Client
  • func New(hash string) *Client
  • func (c *Client) CheckXSRF(handler http.Handler, path ...string) http.Handler
  • func (c *Client) CustomLoginPage(favicon, title string, path ...string) http.Handler
  • func (c *Client) EnsureAuth(handler http.Handler) http.Handler
  • func (c *Client) IsAuth(r *http.Request) bool
  • func (c *Client) Login(paths ...string) http.Handler
  • func (c *Client) LoginPage(path ...string) http.Handler
  • func (c *Client) Logout(path ...string) http.Handler
  • func (c *Client) XSRF(path ...string) string

Constants

const CookieName = "Authorization"

CookieName used by a1 for authorization.

const LoginPath = "/login"

LoginPath is the default path used for hosting both the LoginPage (GET) and for performing Login (POST). Alternative paths can be passed to these functions if desired.

const LogoutPath = "/logout"

LogoutPath is the default path for logging out. An alternative path can be passed to Logout if desired.

const RedirectPath = "/"

RedirectPath is the default path the user is redirected to after a successful Login or Logout. Alternatives may be used instead.

Functions

func Hash

func Hash(password string) (string, error)

Hash returns the hash of a password that should be passed to New and used to authenticate the user.

func RateLimit

func RateLimit(qps float64, handler http.Handler) http.Handler

RateLimit restricts the qps of a wrapped handler.

Types

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client holds the state required by a1 to verify a user. A new client can be created using New.

func New

func New(hash string) *Client

New takes a hash returned from Hash and returns a new Client which can be used for authenticating users.

func (*Client) CheckXSRF

func (c *Client) CheckXSRF(handler http.Handler, path ...string) http.Handler

CheckXSRF wraps a handler and ensures POST requests to the handler contain a token returned by an XSRF call (with optional path) in the body.

func (*Client) CustomLoginPage

func (c *Client) CustomLoginPage(favicon, title string, path ...string) http.Handler

CustomLoginPage allows for tweaking the favicon and title of the page that LoginPage provides.

func (*Client) EnsureAuth

func (c *Client) EnsureAuth(handler http.Handler) http.Handler

EnsureAuth wraps a handler and ensures requests to it are authenticated before allowing it to proceed.

func (*Client) IsAuth

func (c *Client) IsAuth(r *http.Request) bool

IsAuth checks whether a request r is authenticated by this client (i.e. the session is present and hasn't expired and the decoded cookie matches the session).

func (*Client) Login

func (c *Client) Login(paths ...string) http.Handler

Login authenticates users provided the password they POST hash to the same hash the client was initialized with. By default, LoginPath is used for verifying XSRF and users are redirected to RedirectPath after successfully loggin in, but alternatives may be passed in through the paths parameter.

func (*Client) LoginPage

func (c *Client) LoginPage(path ...string) http.Handler

LoginPage returns a default login page that will POST its form to the optional path argument or LoginPath. The page can be further customized through the use of CustomLoginPage.

func (*Client) Logout

func (c *Client) Logout(path ...string) http.Handler

Logout logs a user out, clearing the session and then redirecting them to the optional path passed in or RedirectPath.

func (*Client) XSRF

func (c *Client) XSRF(path ...string) string

XSRF returns a token (which can optionally be scoped to a specific path) to be used for thrwating cross-site request forgery along with CheckXSRF.