admin

Documentation

Overview

Package admin is how the console reaches fileshare servers: their admin API (fileshare.admin.v1.AdminService, over Connect), and who is logged in.

In a browser it goes through go-fileshare/portal, which holds the tokens: the console sends its calls to /api/<server>/..., with the session cookie the browser adds and the static header the portal requires, and never sees a token.

Index

• Constants
• Variables
• type Backend
• type Direct
  • func NewDirect(cfg DirectConfig, open func(string) error, hc *http.Client) (*Direct, error)
  • func (d *Direct) Client(server string) adminv1connect.AdminServiceClient
  • func (d *Direct) LoginURL(string) string
  • func (d *Direct) Logout(context.Context) (string, error)
  • func (d *Direct) Session(ctx context.Context) (*Session, error)
• type DirectConfig
• type DirectServer
• type Portal
  • func NewPortal(base string, hc *http.Client, serialize func(func() error) error) *Portal
  • func (p *Portal) Client(server string) adminv1connect.AdminServiceClient
  • func (p *Portal) LoginURL(returnTo string) string
  • func (p *Portal) Logout(ctx context.Context) (string, error)
  • func (p *Portal) Session(ctx context.Context) (*Session, error)
• type Server
  • func (s Server) Name() string
• type Session
  • func (s *Session) Who() string

Constants

const LoginAgain = "native:login"

LoginAgain is what LoginURL returns: the native console has no page to go to, it logs in again.

const MaxInUse = 5

MaxInUse is how many servers' tokens one refresh asks for: the ones most recently used. The portal keeps its session in cookies, and a browser sends those on one header line that a load balancer bounds (8 KiB at nginx's default); five tokens of about 1 KB fit. Calling a sixth server makes the least recently used one ask again when it is next called.

Variables

var ErrNotLoggedIn = errors.New("not logged in")

ErrNotLoggedIn is the answer when there is no session, or it has ended.

Types

type Backend

type Backend interface {
	Session(ctx context.Context) (*Session, error)
	// Client is the admin API of one server.
	Client(server string) adminv1connect.AdminServiceClient
	// Logout ends the session, and returns where the browser should go
	// next to end it at the identity provider too ("" if nowhere).
	Logout(ctx context.Context) (string, error)
	// LoginURL is where to send a browser that has no session.
	LoginURL(returnTo string) string
}

A Backend is what the console needs.

type Direct

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

Direct is a Backend that logs in itself -- through the system browser and a loopback listener (go-authn/rp, RFC 8252) -- and calls each server with a token addressed to it alone. The refresh token stays in this process's memory, and one refresh runs at a time: the provider rotates a public client's refresh tokens and ends the login when one is spent twice.

func NewDirect

func NewDirect(cfg DirectConfig, open func(string) error, hc *http.Client) (*Direct, error)

NewDirect is a Backend over cfg. open shows a URL to the person -- the system browser (rp.OpenBrowser).

func (*Direct) Client

func (d *Direct) Client(server string) adminv1connect.AdminServiceClient

Client is the admin API of server, called directly with its own token.

func (*Direct) LoginURL

func (d *Direct) LoginURL(string) string

LoginURL is LoginAgain: there is no page to send a native app to.

func (*Direct) Logout

func (d *Direct) Logout(context.Context) (string, error)

Logout forgets the login, and returns where to end the session at the provider, if it says.

func (*Direct) Session

func (d *Direct) Session(ctx context.Context) (*Session, error)

Session logs in, the first time, and says who and which servers.

type DirectConfig

type DirectConfig struct {
	Issuer   string
	ClientID string // a PUBLIC client: no secret (RFC 8252 §8.5)
	Scopes   []string
	Servers  []DirectServer
}

DirectConfig is what a native console needs to reach servers on its own, without a portal: where to log in, and the servers.

type DirectServer

type DirectServer struct {
	ID, Label string
	URL       string // the admin block's web listener
	Issuer    string
	Resource  string // RFC 8707: the token's audience, the server's issuer audience
	Scope     string // for a provider that sets the audience from a scope
	CAFile    string // when its certificate is not publicly trusted
}

DirectServer is one fileshare server's admin API over HTTPS.

type Portal

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

Portal is a Backend through go-fileshare/portal.

func NewPortal

func NewPortal(base string, hc *http.Client, serialize func(func() error) error) *Portal

NewPortal is a Backend through the portal at base (an origin, such as "https://files.example.org", or "" for the page's own). serialize may be nil: refreshes are then serialized within this process only.

func (*Portal) Client

func (p *Portal) Client(server string) adminv1connect.AdminServiceClient

Client is the admin API of server, through the portal.

func (*Portal) LoginURL

func (p *Portal) LoginURL(returnTo string) string

LoginURL is the portal's login, coming back to returnTo (a path).

func (*Portal) Logout

func (p *Portal) Logout(ctx context.Context) (string, error)

Logout ends the session.

func (*Portal) Session

func (p *Portal) Session(ctx context.Context) (*Session, error)

Session is who is logged in.

type Server

type Server struct {
	ID    string
	Label string
	// Reachable: its tokens come from the identity provider this session
	// logged in with. A server behind another provider is listed, not
	// reachable.
	Reachable bool
}

A Server is one fileshare server the console can manage.

func (Server) Name

func (s Server) Name() string

Name is how the console shows the server.

type Session

type Session struct {
	Issuer, Subject, Name string
	Expires               time.Time
	Servers               []Server
}

A Session is who is logged in, and which servers they can reach.

func (*Session) Who

func (s *Session) Who() string

Who is how the console names the person.