dmv

README

dmv

Simple authentication for Martini. Does not handle state or make use of the sessions middleware. It only provides a means of initial authentication. Beacuse of this, it is up to the application to implement its own authorization. External authentication mediums will provide profile information. For example, the OAuth 2.0 Facebook function provides information about the user including their name and email address.

Authentication is handled on a per route basis, allowing applications to easily use multiple authentication mediums.

Supported Mediums

• Local (Form)
• Local (Basic)
• Github OAuth 2.0
• Facebook OAuth 2.0
• Google OAuth 2.0

Usage

There is sample usage for each Auth* function in the docs. Also see examples.

Documentation

Overview

Package dmv simple authentication schemes for Martini

Index

• func AuthBasic() martini.Handler
• func AuthFacebook(opts *OAuth2Options) martini.Handler
• func AuthGithub(opts *OAuth2Options) martini.Handler
• func AuthGoogle(opts *OAuth2Options) martini.Handler
• func AuthLocal(opts *LocalOptions) martini.Handler
• func FailBasic(w http.ResponseWriter)
• func RedirectRelativeFunc(path string) func(*http.Request) string
• type Basic
• type Facebook
• type FacebookProfile
• type Github
• type GithubProfile
• type Google
• type GoogleProfile
• type Local
• type LocalOptions
• type OAuth2Options

Functions

func AuthBasic

func AuthBasic() martini.Handler

AuthBasic attempts to get a username and password from an Authorization header. Basic is mapped to the current request context. BasicFail will be called if there are errors, the header is empty, or a username or password is empty.

m.Get("/protected", AuthBasic(), func(b *dmv.Basic, w http.ResponseWriter) {
    // Lookup user by b.Username
    // Compare password to b.Password
    // If not valid call dmv.FailBasic(w)
})

func AuthFacebook

func AuthFacebook(opts *OAuth2Options) martini.Handler

AuthFacebook authenticates users using Facebook and OAuth2.0. After handling a callback request, a request is made to get the users facebook profile and a Facebook struct will be mapped to the current request context.

This function should be called twice in each application, once on the login handler, and once on the callback handler.

package main

import (
    "github.com/go-martini/martini"
    "github.com/martini-contrib/sessions"
    "net/http"
)

func main() {
    fbOpts := &dmv.OAuth2.0Options{
        ClientID: "oauth_id",
        ClientSecret: "oauth_secret",
        RedirectURL: "http://host:port/auth/callback/facebook",
    }

    m := martini.Classic()
    store := sessions.NewCookieStore([]byte("secret123"))
    m.Use(sessions.Sessions("my_session", store))

    m.Get("/", func(s sessions.Session) string {
        return "hi" + s.Get("userID")
    })
    m.Get("/auth/facebook", dmv.AuthFacebook(fbOpts))
    m.Get("/auth/callback/facebook", dmv.AuthFacebook(fbOpts), func(fb *dmv.Facebook, req *http.Request, w http.ResponseWriter) {
        // Handle any errors.
        if len(fb.Errors) > 0 {
            http.Error(w, "Oauth failure", http.StatusInternalServerError)
            return
        }
        // Do something in a database to create or find the user by the facebook profile id.
        user := findOrCreateByFacebookID(fb.Profile.ID)
        s.Set("userID", user.ID)
        http.Redirect(w, req, "/", http.StatusFound)
    })
}

func AuthGithub

func AuthGithub(opts *OAuth2Options) martini.Handler

AuthGithub authenticates users using Github and OAuth2.0. After handling a callback request, a request is made to get the users Github profile and a Github struct will be mapped to the current request context.

This function should be called twice in each application, once on the login handler and once on the callback handler.

package main

import (
    "github.com/go-martini/martini"
    "github.com/martini-contrib/sessions"
    "net/http"
)

func main() {
    ghOpts := &dmv.OAuth2.0Options{
        ClientID: "oauth_id",
        ClientSecret: "oauth_secret",
        RedirectURL: "http://host:port/auth/callback/github",
    }

    m := martini.Classic()
    store := sessions.NewCookieStore([]byte("secret123"))
    m.Use(sessions.Sessions("my_session", store))

    m.Get("/", func(s sessions.Session) string {
        return "hi" + s.Get("userID")
    })
    m.Get("/auth/github", dmv.AuthGithub(ghOpts))
    m.Get("/auth/callback/github", dmv.AuthGithub(ghOpts), func(gh *dmv.Github, req *http.Request, w http.ResponseWriter) {
        // Handle any errors.
        if len(gh.Errors) > 0 {
            http.Error(w, "Oauth failure", http.StatusInternalServerError)
            return
        }
        // Do something in a database to create or find the user by the Github profile id.
        user := findOrCreateByGithubID(gh.Profile.ID)
        s.Set("userID", user.ID)
        http.Redirect(w, req, "/", http.StatusFound)
    })
}

func AuthGoogle

func AuthGoogle(opts *OAuth2Options) martini.Handler

AuthGoogle authenticates users using Google and OAuth2.0. After handling a callback request, a request is made to get the users Google profile and a Google struct will be mapped to the current request context.

This function should be called twice in each application, once on the login handler and once on the callback handler.

package main

import (
    "github.com/go-martini/martini"
    "github.com/martini-contrib/sessions"
    "github.com/thomasjsteele/dmv"
    "net/http"
)

func main() {
    googleOpts := &dmv.OAuth2Options{
        ClientID: "oauth_id",
        ClientSecret: "oauth_secret",
        RedirectURL: "http://host:port/auth/callback/google",
        Scopes:      []string{"https://www.googleapis.com/auth/userinfo.email",
                              "https://www.googleapis.com/auth/userinfo.profile"},
    }

    m := martini.Classic()
    store := sessions.NewCookieStore([]byte("secret123"))
    m.Use(sessions.Sessions("my_session", store))

    m.Get("/", func(s sessions.Session) string {
        return "hello" + s.Get("userID")
    })
    m.Get("/auth/google", dmv.AuthGoogle(googleOpts))
    m.Get("/auth/callback/google", dmv.AuthGoogle(googleOpts), func(goog *dmv.Google, req *http.Request, w http.ResponseWriter) {
        // Handle any errors.
        if len(goog.Errors) > 0 {
            http.Error(w, "OAuth failure", http.StatusInternalServerError)
            return
        }
        // Do something in a database to create or find the user by the Google profile id.
        s.Set("userID", goog.Profile.ID)
        http.Redirect(w, req, "/", http.StatusFound)
    })
}

func AuthLocal

func AuthLocal(opts *LocalOptions) martini.Handler

AuthLocal attempts to get a username and password from a request.

m.Post("/login", dmv.AuthLocal(), func(l *dmv.Local) {
    if len(l.Errors) > 0 {
        // Return "invalid username or password" message  or perhaps 401.
    }
    // Lookup user by l.Username
    // Compare password of found user to l.Password
})

func FailBasic

func FailBasic(w http.ResponseWriter)

FailBasic writes the required response headers to prompt for basic authentication.

func RedirectRelativeFunc

func RedirectRelativeFunc(path string) func(*http.Request) string

Types

type Basic

type Basic struct {
	Username string
	Password string
}

Basic stores a username and password from the Authorization header.

type Facebook

type Facebook struct {
	Errors       []error
	AccessToken  string
	RefreshToken string
	Profile      FacebookProfile
}

Facebook stores the access and refresh tokens along with the users profile.

type FacebookProfile

type FacebookProfile struct {
	ID         string `json:"id"`
	Username   string `json:"username"`
	Name       string `json:"name"`
	LastName   string `json:"last_name"`
	FirstName  string `json:"first_name"`
	MiddleName string `json:"middle_name"`
	Gender     string `json:"gender"`
	Link       string `json:"link"`
	Email      string `json:"email"`
}

FacebookProfile stores information about the user from facebook.

type Github

type Github struct {
	Errors       []error
	AccessToken  string
	RefreshToken string
	Profile      GithubProfile
}

Github stores the access and refresh tokens along with the users profile.

type GithubProfile

type GithubProfile struct {
	ID      int    `json:"id"`
	Name    string `json:"name"`
	Login   string `json:"login"`
	HTMLURL string `json:"html_url"`
	Email   string `json:"email"`
}

GithubProfile stores information about the user from Github.

type Google

type Google struct {
	Errors       []error
	AccessToken  string
	RefreshToken string
	Profile      GoogleProfile
}

Google stores the access and refresh tokens along with the user profile.

type GoogleProfile

type GoogleProfile struct {
	ID          string `json:"id"`
	DisplayName string `json:"name"`
	FamilyName  string `json:"family_name"`
	GivenName   string `json:"given_name"`
	Email       string `json:"email"`
}

GoogleProfile stores information from the users google+ profile.

type Local

type Local struct {
	Errors   []error
	Username string
	Password string
}

Local is mapped to the martini.Context from the martini.Handler returned from AuthLocal.

type LocalOptions

type LocalOptions struct {
	// The form field to represent a username.
	UsernameField string
	// The form field to represent a password.
	PasswordField string
}

LocalOptions are used to pass conditional arguments to AuthLocal.

type OAuth2Options

type OAuth2Options struct {
	ClientID     string
	ClientSecret string
	RedirectURL  string
	// Accepts a func to generate the redirect URL based on the request. Useful
	// if you want to redirect to a relative path. Takes precedence over
	// RedirectURL if both are set.
	RedirectFunc func(*http.Request) string
	Scopes       []string
	AuthURL      string
	TokenURL     string
}

OAuth2Options contains options for complete OAuth2.0.