candid

README

Candid Identity service

The Candid server provides a macaroon-based authentication service.

Installation

The easiest way to start using the candid service is with the snap:

snap install candid --edge

The configuration file used by the snap can be found in /var/snap/candid/current/config.yaml.

Development

Requirements

Candid requires go1.11 or later to build. This is available in the go snap:

snap install go

Go will additionally require installing the following packages in order that it can fetch and build candid dependencies:

apt install build-essential bzr git

Source

Get the source from github.com/CanoniclaLtd/candid.

git clone git@github.com:CanonicalLtd/candid

It is recommended that you check out the source outside of any $GOPATH ($HOME/go by default). If you do wish to check out into a $GOPATH then you will need to set the environment variable GO111MODULE=on.

Testing

The store/mgostore component additionally requires mongodb to be installed, this should be installed from the system packages:

apt install mongodb

The store/sqlstore component additionally requires a running postgresql, this may be running on a different system. The posgresql system to use is specified using the standard postgresql environment variables. To skip running postgresql tests set the environment variable PGTESTDISABLE=1.

Tests are run by running make check in the root of the source tree. The tests for a single package can be run by running go test in the package directory.

Documentation

Index

• Constants
• func Versions() []string
• type HandlerCloser
  • func NewServer(params ServerParams, serveVersions ...string) (HandlerCloser, error)
• type ServerParams

Constants

const (
	Debug      = "debug"
	Discharger = "discharger"
	V1         = "v1"
)

Versions of the API that can be served.

Functions

func Versions

func Versions() []string

Versions returns all known API version strings in alphabetical order.

Types

type HandlerCloser

type HandlerCloser interface {
	http.Handler
	Close()
}

func NewServer

func NewServer(params ServerParams, serveVersions ...string) (HandlerCloser, error)

NewServer returns a new handler that handles identity service requests and stores its data in the given database. The handler will serve the specified versions of the API.

type ServerParams

type ServerParams struct {
	// MeetingStore holds the storage that will be used to store
	// rendezvous information.
	MeetingStore meeting.Store

	// ProviderDataStore holds the storeage that can be used by
	// identity providers to store data that is not associated with
	// an individual identity.
	ProviderDataStore store.ProviderDataStore

	// RootKeyStore holds the root key store that will be used to
	// store macaroon root keys within the identity server.
	RootKeyStore bakery.RootKeyStore

	// Store holds the identities store for the identity server.
	Store store.Store

	// AdminPassword holds the password for admin login.
	AdminPassword string

	// Key holds the keypair to use with the bakery service.
	Key *bakery.KeyPair

	// Location holds a URL representing the externally accessible
	// base URL of the service, without a trailing slash.
	Location string

	// PrivateAddr should hold a dialable address that will be used
	// for communication between identity servers. Note that this
	// should not contain a port.
	PrivateAddr string

	// IdentityProviders contains the set of identity providers that
	// should be initialised by the service.
	IdentityProviders []idp.IdentityProvider

	// DebugTeams contains the set of launchpad teams that may access
	// the restricted debug endpoints.
	// TODO remove this.
	DebugTeams []string

	// AdminAgentPublicKey contains the public key of the admin agent.
	AdminAgentPublicKey *bakery.PublicKey

	// StaticFileSystem contains an http.FileSystem that can be used
	// to serve static files.
	StaticFileSystem http.FileSystem

	// Template contains a set of templates that are used to generate
	// html output.
	Template *template.Template

	// DebugStatusCheckerFuncs contains functions that will be
	// executed as part of a /debug/status check.
	DebugStatusCheckerFuncs []debugstatus.CheckerFunc

	// RendezvousTimeout holds the time after which an interactive discharge wait
	// request will time out.
	RendezvousTimeout time.Duration

	// ACLStore holds the ACLStore for the identity server.
	ACLStore aclstore.ACLStore

	// RedirectLoginWhitelist contains a list of URLs that are
	// trusted to be used as return_to URLs during an interactive
	// login.
	RedirectLoginWhitelist []string

	// APIMacaroonTimeout is the maximum life of an API macaroon.
	APIMacaroonTimeout time.Duration

	// DischargeMacaroonTimeout is the maximum life of a Discharge
	// macaroon.
	DischargeMacaroonTimeout time.Duration

	// DischargeTokenTimeout is the maximum life of a Discharge
	// token.
	DischargeTokenTimeout time.Duration
}

ServerParams contains configuration parameters for a server.