auth

README

api2go-auth

This package simplifies the task of adding authentication to an application using api2go.

Features

Here are some of the features that api2go-auth provides:

• Provides methods for login and logout
• Ensures all API methods are authenticated
• Enables full customization of the authentication process

Server Usage

To use api2go-auth, you must first create a type that implements Authenticator. In the following example, user credentials are stored in a database:

type UserAuth struct {}

func (u *UserAuth) Authenticate(r *http.Request) (interface{}, interface{}, error) {
    u, err := isValidUser(r)
    if err != nil {
        return nil, nil, err
    }
    return u.ID, u, err
}

func (u *UserAuth) Initialize(r *http.Request, i interface{}) (*http.Request, error) {
    u, err := fetchUser(i)
    if err != nil {
        return nil, err
    }
    return r.WithContext(
        context.WithValue(r.Context(), "user", u)
    ), nil
}

The Authenticate() method is invoked when the client attempts to login. Assuming valid credentials are supplied, the method returns both a unique identifier for the user as well as the user object itself (which will be sent to the client).

The Initialize() method is invoked before each API request. It loads the user object from the unique identifier (which was returned in Authenticate()) and adds a variable to the request context so that it can be used by data sources.

The next step is to simply create an Auth instance:

var (
    api = api2go.NewAPI("api")
    h   = auth.New(api, &UserAuth{}, nil)
)

h can then be used as an HTTP handler.

Client Usage

Clients must log in my sending a POST request to the /login endpoint and including the data expected by Authenticate (a username and password, for example). If successful, the data returned by Authenticate will be send to the client in JSONAPI format. A cookie will be set that authenticates future requests.

When a session is ready to be ended, the client may send a POST request to /logout to destroy the session.

Documentation

Index

• type Auth
  • func New(api *api2go.API, authenticator Authenticator, secretKey []byte) *Auth
  • func (a *Auth) ServeHTTP(w http.ResponseWriter, r *http.Request)
• type Authenticator

Types

type Auth

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

Auth provides a handler to authenticate requests. In addition to serving the routes provided by the API, two additional routes are added for logging in and logging out.

func New

func New(api *api2go.API, authenticator Authenticator, secretKey []byte) *Auth

New creates a new handler for the provided API using the provided authenticator for requests. The secret key allows for persistent sessions and may be set to nil to disable the feature.

func (*Auth) ServeHTTP

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

ServeHTTP responds to requests for API resources.

type Authenticator

type Authenticator interface {

	// Authenticate determines if the request represents a valid login attempt.
	// The first return value is a unique identifier stored with the session
	// and used for initializing requests. This value should be set to nil if
	// the provided credentials are invalid or insufficient. The second return
	// value is encoded as JSON and returned to the client. The third return
	// value is used if an error occurs during authentication.
	Authenticate(r *http.Request) (interface{}, interface{}, error)

	// Initialize prepares an authenticated request for processing. Typically,
	// this involves setting a value on the request's context based on the
	// provided session object (returned by Authenticate). The request is not
	// processed further if an error is returned.
	Initialize(r *http.Request, i interface{}) (*http.Request, error)
}

Authenticator provides methods for authenticating requests.