auth

README

ExternalAuth

第三方登录平台。通过加载各种第三方登录驱动来实现用户的第三方认证

功能

• 支持多种的登录驱动
• 支持使用代理的方式进行登录
• 提供统一的用户档案接口，将登录后获取的用户信息进行统一处理

限制

• 需要使用Session组件
• 不包含用户系统

支持的驱动列表

• Github
• Windows Live
• Twitter
• Facebook
• 微信企业号(oauth2,扫码)
• 微信公众号(oauth2)

Documentation

Index

• Constants
• Variables
• func DefaultNotFoundAction(w http.ResponseWriter, r *http.Request)
• type Auth
  • func New() *Auth
  • func (a *Auth) GetProvider(keyword string) (*Provider, error)
  • func (a *Auth) Init(option Option) error
  • func (a *Auth) MustGetProvider(keyword string) *Provider
  • func (a *Auth) MustGetResult(req *http.Request) *Result
  • func (a *Auth) MustRegisterProvider(keyword string, driver Driver) *Provider
  • func (a *Auth) MustRegisterWithCreator(keyword string, creator DriverCreator) *Provider
  • func (a *Auth) ProviderManager() ProviderManager
  • func (a *Auth) RandToken(length int) ([]byte, error)
  • func (a *Auth) RegisterProvider(keyword string, driver Driver) (*Provider, error)
  • func (a *Auth) RegisterWithCreator(keyword string, creator DriverCreator) (*Provider, error)
  • func (a *Auth) Serve(SuccessAction func(w http.ResponseWriter, r *http.Request)) func(w http.ResponseWriter, r *http.Request)
  • func (a *Auth) SetProviderManager(p ProviderManager)
  • func (a *Auth) SetResult(r *http.Request, result *Result)
• type ContextName
• type Driver
• type DriverCreator
• type MapProviderManager
  • func NewMapProviderManager() *MapProviderManager
  • func (m *MapProviderManager) GetProvider(a *Auth, keyword string) (*Provider, error)
  • func (m *MapProviderManager) RegisterProvider(a *Auth, keyword string, driver Driver) (*Provider, error)
• type Option
• type OptionFunc
  • func OptionCommon(hostpath string, Session Session) OptionFunc
  • func (i OptionFunc) ApplyTo(a *Auth) error
• type Profile
  • func (p *Profile) AddValue(index ProfileIndex, value string)
  • func (p *Profile) SetValue(index ProfileIndex, value string)
  • func (p *Profile) SetValues(index ProfileIndex, values []string)
  • func (p *Profile) Value(index ProfileIndex) string
  • func (p *Profile) Values(index ProfileIndex) []string
• type ProfileIndex
• type Provider
  • func (p *Provider) AuthRequest(r *http.Request) (*Result, error)
  • func (p *Provider) AuthURL() string
  • func (p *Provider) Login(w http.ResponseWriter, r *http.Request)
  • func (p *Provider) LoginURL() string
• type ProviderManager
• type Result
  • func NewResult() *Result
• type Session

Constants

const DefaultAuthPrefix = "/auth/"

DefaultAuthPrefix default auth action prefix

const DefaultLoginPrefix = "/login/"

DefaultLoginPrefix default login action prefix

const ProfileGenderFemale = "F"

ProfileGenderFemale Female value for profile gender field.

const ProfileGenderMale = "M"

ProfileGenderMale Male value for profile gender field.

const ProfileGenderUnknow = ""

ProfileGenderUnknow Unknow value for profile gender field.

const ProfileIndexAccessToken = ProfileIndex("AccessToken")

ProfileIndexAccessToken profile index accesstoken

const ProfileIndexAvatar = ProfileIndex("Avatar")

ProfileIndexAvatar profile index avatar

const ProfileIndexCity = ProfileIndex("City")

ProfileIndexCity profile index city

const ProfileIndexCompany = ProfileIndex("Company")

ProfileIndexCompany profile index company

const ProfileIndexCountry = ProfileIndex("Country")

ProfileIndexCountry profile index country

const ProfileIndexEmail = ProfileIndex("Email")

ProfileIndexEmail profile index email

const ProfileIndexFirstName = ProfileIndex("FirstName")

ProfileIndexFirstName profile first name

const ProfileIndexGender = ProfileIndex("Gender")

ProfileIndexGender profile index Gender

const ProfileIndexID = ProfileIndex("ID")

ProfileIndexID profile index id.

const ProfileIndexLastName = ProfileIndex("LastName")

ProfileIndexLastName profile last name

const ProfileIndexLocale = ProfileIndex("Locale")

ProfileIndexLocale profile index locale

const ProfileIndexLocation = ProfileIndex("Location")

ProfileIndexLocation profile index location

const ProfileIndexMiddleName = ProfileIndex("LastName")

ProfileIndexMiddleName profile last name

const ProfileIndexName = ProfileIndex("Name")

ProfileIndexName profile index name

const ProfileIndexNickname = ProfileIndex("Nickname")

ProfileIndexNickname profile index nick name

const ProfileIndexProfileURL = ProfileIndex("ProfileURL")

ProfileIndexProfileURL profile index url

const ProfileIndexProvince = ProfileIndex("Province")

ProfileIndexProvince profile index province

const ProfileIndexWebsite = ProfileIndex("Website")

ProfileIndexWebsite profile index website

const ResultContextName = ContextName("authresult")

ResultContextName context name for result in request.

Variables

var DefaultProviderManager = NewMapProviderManager()

DefaultProviderManager default provider manager for auth service.

var ErrAuthParamsError = errors.New("external auth params error")

ErrAuthParamsError error raised when auth prarms error. Should be rasied in auth driver's AuthRequest method.

var TokenMask = []byte("ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789_-")

TokenMask used to generate random bytes.

Functions

func DefaultNotFoundAction

func DefaultNotFoundAction(w http.ResponseWriter, r *http.Request)

DefaultNotFoundAction default not found action execute when provider not found.

Types

type Auth

type Auth struct {

	//Host auth service host.For example,https://www.example.com
	Host string
	//Path auth servcei path.For example,"/auth" in https://www.example.com/auth
	Path string
	//LoginPrefix login action prefix. For example,"/login" in https://www.example.com/auth/login.
	LoginPrefix string
	//AuthPrefix auth action prefix. For example,"/auth" in https://www.example.com/auth/auth.
	AuthPrefix string
	//NotFoundAction action executed when provider keyword not found or auth params error.
	NotFoundAction func(w http.ResponseWriter, r *http.Request)
	//Session session used by auth provider to store data like state.
	Session Session
	// contains filtered or unexported fields
}

Auth auth service main struct

func New

func New() *Auth

New create new auth service. You should init auth after create.

func (*Auth) GetProvider

func (a *Auth) GetProvider(keyword string) (*Provider, error)

GetProvider get registered provider by keyword. return provider and any error if raised.

func (*Auth) Init

func (a *Auth) Init(option Option) error

Init auth with given option.

func (*Auth) MustGetProvider

func (a *Auth) MustGetProvider(keyword string) *Provider

MustGetProvider get registered provider by keyword. Panic if any error raised. return provider.

func (*Auth) MustGetResult

func (a *Auth) MustGetResult(req *http.Request) *Result

MustGetResult get result form http request.Create result if request result does not exist. Return result.

func (*Auth) MustRegisterProvider

func (a *Auth) MustRegisterProvider(keyword string, driver Driver) *Provider

MustRegisterProvider register provider with given keyword and driver. Panic if any error raised. Return provider.

func (*Auth) MustRegisterWithCreator

func (a *Auth) MustRegisterWithCreator(keyword string, creator DriverCreator) *Provider

MustRegisterWithCreator register provider with given keyword and driver creator. Panic if any error raised. Return provider.

func (*Auth) ProviderManager

func (a *Auth) ProviderManager() ProviderManager

ProviderManager return auth service's provider manager. Return MapProviderManager by default.

func (*Auth) RandToken

func (a *Auth) RandToken(length int) ([]byte, error)

RandToken generate random bytes in give length. Return random butes and any error if raised.

func (*Auth) RegisterProvider

func (a *Auth) RegisterProvider(keyword string, driver Driver) (*Provider, error)

RegisterProvider register provider with given keyword and driver. Return provider and any error if raised.

func (*Auth) RegisterWithCreator

func (a *Auth) RegisterWithCreator(keyword string, creator DriverCreator) (*Provider, error)

RegisterWithCreator register provider with given keyword and driver creator. Return provider and any error if raised.

func (*Auth) Serve

func (a *Auth) Serve(SuccessAction func(w http.ResponseWriter, r *http.Request)) func(w http.ResponseWriter, r *http.Request)

Serve serve as http handlerFunc. For example http.StripPrefix("/auth", http.HandlerFunc(Auth.Serve(successAction))) Params SuccessAction action execute after auth success.You should get auth result by Auth.MustGetResult method. Return http.handleFunc

func (*Auth) SetProviderManager

func (a *Auth) SetProviderManager(p ProviderManager)

SetProviderManager auth service's provider manager.

func (*Auth) SetResult

func (a *Auth) SetResult(r *http.Request, result *Result)

SetResult set result into http request.

type ContextName

type ContextName string

ContextName auth result context name type

type Driver

type Driver interface {
	//ExternalLogin action which redirect to login page.
	ExternalLogin(provider *Provider, w http.ResponseWriter, r *http.Request)
	//AuthRequest auth provider response request.
	//Return auth result and any error raised.
	//If auth request params is not correct,error ErrAuthParamsError will be returned.
	AuthRequest(provider *Provider, r *http.Request) (*Result, error)
}

Driver auth provider driver ineterface.

type DriverCreator

type DriverCreator interface {
	Create() Driver
}

DriverCreator driver creator interface.

type MapProviderManager

type MapProviderManager struct {
	Providers map[string]*Provider
}

MapProviderManager provider manager which store providers in map

func NewMapProviderManager

func NewMapProviderManager() *MapProviderManager

NewMapProviderManager create new MapProviderManager

func (*MapProviderManager) GetProvider

func (m *MapProviderManager) GetProvider(a *Auth, keyword string) (*Provider, error)

GetProvider get provider by keyword and auth service return provider and any erros if raised.

func (*MapProviderManager) RegisterProvider

func (m *MapProviderManager) RegisterProvider(a *Auth, keyword string, driver Driver) (*Provider, error)

RegisterProvider register provider with keyword ,auth service and driver. return provider and any erros if raised.

type Option

type Option interface {
	ApplyTo(*Auth) error
}

Option auth option interface

type OptionFunc

type OptionFunc func(*Auth) error

OptionFunc auth option function interface.

func OptionCommon

func OptionCommon(hostpath string, Session Session) OptionFunc

OptionCommon auth service option with given hostpath and session. Params hostpath shold be form "https://www.example.com/auth"

func (OptionFunc) ApplyTo

func (i OptionFunc) ApplyTo(a *Auth) error

ApplyTo apply option function to auth.

type Profile

type Profile map[ProfileIndex][]string

Profile type stores user profile data

func (*Profile) AddValue

func (p *Profile) AddValue(index ProfileIndex, value string)

AddValue add value to profile field.

func (*Profile) SetValue

func (p *Profile) SetValue(index ProfileIndex, value string)

SetValue set string as profile data and clear previous data.

func (*Profile) SetValues

func (p *Profile) SetValues(index ProfileIndex, values []string)

SetValues set string slice as profile data and clear previous data.

func (*Profile) Value

func (p *Profile) Value(index ProfileIndex) string

Value return first data of profile field. if profile is empty,empty string will be returned.

func (*Profile) Values

func (p *Profile) Values(index ProfileIndex) []string

Values return all data of profile field. if profile is empty,nil will be returned.

type ProfileIndex

type ProfileIndex string

ProfileIndex type profile index. You should use ProfileIndex(string) as profile index.

type Provider

type Provider struct {
	//Driver auth driver
	Driver Driver
	//Auth auth service which provider belongs to.
	Auth *Auth
	//Keyword provider keyword.
	Keyword string
}

Provider auth provider mian struct

func (*Provider) AuthRequest

func (p *Provider) AuthRequest(r *http.Request) (*Result, error)

AuthRequest auth provider response request. Return auth result and any error raised. If auth request params is not correct,error ErrAuthParamsError will be returned.

func (*Provider) AuthURL

func (p *Provider) AuthURL() string

AuthURL return provider's auth url.

func (*Provider) Login

func (p *Provider) Login(w http.ResponseWriter, r *http.Request)

Login login action.

func (*Provider) LoginURL

func (p *Provider) LoginURL() string

LoginURL return provider's login url.

type ProviderManager

type ProviderManager interface {
	//GetProvider get provider by keyword and auth service
	//return provider and any erros if raised.
	GetProvider(auth *Auth, keyword string) (*Provider, error)
	//RegisterProvider register provider with keyword ,auth service and driver.
	//return provider and any erros if raised.
	RegisterProvider(auth *Auth, keyword string, driver Driver) (*Provider, error)
}

ProviderManager provider manager interface.

type Result

type Result struct {
	//Account user account
	Account string
	//Keyword keyword of provider which auth the request.
	Keyword string
	//Data user data from auth provider
	Data Profile
}

Result provider auth result

func NewResult

func NewResult() *Result

NewResult create new auth result.

type Session

type Session interface {
	// Set set session by field name with given value.
	Set(r *http.Request, fieldname string, v interface{}) error
	//Get get session by field name with given value.
	Get(r *http.Request, fieldname string, v interface{}) error
	// Del del session value by field name .
	Del(r *http.Request, fieldname string) error
	// IsNotFoundError check if given error is session not found error.
	IsNotFoundError(err error) bool
}

Session session interface