microauth

README

golang-microauth

Microauth provides a uniform means of serving HTTP/S for golang projects securely. It allows the specification of a certificate (or generates one) as well as an auth token which is checked before the request is processed.

Quickstart

Import and serve

main.go

package main

import (
  "net/http"
  "fmt"
  "io"

  "github.com/mu-box/golang-microauth"
)

func main() {>
 http.HandleFunc("/", func(rw http.ResponseWriter, req *http.>Request) {
   io.WriteString(rw, "World, Hello!\n")
 })

  fmt.Printf("Stopped serving! - %v\n",
  	microauth.ListenAndServe("127.0.0.1:8081", "$ECRET", nil))
}

Test

$ curl localhost:8081 -i
# HTTP/1.1 401 Unauthorized
# Date: Thu, 09 Jun 2016 22:18:55 GMT
# Content-Length: 0
# Content-Type: text/plain; charset=utf-8

$ curl -H 'X-MICROBOX-TOKEN: $ECRET' localhost:8081 -i
# HTTP/1.1 200 OK
# Date: Thu, 09 Jun 2016 22:27:24 GMT
# Content-Length: 14
# Content-Type: text/plain; charset=utf-8
#
# World, hello!

Usage

Generate a cert and customize auth the token header

...
	cert, _ := microauth.Generate("logvac.microbox.cloud")
	auth := microauth.Auth{
		Header:      "X-AUTH-TOKEN",
		Certificate: cert,
	}
	return auth.ListenAndServeTLS(config.ListenHttp, "secret", router, "/")
...

Contributing

Contributions to the microbox-router project are welcome and encouraged. Contributions should follow the microbox Contribution Process & Guidelines.

Documentation

Overview

Package microauth provides a uniform means of serving HTTP/S for golang projects securely. It allows the specification of a certificate (or generates one) as well as an auth token which is checked before the request is processed.

Index

• Variables
• func Generate(host string) (*tls.Certificate, error)
• func ListenAndServe(addr, token string, h http.Handler, excludedPaths ...string) error
• func ListenAndServeTLS(addr, token string, h http.Handler, excludedPaths ...string) error
• func Load(certFile, keyFile, password string) (*tls.Certificate, error)
• type Auth
  • func (me *Auth) ListenAndServe(addr, token string, h http.Handler, excludedPaths ...string) error
  • func (me *Auth) ListenAndServeTLS(addr, token string, h http.Handler, excludedPaths ...string) error
  • func (me *Auth) ServeHTTP(rw http.ResponseWriter, req *http.Request)

Examples

• ListenAndServe
• ListenAndServeTLS

Variables

var (
	// DefaultAuth is the default Auth object
	DefaultAuth = &Auth{}
)

Functions

func Generate

func Generate(host string) (*tls.Certificate, error)

Generate is a helper function which generates a tls.Certificate for serving TLS requests.

func ListenAndServe

func ListenAndServe(addr, token string, h http.Handler, excludedPaths ...string) error

ListenAndServe is a shortcut function which uses the default one

Example

package main

import (
	"io"
	"net/http"

	microauth "github.com/mu-box/golang-microauth"
)

func main() {
	http.HandleFunc("/", func(rw http.ResponseWriter, req *http.Request) {
		io.WriteString(rw, "World, Hello!\n")
	})

	microauth.ListenAndServe("127.0.0.1:80", "secret", nil)
}

func ListenAndServeTLS

func ListenAndServeTLS(addr, token string, h http.Handler, excludedPaths ...string) error

ListenAndServeTLS is a shortcut function which uses the default one

Example

package main

import (
	"io"
	"net/http"

	microauth "github.com/mu-box/golang-microauth"
)

func main() {
	http.HandleFunc("/", func(rw http.ResponseWriter, req *http.Request) {
		io.WriteString(rw, "World, Hello!\n")
	})

	cert, _ := microauth.Generate("microauth.microbox.cloud")
	microauth.DefaultAuth.Header = "X-AUTH-TOKEN"
	microauth.DefaultAuth.Certificate = cert

	microauth.ListenAndServeTLS("127.0.0.1:443", "secret", nil)
}

func Load

func Load(certFile, keyFile, password string) (*tls.Certificate, error)

Load is a helper function to load a certificate and key from password protected files.

Types

type Auth

type Auth struct {
	Header        string           // Header is the authentication token's header name
	Certificate   *tls.Certificate // Certificate is the tls.Certificate to serve requests with
	ExcludedPaths []string         // ExcludedPaths is a list of paths to be excluded from being authenticated
	Token         string           // Token is the security/authentication string to validate by
	// contains filtered or unexported fields
}

Auth is a structure containing listener information

func (*Auth) ListenAndServe

func (me *Auth) ListenAndServe(addr, token string, h http.Handler, excludedPaths ...string) error

ListenAndServe starts a normal tcp listener and handles serving http while still validating the auth token.

func (*Auth) ListenAndServeTLS

func (me *Auth) ListenAndServeTLS(addr, token string, h http.Handler, excludedPaths ...string) error

ListenAndServeTLS starts a TLS listener and handles serving https

func (*Auth) ServeHTTP

func (me *Auth) ServeHTTP(rw http.ResponseWriter, req *http.Request)

ServeHTTP is to implement the http.Handler interface. Also let clients know when I have no matching route listeners