Documentation
¶
Overview ¶
Package mpclient calls the managed-principal API that SystemAuth serves to relying parties (systemauthsvc.ManagedPrincipalsPath). Every call acts as the signed-in manager and takes that manager's SystemAuth access token, granted the systemforge:managed_principals scope; the API takes the application from the token's client.
The package depends on the standard library and uuid only, so an application in another process does not import SystemAuth's storage.
Index ¶
- Constants
- Variables
- type APIError
- type Claim
- type Client
- func (c *Client) AcceptInvitation(ctx context.Context, token, invitation string) (uuid.UUID, error)
- func (c *Client) Create(ctx context.Context, token string, in CreateInput) (uuid.UUID, error)
- func (c *Client) DeclineInvitation(ctx context.Context, token, invitation string) error
- func (c *Client) Delete(ctx context.Context, token string, id uuid.UUID) error
- func (c *Client) InviteManager(ctx context.Context, token, email, role string) (*Invitation, error)
- func (c *Client) IssueClaim(ctx context.Context, token string, id uuid.UUID) (*Claim, error)
- func (c *Client) IssueLoginToken(ctx context.Context, token string, id uuid.UUID, in IssueLoginTokenInput) (*IssuedLoginToken, error)
- func (c *Client) List(ctx context.Context, token string, after uuid.UUID, limit int) ([]ManagedPrincipal, error)
- func (c *Client) ListLoginTokens(ctx context.Context, token string, id uuid.UUID) ([]LoginToken, error)
- func (c *Client) ListManagers(ctx context.Context, token string, id uuid.UUID) ([]Manager, error)
- func (c *Client) ListSessions(ctx context.Context, token string, id uuid.UUID) ([]Session, error)
- func (c *Client) RedeemClaim(ctx context.Context, token, code string) (uuid.UUID, error)
- func (c *Client) Release(ctx context.Context, token string, id uuid.UUID) error
- func (c *Client) RemoveManager(ctx context.Context, token string, id, managerID uuid.UUID, role string) error
- func (c *Client) RevokeAll(ctx context.Context, token string, id uuid.UUID) error
- func (c *Client) RevokeInvitation(ctx context.Context, token string, invitationID uuid.UUID) error
- func (c *Client) RevokeLoginToken(ctx context.Context, token string, id, credentialID uuid.UUID) error
- func (c *Client) RevokeSession(ctx context.Context, token string, id uuid.UUID, kind string, ...) error
- type CreateInput
- type Invitation
- type IssueLoginTokenInput
- type IssuedLoginToken
- type LoginToken
- type ManagedPrincipal
- type Manager
- type Session
Constants ¶
const ( RoleGuardian = "guardian" RoleEducator = "educator" )
Roles a manager can hold. Deployments may register further roles.
Variables ¶
var ( ErrUnauthorized = errors.New("mpclient: unauthorized") // ErrForbidden means the manager may not do this, the principal does not // exist or is not theirs, or the token lacks the scope. The API gives one // answer for all of these. ErrForbidden = errors.New("mpclient: forbidden") // ErrNotFound means the route or a token, session or invitation was not // found. ErrNotFound = errors.New("mpclient: not found") // ErrInvalidCode means a claim code or invitation token cannot be used, // for any reason. ErrInvalidCode = errors.New("mpclient: invalid code") // ErrInvalidRequest means the request was refused as malformed or // incomplete; APIError.Message says why. ErrInvalidRequest = errors.New("mpclient: invalid request") // ErrConflict means the request conflicts with the principal's state, // such as removing its last manager. ErrConflict = errors.New("mpclient: conflict") // ErrRateLimited means too many attempts; APIError.RetryAfter says when // to try again. ErrRateLimited = errors.New("mpclient: rate limited") )
Errors an API call can return, each wrapped in an *APIError.
Functions ¶
This section is empty.
Types ¶
type APIError ¶
type APIError struct {
Status int
Message string
RetryAfter time.Duration
// contains filtered or unexported fields
}
APIError is an unsuccessful response.
type Claim ¶
type Claim struct {
ID uuid.UUID `json:"id"`
Code string `json:"code"`
ExpiresAt time.Time `json:"expires_at"`
}
Claim is a single-use code that lets another person become a guardian.
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client calls the managed-principal API.
func New ¶
New returns a Client for the API at baseURL, such as "https://auth.example.com/managed-principals". A nil hc uses http.DefaultClient.
func (*Client) AcceptInvitation ¶
AcceptInvitation accepts an invitation to be managed and returns the new manager's ID.
func (*Client) Create ¶
Create creates a managed principal with the caller as its only manager and returns its ID.
func (*Client) DeclineInvitation ¶
DeclineInvitation declines an invitation to be managed.
func (*Client) InviteManager ¶
InviteManager offers to manage the person with a verified address, in role.
func (*Client) IssueClaim ¶
IssueClaim issues a single-use claim code for a managed principal.
func (*Client) IssueLoginToken ¶
func (c *Client) IssueLoginToken(ctx context.Context, token string, id uuid.UUID, in IssueLoginTokenInput) (*IssuedLoginToken, error)
IssueLoginToken issues a login token for a managed principal.
func (*Client) List ¶
func (c *Client) List(ctx context.Context, token string, after uuid.UUID, limit int) ([]ManagedPrincipal, error)
List returns a page of the caller's managed principals in principal-ID order, after the given ID (uuid.Nil for the first page). A short or empty page is the last. limit 0 uses the server's maximum.
func (*Client) ListLoginTokens ¶
func (c *Client) ListLoginTokens(ctx context.Context, token string, id uuid.UUID) ([]LoginToken, error)
ListLoginTokens returns a managed principal's live login tokens.
func (*Client) ListManagers ¶
ListManagers returns a managed principal's active managers.
func (*Client) ListSessions ¶
ListSessions returns the ways a managed principal is signed in.
func (*Client) RedeemClaim ¶
RedeemClaim redeems a claim code: the caller becomes a guardian of the principal it names, whose ID is returned.
func (*Client) RemoveManager ¶
func (c *Client) RemoveManager(ctx context.Context, token string, id, managerID uuid.UUID, role string) error
RemoveManager ends a manager's role over a managed principal. The last manager of a principal without a verified email cannot be removed.
func (*Client) RevokeInvitation ¶
RevokeInvitation withdraws an invitation the caller made.
type CreateInput ¶
type CreateInput struct {
DisplayName string
// Email optionally gives the principal an unverified address.
Email string
Role string
}
CreateInput describes a managed principal to create. The caller becomes its manager in Role.
type Invitation ¶
type Invitation struct {
ID uuid.UUID `json:"id"`
Token string `json:"token"`
Email string `json:"email"`
Role string `json:"role"`
ExpiresAt time.Time `json:"expires_at"`
}
Invitation is an offer to manage a person with a verified address.
type IssueLoginTokenInput ¶
type IssueLoginTokenInput struct {
// Name optionally labels the token, such as the card or device.
Name string `json:"name,omitempty"`
// SingleUse makes the token valid for one sign-in.
SingleUse bool `json:"single_use,omitempty"`
// ExpiresAt optionally sets the expiry; the server clamps it to its
// ceiling. Nil uses the client's or the deployment's default.
ExpiresAt *time.Time `json:"expires_at,omitempty"`
}
IssueLoginTokenInput describes a login token to issue.
type IssuedLoginToken ¶
type IssuedLoginToken struct {
ID uuid.UUID `json:"id"`
Token string `json:"token"`
Prefix string `json:"prefix"`
SingleUse bool `json:"single_use"`
ExpiresAt *time.Time `json:"expires_at,omitempty"`
}
IssuedLoginToken is a newly issued login token. Token is returned only once; render it as a code or card and do not store it.
type LoginToken ¶
type LoginToken struct {
ID uuid.UUID `json:"id"`
Prefix string `json:"prefix"`
Name string `json:"name,omitempty"`
IssuedBy uuid.UUID `json:"issued_by"`
SingleUse bool `json:"single_use"`
CreatedAt time.Time `json:"created_at"`
ExpiresAt *time.Time `json:"expires_at,omitempty"`
LastUsedAt *time.Time `json:"last_used_at,omitempty"`
LastUsedIP string `json:"last_used_ip,omitempty"`
}
LoginToken is a live login token, without its value.
type ManagedPrincipal ¶
type ManagedPrincipal struct {
PrincipalID uuid.UUID `json:"principal_id"`
DisplayName string `json:"display_name"`
// Roles are the roles the calling manager holds over it.
Roles []string `json:"roles"`
}
ManagedPrincipal is a managed principal as its manager lists it.
type Session ¶
type Session struct {
ID uuid.UUID `json:"id"`
Kind string `json:"kind"`
Provider string `json:"provider,omitempty"`
ClientID string `json:"client_id,omitempty"`
CreatedAt time.Time `json:"created_at"`
ExpiresAt time.Time `json:"expires_at"`
LastUsedAt *time.Time `json:"last_used_at,omitempty"`
ClientIP string `json:"client_ip,omitempty"`
}
Session is one way a managed principal is signed in. Kind is "login", "oauth" or "principal_token".
Source Files