agent

Documentation

Overview

Package agent enables non-interactive (agent) login using macaroons. To enable agent authorization with a given httpbakery.Client c against a given third party discharge server URL u:

SetUpAuth(c, u, agentUsername)

Index

• Variables
• func LoginCookie(req *http.Request) (username string, key *bakery.PublicKey, err error)
• func SetInteraction(e *httpbakery.Error, loginURL string)
• func SetUpAuth(client *httpbakery.Client, authInfo *AuthInfo) error
• type Agent
• type AuthInfo
  • func AuthInfoFromEnvironment() (*AuthInfo, error)
• type InteractionInfo
• type LegacyAgentLoginBody
• type LegacyAgentResponse

Examples

• SetUpAuth

Variables

var ErrNoAgentLoginCookie = errgo.New("no agent-login cookie found")

ErrNoAgentLoginCookie is the error returned when the expected agent login cookie has not been found.

var ErrNoAuthInfo = errgo.New("no bakery agent info found in environment")

Functions

func LoginCookie

func LoginCookie(req *http.Request) (username string, key *bakery.PublicKey, err error)

LoginCookie returns details of the agent login cookie from the given request. If no agent-login cookie is found, it returns an ErrNoAgentLoginCookie error.

This function is only applicable to the legacy agent protocol and will be deprecated in the future.

func SetInteraction

func SetInteraction(e *httpbakery.Error, loginURL string)

SetInteraction sets agent interaction information on the given error, which should be an interaction-required error to be returned from a discharge request.

The given URL (which may be relative to the discharger location) will be the subject of a GET request by the client to fetch the agent macaroon that, when discharged, can act as the discharge token.

func SetUpAuth

func SetUpAuth(client *httpbakery.Client, authInfo *AuthInfo) error

SetUpAuth sets up agent authentication on the given client. If this is called several times on the same client, earlier calls will take precedence over later calls when there's a URL and username match for both.

Example

package main

import (
	"github.com/go-macaroon-bakery/macaroon-bakery/v3/bakery"
	"github.com/go-macaroon-bakery/macaroon-bakery/v3/httpbakery"
	"github.com/go-macaroon-bakery/macaroon-bakery/v3/httpbakery/agent"
)

func main() {
	// In practice the key would be read from persistent
	// storage.
	key, err := bakery.GenerateKey()
	if err != nil {
		// handle error
	}

	client := httpbakery.NewClient()
	err = agent.SetUpAuth(client, &agent.AuthInfo{
		Key: key,
		Agents: []agent.Agent{{
			URL:      "http://foo.com",
			Username: "agent-username",
		}},
	})
	if err != nil {
		// handle error
	}
}

Types

type Agent

type Agent struct {
	// URL holds the URL associated with the agent.
	URL string `json:"url" yaml:"url"`
	// Username holds the username to use for the agent.
	Username string `json:"username" yaml:"username"`
}

Agent represents an agent that can be used for agent authentication.

type AuthInfo

type AuthInfo struct {
	Key    *bakery.KeyPair `json:"key,omitempty" yaml:"key,omitempty"`
	Agents []Agent         `json:"agents" yaml:"agents"`
}

AuthInfo holds the agent information required to set up agent authentication information. It holds the agent's private key and information about the username associated with each known agent-authentication server.

func AuthInfoFromEnvironment

func AuthInfoFromEnvironment() (*AuthInfo, error)

AuthInfoFromEnvironment returns an AuthInfo derived from environment variables.

It recognizes the following variable: BAKERY_AGENT_FILE - path to a file containing agent authentication

info in JSON format (as marshaled by the AuthInfo type).

If BAKERY_AGENT_FILE is not set, ErrNoAuthInfo will be returned.

type InteractionInfo

type InteractionInfo struct {
	// LoginURL holds the URL from which to acquire
	// a macaroon that can be used to complete the agent
	// login. To acquire the macaroon, make a POST
	// request to the URL with user and public-key
	// parameters.
	LoginURL string `json:"login-url"`
}

InteractionInfo holds the information expected in the agent interaction entry in an interaction-required error.

type LegacyAgentLoginBody

type LegacyAgentLoginBody struct {
	Username  string            `json:"username"`
	PublicKey *bakery.PublicKey `json:"public_key"`
}

LegacyAgentLoginBody is used to encode the JSON body sent when making a legacy agent protocol POST request to the visit URL.

type LegacyAgentResponse

type LegacyAgentResponse struct {
	AgentLogin bool `json:"agent_login"`
}

LegacyAgentResponse contains the response to a legacy agent login attempt.