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

                                                                                                                            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

                                                                                                                                                  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.

                                                                                                                                                    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.