httpbakery

package
v3.0.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 25, 2022 License: LGPL-3.0 Imports: 28 Imported by: 97

Documentation

Index

Constants

View Source 
const (
	// CondClientIPAddr holds the first party caveat condition
	// that checks a client's IP address.
	CondClientIPAddr = "client-ip-addr"

	// CondClientOrigin holds the first party caveat condition that
	// checks a client's origin header.
	CondClientOrigin = "origin"
)
View Source 
const (
	ErrBadRequest                = ErrorCode("bad request")
	ErrDischargeRequired         = ErrorCode("macaroon discharge required")
	ErrInteractionRequired       = ErrorCode("interaction required")
	ErrInteractionMethodNotFound = ErrorCode("discharger does not provide an supported interaction method")
	ErrPermissionDenied          = ErrorCode("permission denied")
)
View Source 
const (
	DefaultAuthnExpiry = 7 * 24 * time.Hour
	DefaultAuthzExpiry = 5 * time.Minute
)

Default expiry times for macaroons created by Oven.Error.

View Source 
const BakeryProtocolHeader = "Bakery-Protocol-Version"

BakeryProtocolHeader is the header that HTTP clients should set to determine the bakery protocol version. If it is 0 or missing, a discharge-required error response will be returned with HTTP status 407; if it is 1, the response will have status 401 with the WWW-Authenticate header set to "Macaroon".

View Source 
const CheckersNamespace = "http"

CheckersNamespace holds the URI of the HTTP checkers schema.

View Source 
const MacaroonsHeader = "Macaroons"

MacaroonsHeader is the key of the HTTP header that can be used to provide a macaroon for request authorization.

View Source 
const PermanentExpiryDuration = 100 * 365 * 24 * time.Hour

PermanentExpiryDuration holds the length of time a cookie holding a macaroon with no time-before caveat will be stored.

View Source 
const WebBrowserInteractionKind = "browser-window"

Variables

View Source 
var AllowInsecureThirdPartyLocator = false

AllowInsecureThirdPartyLocator holds whether ThirdPartyLocator allows insecure HTTP connections for fetching third party information. It is provided for testing purposes and should not be used in production code.

Functions

func ClientIPAddrCaveat 

func ClientIPAddrCaveat(addr net.IP) checkers.Caveat

ClientIPAddrCaveat returns a caveat that will check whether the client's IP address is as provided.

func ClientOriginCaveat 

func ClientOriginCaveat(origin string) checkers.Caveat

ClientOriginCaveat returns a caveat that will check whether the client's Origin header in its HTTP request is as provided.

func ContextWithRequest 

func ContextWithRequest(ctx context.Context, req *http.Request) context.Context

ContextWithRequest returns the context with information from the given request attached as context. This is used by the httpbakery checkers (see RegisterCheckers for details).

func DefaultGetError 

func DefaultGetError(httpResp *http.Response) error

DefaultGetError is the default error unmarshaler used by Client.Do.

func ErrorToResponse 

func ErrorToResponse(ctx context.Context, err error) (int, interface{})

ErrorToResponse returns the HTTP status and an error body to be marshaled as JSON for the given error. This allows a third party package to integrate bakery errors into their error responses when they encounter an error with a *bakery.Error cause.

func IsDischargeError 

func IsDischargeError(err error) bool

IsDischargeError reports whether err is a *DischargeError.

func IsInteractionError 

func IsInteractionError(err error) bool

IsInteractionError reports whether err is an *InteractionError.

func MacaroonsForURL 

func MacaroonsForURL(jar http.CookieJar, u *url.URL) []macaroon.Slice

MacaroonsForURL returns any macaroons associated with the given URL in the given cookie jar.

func NewChecker 

func NewChecker() *checkers.Checker

NewChecker returns a new checker with the standard and HTTP checkers registered in it.

func NewCookie 

func NewCookie(ns *checkers.Namespace, ms macaroon.Slice) (*http.Cookie, error)

NewCookie takes a slice of macaroons and returns them encoded as a cookie. The slice should contain a single primary macaroon in its first element, and any discharges after that.

The given namespace specifies the first party caveat namespace, used for deriving the expiry time of the cookie.

func NewDischargeRequiredError 

func NewDischargeRequiredError(p DischargeRequiredErrorParams) error

NewDischargeRequiredErrorWithVersion returns an error of type *Error that contains a macaroon to the client and acts as a request that the macaroon be discharged to authorize the request.

The client is responsible for discharging the macaroon and storing it as a cookie (or including it as a Macaroon header) to be used for the subsequent request.

func NewHTTPClient 

func NewHTTPClient() *http.Client

NewHTTPClient returns an http.Client that ensures that headers are sent to the server even when the server redirects a GET request. The returned client also contains an empty in-memory cookie jar.

See https://github.com/golang/go/issues/4677

func OpenWebBrowser 

func OpenWebBrowser(url *url.URL) error

OpenWebBrowser opens a web browser at the given URL. If the OS is not recognised, the URL is just printed to standard output.

func RegisterCheckers 

func RegisterCheckers(c *checkers.Checker)

RegisterCheckers registers all the HTTP checkers with the given checker. Current checkers include: 

client-ip-addr <ip-address>

The client-ip-addr caveat checks that the HTTP request has the given remote IP address. 

origin <name>

The origin caveat checks that the HTTP Origin header has the given value.

func RequestMacaroons 

func RequestMacaroons(req *http.Request) []macaroon.Slice

RequestMacaroons returns any collections of macaroons from the header and cookies found in the request. By convention, each slice will contain a primary macaroon followed by its discharges.

func RequestVersion 

func RequestVersion(req *http.Request) bakery.Version

RequestVersion determines the bakery protocol version from a client request. If the protocol cannot be determined, or is invalid, the original version of the protocol is used. If a later version is found, the latest known version is used, which is OK because versions are backwardly compatible.

TODO as there are no known version 0 clients, default to version 1 instead.

func SameClientIPAddrCaveat 

func SameClientIPAddrCaveat(req *http.Request) checkers.Caveat

SameClientIPAddrCaveat returns a caveat that will check that the remote IP address is the same as that in the given HTTP request.

func SetCookie 

func SetCookie(jar http.CookieJar, url *url.URL, ns *checkers.Namespace, ms macaroon.Slice) error

SetCookie sets a cookie for the given URL on the given cookie jar that will holds the given macaroon slice. The macaroon slice should contain a single primary macaroon in its first element, and any discharges after that.

The given namespace specifies the first party caveat namespace, used for deriving the expiry time of the cookie.

func SetLegacyInteraction 

func SetLegacyInteraction(e *Error, visitURL, waitURL string)

SetLegacyInteraction adds information about web-browser-based interaction (or other kinds of legacy-protocol interaction) to the given error, which should be an interaction-required error that's about to be returned from a discharge request.

The visitURL parameter holds a URL that should be visited by the user in a web browser (or with an "Accept: application/json" header to find out the set of legacy interaction methods).

The waitURL parameter holds a URL that can be long-polled to acquire the discharge macaroon.

func SetWebBrowserInteraction 

func SetWebBrowserInteraction(e *Error, visitURL, waitTokenURL string)

SetWebBrowserInteraction adds information about web-browser-based interaction to the given error, which should be an interaction-required error that's about to be returned from a discharge request.

The visitURL parameter holds a URL that should be visited by the user in a web browser; the waitTokenURL parameter holds a URL that can be long-polled to acquire the resulting discharge token.

Use SetLegacyInteraction to add support for legacy clients that don't understand the newer InteractionMethods field.

func ThirdPartyInfoForLocation 

func ThirdPartyInfoForLocation(ctx context.Context, client httprequest.Doer, url string) (bakery.ThirdPartyInfo, error)

ThirdPartyInfoForLocation returns information on the third party discharge server running at the given location URL. Note that this is insecure if an http: URL scheme is used. If client is nil, http.DefaultClient will be used.

func WriteError 

func WriteError(ctx context.Context, w http.ResponseWriter, err error)

WriteError writes the given bakery error to w.

Types

type Client 

type Client struct {
	// Client holds the HTTP client to use. It should have a cookie
	// jar configured, and when redirecting it should preserve the
	// headers (see NewHTTPClient).
	*http.Client

	// InteractionMethods holds a slice of supported interaction
	// methods, with preferred methods earlier in the slice.
	// On receiving an interaction-required error when discharging,
	// the Kind method of each Interactor in turn will be called
	// and, if the error indicates that the interaction kind is supported,
	// the Interact method will be called to complete the discharge.
	InteractionMethods []Interactor

	// Key holds the client's key. If set, the client will try to
	// discharge third party caveats with the special location
	// "local" by using this key. See bakery.DischargeAllWithKey and
	// bakery.LocalThirdPartyCaveat for more information
	Key *bakery.KeyPair

	// Logger is used to log information about client activities.
	// If it is nil, bakery.DefaultLogger("httpbakery") will be used.
	Logger bakery.Logger
}

Client holds the context for making HTTP requests that automatically acquire and discharge macaroons.

func NewClient 

func NewClient() *Client

NewClient returns a new Client containing an HTTP client created with NewHTTPClient and leaves all other fields zero.

func (*Client) AcquireDischarge 

func (c *Client) AcquireDischarge(ctx context.Context, cav macaroon.Caveat, payload []byte) (*bakery.Macaroon, error)

AcquireDischarge acquires a discharge macaroon from the caveat location as an HTTP URL. It fits the getDischarge argument type required by bakery.DischargeAll.

func (*Client) AddInteractor 

func (c *Client) AddInteractor(i Interactor)

AddInteractor is a convenience method that appends the given interactor to c.InteractionMethods. For example, to enable web-browser interaction on a client c, do: 

c.AddInteractor(httpbakery.WebBrowserWindowInteractor)

func (*Client) DischargeAll 

func (c *Client) DischargeAll(ctx context.Context, m *bakery.Macaroon) (macaroon.Slice, error)

DischargeAll attempts to acquire discharge macaroons for all the third party caveats in m, and returns a slice containing all of them bound to m.

If the discharge fails because a third party refuses to discharge a caveat, the returned error will have a cause of type *DischargeError. If the discharge fails because visitWebPage returns an error, the returned error will have a cause of *InteractionError.

The returned macaroon slice will not be stored in the client cookie jar (see SetCookie if you need to do that).

func (*Client) DischargeAllUnbound 

func (c *Client) DischargeAllUnbound(ctx context.Context, ms bakery.Slice) (bakery.Slice, error)

DischargeAllUnbound is like DischargeAll except that it does not bind the resulting macaroons.

func (*Client) Do 

func (c *Client) Do(req *http.Request) (*http.Response, error)

Do is like DoWithContext, except the context is automatically derived. If using go version 1.7 or later the context will be taken from the given request, otherwise context.Background() will be used.

func (*Client) DoWithContext 

func (c *Client) DoWithContext(ctx context.Context, req *http.Request) (*http.Response, error)

DoWithContext sends the given HTTP request and returns its response. If the request fails with a discharge-required error, any required discharge macaroons will be acquired, and the request will be repeated with those attached.

If the required discharges were refused by a third party, an error with a *DischargeError cause will be returned.

If interaction is required by the user, the client's InteractionMethods will be used to perform interaction. An error with a *InteractionError cause will be returned if this interaction fails. See WebBrowserWindowInteractor for a possible implementation of an Interactor for an interaction method.

DoWithContext may add headers to req.Header.

func (*Client) DoWithCustomError 

func (c *Client) DoWithCustomError(req *http.Request, getError func(resp *http.Response) error) (*http.Response, error)

DoWithCustomError is like Do except it allows a client to specify a custom error function, getError, which is called on the HTTP response and may return a non-nil error if the response holds an error. If the cause of the returned error is a *Error value and its code is ErrDischargeRequired, the macaroon in its Info field will be discharged and the request will be repeated with the discharged macaroon. If getError returns nil, it should leave the response body unchanged.

If getError is nil, DefaultGetError will be used.

This method can be useful when dealing with APIs that return their errors in a format incompatible with Error, but the need for it should be avoided when creating new APIs, as it makes the endpoints less amenable to generic tools.

func (*Client) HandleError 

func (c *Client) HandleError(ctx context.Context, reqURL *url.URL, err error) error

HandleError tries to resolve the given error, which should be a response to the given URL, by discharging any macaroon contained in it. That is, if the error cause is an *Error and its code is ErrDischargeRequired, then it will try to discharge err.Info.Macaroon. If the discharge succeeds, the discharged macaroon will be saved to the client's cookie jar and ResolveError will return nil.

For any other kind of error, the original error will be returned.

type DischargeError 

type DischargeError struct {
	// Reason holds the underlying remote error that caused the
	// discharge to fail.
	Reason *Error
}

DischargeError represents the error when a third party discharge is refused by a server.

func (*DischargeError) Error 

func (e *DischargeError) Error() string

type DischargeRequiredErrorParams 

type DischargeRequiredErrorParams struct {
	// Macaroon holds the macaroon that needs to be discharged
	// by the client.
	Macaroon *bakery.Macaroon

	// OriginalError holds the reason that the discharge-required
	// error was created. If it's nil, ErrDischargeRequired will
	// be used.
	OriginalError error

	// CookiePath holds the path for the client to give the cookie
	// holding the discharged macaroon. If it's empty, then a
	// relative path from the request URL path to / will be used if
	// Request is provided, or "/" otherwise.
	CookiePath string

	// CookieNameSuffix holds the suffix for the client
	// to give the cookie holding the discharged macaroon
	// (after the "macaroon-" prefix).
	// If it's empty, "auth" will be used.
	CookieNameSuffix string

	// Request holds the request that the error is in response to.
	// It is used to form the cookie path if CookiePath is empty.
	Request *http.Request
}

type DischargeToken 

type DischargeToken struct {
	// Kind holds the kind of the token. By convention this
	// matches the name of the interaction method used to
	// obtain the token, but that's not required.
	Kind string `json:"kind"`

	// Value holds the value of the token.
	Value []byte `json:"value"`
}

DischargeToken holds a token that is intended to persuade a discharger to discharge a third party caveat.

type Discharger 

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

Discharger represents a third-party caveat discharger. can discharge caveats in an HTTP server.

The name space served by dischargers is as follows. All parameters can be provided either as URL attributes or form attributes. The result is always formatted as a JSON object.

On failure, all endpoints return an error described by the Error type.

POST /discharge 

params:
	id: all-UTF-8 third party caveat id
	id64: non-padded URL-base64 encoded caveat id
	macaroon-id: (optional) id to give to discharge macaroon (defaults to id)
	token: (optional) value of discharge token
	token64: (optional) base64-encoded value of discharge token.
	token-kind: (mandatory if token or token64 provided) discharge token kind.
result on success (http.StatusOK):
	{
		Macaroon *macaroon.Macaroon
	}

GET /publickey 

result:
	public key of service
	expiry time of key

func NewDischarger 

func NewDischarger(p DischargerParams) *Discharger

NewDischarger returns a new third-party caveat discharger using the given parameters.

func (*Discharger) AddMuxHandlers 

func (d *Discharger) AddMuxHandlers(mux *http.ServeMux, rootPath string)

AddMuxHandlers adds handlers to the given ServeMux to provide a third-party caveat discharge service.

func (*Discharger) Handlers 

func (d *Discharger) Handlers() []httprequest.Handler

Handlers returns a slice of handlers that can handle a third-party caveat discharge service when added to an httprouter.Router. TODO provide some way of customizing the context so that ErrorToResponse can see a request-specific context.

type DischargerParams 

type DischargerParams struct {
	// CheckerP is used to actually check the caveats.
	// This will be used in preference to Checker.
	CheckerP ThirdPartyCaveatCheckerP

	// Checker is used to actually check the caveats.
	// This should be considered deprecated and will be ignored if CheckerP is set.
	Checker ThirdPartyCaveatChecker

	// Key holds the key pair of the discharger.
	Key *bakery.KeyPair

	// Locator is used to find public keys when adding
	// third-party caveats on discharge macaroons.
	// If this is nil, no third party caveats may be added.
	Locator bakery.ThirdPartyLocator

	// ErrorToResponse is used to convert errors returned by the third
	// party caveat checker to the form that will be JSON-marshaled
	// on the wire. If zero, this defaults to ErrorToResponse.
	// If set, it should handle errors that it does not understand
	// by falling back to calling ErrorToResponse to ensure
	// that the standard bakery errors are marshaled in the expected way.
	ErrorToResponse func(ctx context.Context, err error) (int, interface{})
}

Discharger holds parameters for creating a new Discharger.

type Error 

type Error struct {
	Code    ErrorCode  `json:",omitempty"`
	Message string     `json:",omitempty"`
	Info    *ErrorInfo `json:",omitempty"`
	// contains filtered or unexported fields
}

Error holds the type of a response from an httpbakery HTTP request, marshaled as JSON.

Note: Do not construct Error values with ErrDischargeRequired or ErrInteractionRequired codes directly - use the NewDischargeRequiredError or NewInteractionRequiredError functions instead.

func NewInteractionRequiredError 

func NewInteractionRequiredError(originalErr error, req *http.Request) *Error

NewInteractionRequiredError returns an error of type *Error that requests an interaction from the client in response to the given request. The originalErr value describes the original error - if it is nil, a default message will be provided.

This function should be used in preference to creating the Error value directly, as it sets the bakery protocol version correctly in the error.

The returned error does not support any interaction kinds. Use kind-specific SetInteraction methods (for example WebBrowserInteractor.SetInteraction) to add supported interaction kinds.

Note that WebBrowserInteractor.SetInteraction should always be called for legacy clients to maintain backwards compatibility.

func (*Error) Error 

func (e *Error) Error() string

func (*Error) ErrorCode 

func (e *Error) ErrorCode() ErrorCode

func (*Error) ErrorInfo 

func (e *Error) ErrorInfo() *ErrorInfo

ErrorInfo returns additional information about the error. TODO return interface{} here?

func (*Error) InteractionMethod 

func (e *Error) InteractionMethod(kind string, x interface{}) error

InteractionMethod checks whether the error is an InteractionRequired error that implements the method with the given name, and JSON-unmarshals the method-specific data into x.

func (*Error) SetInteraction 

func (e *Error) SetInteraction(kind string, v interface{})

SetInteraction sets the information for a particular interaction kind to v. The error should be an interaction-required error. This method will panic if v cannot be JSON-marshaled. It is expected that interaction implementations will implement type-safe wrappers for this method, so you should not need to call it directly.

type ErrorCode 

type ErrorCode string

ErrorCode holds an error code that classifies an error returned from a bakery HTTP handler.

func (ErrorCode) Error 

func (e ErrorCode) Error() string

func (ErrorCode) ErrorCode 

func (e ErrorCode) ErrorCode() ErrorCode

type ErrorInfo 

type ErrorInfo struct {
	// Macaroon may hold a macaroon that, when
	// discharged, may allow access to a service.
	// This field is associated with the ErrDischargeRequired
	// error code.
	Macaroon *bakery.Macaroon `json:",omitempty"`

	// MacaroonPath holds the URL path to be associated
	// with the macaroon. The macaroon is potentially
	// valid for all URLs under the given path.
	// If it is empty, the macaroon will be associated with
	// the original URL from which the error was returned.
	MacaroonPath string `json:",omitempty"`

	// CookieNameSuffix holds the desired cookie name suffix to be
	// associated with the macaroon. The actual name used will be
	// ("macaroon-" + CookieName). Clients may ignore this field -
	// older clients will always use ("macaroon-" +
	// macaroon.Signature() in hex).
	CookieNameSuffix string `json:",omitempty"`

	// InteractionMethods holds the set of methods that the
	// third party supports for completing the discharge.
	// See InteractionMethod for a more convenient
	// accessor method.
	InteractionMethods map[string]*json.RawMessage `json:",omitempty"`

	// LegacyVisitURL holds a URL that the client should visit
	// in a web browser to authenticate themselves.
	// This is deprecated - it is superceded by the InteractionMethods
	// field.
	LegacyVisitURL string `json:"VisitURL,omitempty"`

	// LegacyWaitURL holds a URL that the client should visit
	// to acquire the discharge macaroon. A GET on
	// this URL will block until the client has authenticated,
	// and then it will return the discharge macaroon.
	// This is deprecated - it is superceded by the InteractionMethods
	// field.
	LegacyWaitURL string `json:"WaitURL,omitempty"`
}

ErrorInfo holds additional information provided by an error.

type InteractionError 

type InteractionError struct {
	// Reason holds the actual error returned from visitWebPage.
	Reason error
}

InteractionError wraps an error returned by a call to visitWebPage.

func (*InteractionError) Error 

func (e *InteractionError) Error() string

type Interactor 

type Interactor interface {
	// Kind returns the interaction method name. This corresponds to the
	// key in the Error.InteractionMethods type.
	Kind() string

	// Interact performs the interaction, and returns a token that can be
	// used to acquire the discharge macaroon. The location provides
	// the third party caveat location to make it possible to use
	// relative URLs.
	//
	// If the given interaction isn't supported by the client for
	// the given location, it may return an error with an
	// ErrInteractionMethodNotFound cause which will cause the
	// interactor to be ignored that time.
	Interact(ctx context.Context, client *Client, location string, interactionRequiredErr *Error) (*DischargeToken, error)
}

An Interactor represents a way of persuading a discharger that it should grant a discharge macaroon.

type LegacyInteractor 

type LegacyInteractor interface {
	// LegacyInteract implements the "visit" half of a legacy discharge
	// interaction. The "wait" half will be implemented by httpbakery.
	// The location is the location specified by the third party
	// caveat.
	LegacyInteract(ctx context.Context, client *Client, location string, visitURL *url.URL) error
}

LegacyInteractor may optionally be implemented by Interactor implementations that implement the legacy interaction-required error protocols.

type Oven 

type Oven struct {
	// Oven holds the bakery Oven used to create
	// new macaroons to put in discharge-required errors.
	*bakery.Oven

	// AuthnExpiry holds the expiry time of macaroons that
	// are created for authentication. As these are generally
	// applicable to all endpoints in an API, this is usually
	// longer than AuthzExpiry. If this is zero, DefaultAuthnExpiry
	// will be used.
	AuthnExpiry time.Duration

	// AuthzExpiry holds the expiry time of macaroons that are
	// created for authorization. As these are generally applicable
	// to specific operations, they generally don't need
	// a long lifespan, so this is usually shorter than AuthnExpiry.
	// If this is zero, DefaultAuthzExpiry will be used.
	AuthzExpiry time.Duration
}

Oven is like bakery.Oven except it provides a method for translating errors returned by bakery.AuthChecker into errors suitable for passing to WriteError.

func (*Oven) Error 

func (oven *Oven) Error(ctx context.Context, req *http.Request, err error) error

Error processes an error as returned from bakery.AuthChecker into an error suitable for returning as a response to req with WriteError.

Specifically, it translates bakery.ErrPermissionDenied into ErrPermissionDenied and bakery.DischargeRequiredError into an Error with an ErrDischargeRequired code, using oven.Oven to mint the macaroon in it.

type ThirdPartyCaveatChecker 

type ThirdPartyCaveatChecker interface {
	// CheckThirdPartyCaveat is like ThirdPartyCaveatCheckerP.CheckThirdPartyCaveat
	// except that it uses separate arguments instead of a struct arg.
	CheckThirdPartyCaveat(ctx context.Context, info *bakery.ThirdPartyCaveatInfo, req *http.Request, token *DischargeToken) ([]checkers.Caveat, error)
}

ThirdPartyCaveatChecker is used to check third party caveats. This interface is deprecated and included only for backward compatibility; ThirdPartyCaveatCheckerP should be used instead.

type ThirdPartyCaveatCheckerFunc 

type ThirdPartyCaveatCheckerFunc func(ctx context.Context, req *http.Request, info *bakery.ThirdPartyCaveatInfo, token *DischargeToken) ([]checkers.Caveat, error)

ThirdPartyCaveatCheckerFunc implements ThirdPartyCaveatChecker by calling a function.

func (ThirdPartyCaveatCheckerFunc) CheckThirdPartyCaveat 

func (f ThirdPartyCaveatCheckerFunc) CheckThirdPartyCaveat(ctx context.Context, info *bakery.ThirdPartyCaveatInfo, req *http.Request, token *DischargeToken) ([]checkers.Caveat, error)

type ThirdPartyCaveatCheckerP 

type ThirdPartyCaveatCheckerP interface {
	// CheckThirdPartyCaveat is used to check whether a client
	// making the given request should be allowed a discharge for
	// the p.Info.Condition. On success, the caveat will be discharged,
	// with any returned caveats also added to the discharge
	// macaroon.
	//
	// The p.Token field, if non-nil, is a token obtained from
	// Interactor.Interact as the result of a discharge interaction
	// after an interaction required error.
	//
	// Note than when used in the context of a discharge handler
	// created by Discharger, any returned errors will be marshaled
	// as documented in DischargeHandler.ErrorMapper.
	CheckThirdPartyCaveat(ctx context.Context, p ThirdPartyCaveatCheckerParams) ([]checkers.Caveat, error)
}

ThirdPartyCaveatCheckerP is used to check third party caveats. The "P" stands for "Params" - this was added after ThirdPartyCaveatChecker which can't be removed without breaking backwards compatibility.

type ThirdPartyCaveatCheckerPFunc 

type ThirdPartyCaveatCheckerPFunc func(ctx context.Context, p ThirdPartyCaveatCheckerParams) ([]checkers.Caveat, error)

ThirdPartyCaveatCheckerPFunc implements ThirdPartyCaveatCheckerP by calling a function.

func (ThirdPartyCaveatCheckerPFunc) CheckThirdPartyCaveat 

func (f ThirdPartyCaveatCheckerPFunc) CheckThirdPartyCaveat(ctx context.Context, p ThirdPartyCaveatCheckerParams) ([]checkers.Caveat, error)

type ThirdPartyCaveatCheckerParams 

type ThirdPartyCaveatCheckerParams struct {
	// Caveat holds information about the caveat being discharged.
	Caveat *bakery.ThirdPartyCaveatInfo

	// Token holds the discharge token provided by the client, if any.
	Token *DischargeToken

	// Req holds the HTTP discharge request.
	Request *http.Request

	// Response holds the HTTP response writer. Implementations
	// must not call its WriteHeader or Write methods.
	Response http.ResponseWriter
}

ThirdPartyCaveatCheckerParams holds the parameters passed to CheckThirdPartyCaveatP.

type ThirdPartyLocator 

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

ThirdPartyLocator represents locator that can interrogate third party discharge services for information. By default it refuses to use insecure URLs.

func NewThirdPartyLocator 

func NewThirdPartyLocator(client httprequest.Doer, cache *bakery.ThirdPartyStore) *ThirdPartyLocator

NewThirdPartyLocator returns a new third party locator that uses the given client to find information about third parties and uses the given cache as a backing.

If cache is nil, a new cache will be created.

If client is nil, http.DefaultClient will be used.

func (*ThirdPartyLocator) AllowInsecure 

func (kr *ThirdPartyLocator) AllowInsecure()

AllowInsecure allows insecure URLs. This can be useful for testing purposes. See also AllowInsecureThirdPartyLocator.

func (*ThirdPartyLocator) ThirdPartyInfo 

func (kr *ThirdPartyLocator) ThirdPartyInfo(ctx context.Context, loc string) (bakery.ThirdPartyInfo, error)

ThirdPartyLocator implements bakery.ThirdPartyLocator by first looking in the backing cache and, if that fails, making an HTTP request to find the information associated with the given discharge location.

It refuses to fetch information from non-HTTPS URLs.

type WaitResponse 

type WaitResponse struct {
	Macaroon *bakery.Macaroon
}

WaitResponse holds the type that should be returned by an HTTP response made to a LegacyWaitURL (See the ErrorInfo type).

type WaitTokenResponse 

type WaitTokenResponse struct {
	Kind string `json:"kind"`
	// Token holds the token value when it's well-formed utf-8
	Token string `json:"token,omitempty"`
	// Token64 holds the token value, base64 encoded, when it's
	// not well-formed utf-8.
	Token64 string `json:"token64,omitempty"`
}

WaitTokenResponse holds the response type returned, JSON-encoded, from the waitToken URL passed to SetBrowserInteraction.

type WebBrowserInteractionInfo 

type WebBrowserInteractionInfo struct {
	// VisitURL holds the URL to be visited in a web browser.
	VisitURL string

	// WaitTokenURL holds a URL that will block on GET
	// until the browser interaction has completed.
	// On success, the response is expected to hold a waitTokenResponse
	// in its body holding the token to be returned from the
	// Interact method.
	WaitTokenURL string
}

WebBrowserInteractionInfo holds the information expected in the browser-window interaction entry in an interaction-required error.

type WebBrowserInteractor 

type WebBrowserInteractor struct {
	// OpenWebBrowser is used to visit a page in
	// the user's web browser. If it's nil, the
	// OpenWebBrowser function will be used.
	OpenWebBrowser func(*url.URL) error
}

WebBrowserInteractor handls web-browser-based interaction-required errors by opening a web browser to allow the user to prove their credentials interactively.

It implements the Interactor interface, so instances can be used with Client.AddInteractor.

func (WebBrowserInteractor) Interact 

func (wi WebBrowserInteractor) Interact(ctx context.Context, client *Client, location string, irErr *Error) (*DischargeToken, error)

Interact implements Interactor.Interact by opening a new web page.

func (WebBrowserInteractor) Kind 

func (WebBrowserInteractor) Kind() string

Kind implements Interactor.Kind.

func (WebBrowserInteractor) LegacyInteract 

func (wi WebBrowserInteractor) LegacyInteract(ctx context.Context, client *Client, location string, visitURL *url.URL) error

LegacyInteract implements LegacyInteractor by opening a web browser page.

Source Files

View all Source files

Directories

Path Synopsis
Package agent enables non-interactive (agent) login using macaroons.
 Package agent enables non-interactive (agent) login using macaroons.
Package form enables interactive login without using a web browser.
 Package form enables interactive login without using a web browser.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.