delegation

Documentation

Overview

Package delegation contains low-level API for working with delegation tokens.

Prefer the high-level API in server/auth package, in particular `MintDelegationToken` and `auth.GetRPCTransport(ctx, auth.AsUser)`.

Index

• Constants
• Variables
• func CheckToken(c context.Context, params CheckTokenParams) (identity.Identity, error)
• type CertificatesProvider
• type CheckTokenParams
• type GroupsChecker
• type Token

Constants

const (
	// HTTPHeaderName is name of HTTP header that carries the token.
	HTTPHeaderName = "X-Delegation-Token-V1"
)

Variables

var (
	// ErrMalformedDelegationToken is returned when delegation token cannot be
	// deserialized.
	ErrMalformedDelegationToken = errors.New("auth: malformed delegation token")

	// ErrUnsignedDelegationToken is returned if token's signature cannot be
	// verified.
	ErrUnsignedDelegationToken = errors.New("auth: unsigned delegation token")

	// ErrForbiddenDelegationToken is returned if token is structurally correct,
	// but some of its constraints prevents it from being used. For example, it is
	// already expired or it was minted for some other services, etc. See logs for
	// details.
	ErrForbiddenDelegationToken = errors.New("auth: forbidden delegation token")
)

Functions

func CheckToken

func CheckToken(c context.Context, params CheckTokenParams) (identity.Identity, error)

CheckToken verifies validity of a delegation token.

If the token is valid, it returns the delegated identity (embedded in the token).

May return transient errors.

Types

type CertificatesProvider

type CertificatesProvider interface {
	// GetCertificates returns a bundle with certificates of a trusted signer.
	//
	// Returns (nil, nil) if the given signer is not trusted.
	//
	// Returns errors (usually transient) if the bundle can't be fetched.
	GetCertificates(c context.Context, id identity.Identity) (*signing.PublicCertificates, error)
}

CertificatesProvider is used by 'CheckToken', it is implemented by authdb.DB.

It returns certificates of services trusted to sign tokens.

type CheckTokenParams

type CheckTokenParams struct {
	Token                string               // the delegation token to check
	PeerID               identity.Identity    // identity of the caller, as extracted from its credentials
	CertificatesProvider CertificatesProvider // returns certificates with trusted keys
	GroupsChecker        GroupsChecker        // knows how to do group lookups
	OwnServiceIdentity   identity.Identity    // identity of the current service
}

CheckTokenParams is passed to CheckToken.

type GroupsChecker

type GroupsChecker interface {
	// IsMember returns true if the given identity belongs to any of the groups.
	//
	// Unknown groups are considered empty. May return errors if underlying
	// datastore has issues.
	IsMember(c context.Context, id identity.Identity, groups []string) (bool, error)
}

GroupsChecker is accepted by 'CheckToken', it is implemented by authdb.DB.

type Token

type Token struct {
	// base64-encoded URL-safe blob with the token
	Token string `json:"token,omitempty"`
	// UTC time when it expires
	Expiry jsontime.Time `json:"expiry,omitempty"`
}

Token represents serialized and signed delegation token.