Documentation
¶
Overview ¶
Package apikeys adds machine credentials to Auth-All.
A key authenticates through the Authorization header, so a host route under RequireAuth or under a role check accepts it with no change.
k := apikeys.New(apikeys.Prefix("ak_"), apikeys.MaxTTL(365*24*time.Hour))
auth, err := authall.New(authall.WithStore(s), authall.WithPlugins(r, k))
The plaintext key exists one time, in the response of the create route. The store keeps the SHA-256 digest.
Index ¶
- Constants
- func NewPlaintextKey(prefix string) (string, error)
- func Table(o schema.Options) schema.Table
- type CreateInput
- type Option
- type OrganizationResolver
- type Plugin
- func (p *Plugin) Claims(bearer string) bool
- func (p *Plugin) Create(ctx context.Context, owner *store.User, in CreateInput) (*store.APIKey, string, error)
- func (p *Plugin) ID() string
- func (p *Plugin) List(ctx context.Context, userID string) ([]store.APIKey, error)
- func (p *Plugin) Register(r *plugin.Registry) error
- func (p *Plugin) Resolve(ctx context.Context, bearer string) (*plugin.Principal, error)
- func (p *Plugin) Revoke(ctx context.Context, keyID string, actor *store.User, isAdmin bool) error
Constants ¶
const DefaultPrefix = "ak_"
DefaultPrefix starts every generated key.
const DefaultTouchInterval = 60 * time.Second
DefaultTouchInterval limits how often a key request writes the last use time.
const ID = "apikeys"
ID is the stable plugin identifier.
Variables ¶
This section is empty.
Functions ¶
func NewPlaintextKey ¶
NewPlaintextKey returns one plaintext key with the given prefix. A test uses it to check the shape of a key with no database.
Types ¶
type CreateInput ¶
type CreateInput struct {
// UserID is the owner of the key.
UserID string
// Name is the label of the owner. It has 1 to 100 characters.
Name string
// Role is the role of the key. An empty value takes the role of the owner.
Role string
// ExpiresAt ends the key. A nil value means no expiry.
ExpiresAt *time.Time
// OrgID names the organization of the key. An empty value creates a key of
// the whole application.
OrgID string
}
CreateInput describes a new key.
type Option ¶
type Option func(*Plugin)
Option configures the plugin.
func AdminRole ¶
AdminRole names the role that can list and revoke the keys of another user. The default is "admin".
func AllowNoExpiry ¶
func AllowNoExpiry() Option
AllowNoExpiry accepts a key with no expiry, even when a maximum lifetime exists.
func MaxTTL ¶
MaxTTL sets the highest accepted lifetime of a key. A key with no expiry then fails, unless the host allows one with AllowNoExpiry.
func Organizations ¶ added in v0.4.0
func Organizations(r OrganizationResolver) Option
Organizations lets a key name an organization. The value is the organizations plugin.
orgs := organizations.New(...) keys := apikeys.New(apikeys.Organizations(orgs))
func TouchInterval ¶
TouchInterval limits how often a key request writes the last use time. The default is 60 seconds.
type OrganizationResolver ¶ added in v0.4.0
type OrganizationResolver interface {
// KeyCredential returns the organization, the membership, and the
// effective statements of one key. It returns an error when the owner
// holds no active membership of that organization.
KeyCredential(ctx context.Context, orgID, ownerID, keyRole string) (
*store.Organization, *store.Membership, []string, error)
// KnownRole reports whether the organization holds the role.
KnownRole(ctx context.Context, orgID, role string) (bool, error)
}
OrganizationResolver answers the organization credential of one key. The organizations plugin implements it.
The permissions of an organization key are the intersection of the key permissions and the live permissions of the owner in that organization, so a demoted member keeps no stronger key.
type Plugin ¶
type Plugin struct {
// contains filtered or unexported fields
}
Plugin is the API keys plugin.
func (*Plugin) Claims ¶
Claims implements plugin.CredentialResolver. It reads the shape of the value only, and it makes no database call.
func (*Plugin) Create ¶
func (p *Plugin) Create(ctx context.Context, owner *store.User, in CreateInput) (*store.APIKey, string, error)
Create returns a new key and its plaintext value. The plaintext exists only in this return value.
Source Files