grants

README

grants

The grants package encapsulates the part of the auth system that handles authentication requests and turns them into sessions.

Put another way, it handles the "login" requests from users and calls through to the appropriate other pieces of the auth system to log the user in.

Implementation

Grants consist of an ID, a source type, a source ID, the scopes they cover, the profile they're for, and some metadata. The source type and source ID are used to avoid reuse attacks; the combination of source ID and source type must be unique amongst all grants. The source ID is meaningful only within the context of that specific grant type; they are opaque within the system as a whole.

Place in the Architecture

When a user first logs in, they create a grant request. For example, when authenticating with an email address, a grant is created with the grant type "email" and a uniquely generated grant ID. The user then clicks the link in their email, which contains the grant ID, which the grants service uses to create a session. For the Google OpenID login flow, there's only one step: pass an ID token from Google, so the grant type is "google_id", and the grant ID is an encoding of some uniquely identifying information from the ID token.

Once a grant is obtained, it can be exchanged for a session.

Scope

grants is solely responsible for managing the various login methods, verifying and validating them, and converting them into a unified representation in the system. The HTTP handlers it provides are responsible for verifying the authentication and authorization of the requests made against it, which will be coming from untrusted sources.

The questions grants is meant to answer for the system include:

• Is this a valid authentication request?
• What scopes should the session have?
• How did a session get created?

The things grants is explicitly not expected to do include:

• Manage valid scopes.
• Manage the mapping of login methods to profile IDs.
• Serve as anything more than an audit log of authentications.

Documentation

Index

• Variables
• type Dependencies
• type Grant
  • func FillGrantDefaults(grant Grant) (Grant, error)
• type GrantUse
• type Storer

Variables

var (
	// ErrGrantAlreadyUsed is returned when a grant is being used, but has already been used. This
	// usually indicates a replay attack.
	ErrGrantAlreadyUsed = errors.New("grant already used, cannot be exchanged again")
	// ErrGrantNotFound is returned when a grant is being used or referenced, but does not exist in
	// the Storer being used. This usually indicates an invalid Grant is being presented.
	ErrGrantNotFound = errors.New("grant not found")
	// ErrGrantAlreadyExists is returned when a grant is being stored in a Storer, but a grant with
	// the same ID alredy exists in that Storer. This usually indicates a programming error.
	ErrGrantAlreadyExists = errors.New("grant with that ID already exists")
	// ErrGrantSourceAlreadyUsed is returned when a grant is being stored in a Storer, but the source
	// of the Grant has already been used in that Storer. This usually indicates a replay attack.
	ErrGrantSourceAlreadyUsed = errors.New("grant source already used to generate a grant, cannot be used to create another grant")
)

Types

type Dependencies

type Dependencies struct {
	Storer Storer // the Storer to store Grants in
}

Dependencies bundles together the information needed to run the service.

type Grant

type Grant struct {
	ID         string    // a unique ID
	SourceType string    // the type of the source used to identify the user
	SourceID   string    // the ID of the source used to identify the user; should be unique across grants
	CreatedAt  time.Time // when the authorization was granted
	UsedAt     time.Time // when the authorization was exchanged for a session
	Scopes     []string  // the scopes of access the user granted
	AccountID  string    // the ID of the account that was used to grant access
	ProfileID  string    // the unique ID representing the user
	ClientID   string    // the client access was granted to
	CreateIP   string    // the IP the user granted access from
	UseIP      string    // the IP the access was exchanged for a session from
	Used       bool      // whether the access has been exchanged for a session or not
}

Grant represents a user's authorization for the use of their account to some client.

func FillGrantDefaults

func FillGrantDefaults(grant Grant) (Grant, error)

FillGrantDefaults sets any unset fields of Grant that have a default value. Fields that are set and fields that have no default value are not modified. The original Grant is not modified; a shallow copy is made and modified, then returned.

type GrantUse

type GrantUse struct {
	Grant string    // the ID of the grant that was exchanged
	IP    string    // the IP address the exchange was initiated from
	Time  time.Time // the time the exchange happened
}

GrantUse represents the exchange of a Grant for a session.

type Storer

type Storer interface {
	CreateGrant(ctx context.Context, g Grant) error
	ExchangeGrant(ctx context.Context, g GrantUse) (Grant, error)
	GetGrant(ctx context.Context, id string) (Grant, error)
	GetGrantBySource(ctx context.Context, sourceType, sourceID string) (Grant, error)
}

Storer is the interface that Grants are persisted and used through.