Documentation
¶
Overview ¶
Package elevation is the admin console unlock ("sudo mode"): signing in gives an admin the workspace side, and the platform console additionally needs a short-lived unlock proved with a second factor. The unlock is an opaque, revocable token bound to the login session's jti, so a stolen unlock is useless without the session, and signing out or revoking the session kills it.
It protects against an unattended browser, a stolen session cookie or a phished password alone. It does not protect against XSS on the same origin, which can ride an unlocked session.
Index ¶
- Constants
- Variables
- func ClearLockout(ctx context.Context, rdb *redis.Client, userID uint) error
- func IPAllowed(set secpolicy.AdminAccess, ip string) bool
- type CodedError
- type Notifier
- type PolicySource
- type Record
- type SecondFactor
- type Service
- func (s *Service) Check(ctx context.Context, userID uint, jti, token string) (Record, error)
- func (s *Service) Elevate(ctx context.Context, user *models.User, jti string, sessionExp time.Time, ...) (string, Record, error)
- func (s *Service) Fresh(rec Record) bool
- func (s *Service) LockedUntil(ctx context.Context, userID uint) time.Time
- func (s *Service) Peek(ctx context.Context, userID uint, jti, token string) (Record, error)
- func (s *Service) Revoke(ctx context.Context, token string)
- func (s *Service) SetNotifier(n Notifier)
- func (s *Service) Settings() secpolicy.AdminAccess
Constants ¶
const ( CookieName = "miabi_admin_unlock" HeaderName = "X-Miabi-Admin-Elevation" )
CookieName carries the unlock for browser clients; HeaderName carries it for the CLI.
Variables ¶
var ( ErrRequired = &CodedError{"ADMIN_ELEVATION_REQUIRED", "the admin console is locked: confirm your second factor to unlock it"} ErrSetupRequired = &CodedError{"ADMIN_2FA_SETUP_REQUIRED", "set up two-factor authentication before unlocking the admin console"} ErrStale = &CodedError{"ADMIN_ELEVATION_STALE", "this action needs a recent unlock: confirm your second factor again"} ErrIPNotAllowed = &CodedError{"ADMIN_IP_NOT_ALLOWED", "the admin console is not reachable from this address"} ErrLocked = &CodedError{"ADMIN_ELEVATION_LOCKED", "too many wrong codes: the admin console unlock is locked for a while"} ErrInvalidCode = &CodedError{"ADMIN_ELEVATION_INVALID_CODE", "invalid code"} ErrNotRequired = errors.New("the admin console unlock is not enabled") )
Functions ¶
func ClearLockout ¶ added in v1.10.18
ClearLockout drops a user's console-unlock lockout and failure count, for host-side recovery.
Types ¶
type CodedError ¶
type CodedError struct {
// contains filtered or unexported fields
}
CodedError carries a stable machine code into the API error envelope, so the web client can tell "unlock the console" from any other 403 without parsing messages.
func (*CodedError) Code ¶
func (e *CodedError) Code() string
Code satisfies the error handler's Code() hook.
func (*CodedError) Error ¶
func (e *CodedError) Error() string
type Notifier ¶
type Notifier interface {
NotifyAdmins(item models.Notification) error
}
Notifier tells the other admins about a lockout. Satisfied by *alerting.AdminNotifier.
type PolicySource ¶
type PolicySource interface {
AdminAccessPolicy() (secpolicy.AdminAccess, bool)
}
PolicySource yields the Enterprise admin_access policy. Satisfied by *secpolicy.Service.
type Record ¶
type Record struct {
UserID uint `json:"user_id"`
JTI string `json:"jti"`
CreatedAt time.Time `json:"created_at"`
LastUsed time.Time `json:"last_used"`
ExpiresAt time.Time `json:"expires_at"`
}
Record is an unlock as stored in Redis, keyed by the token's hash.
type SecondFactor ¶
SecondFactor verifies a TOTP or recovery code. Satisfied by *auth.Service.
type Service ¶
type Service struct {
// contains filtered or unexported fields
}
Service issues and checks unlocks.
func NewService ¶
func NewService(rdb *redis.Client, policy PolicySource, factor SecondFactor, community bool) *Service
NewService builds the unlock service. community is MIABI_ADMIN_UNLOCK: Community's switch for the TOTP unlock with default timings, which the Enterprise policy supersedes.
func (*Service) Check ¶
Check validates an unlock for the session and extends its idle window. It returns ErrRequired for anything that is not a live unlock of this user's this session.
func (*Service) Elevate ¶
func (s *Service) Elevate(ctx context.Context, user *models.User, jti string, sessionExp time.Time, code string) (string, Record, error)
Elevate verifies a second factor and issues an unlock bound to the session jti. The unlock never outlives sessionExp. Every attempt is reported to audit by the caller.
func (*Service) LockedUntil ¶
LockedUntil reports when a user's unlock lockout ends; zero when not locked.
func (*Service) SetNotifier ¶
SetNotifier wires lockout notices to the other admins.
func (*Service) Settings ¶
func (s *Service) Settings() secpolicy.AdminAccess
Settings resolves the unlock in force: the Enterprise policy when enforced, else Community's switch with default timings, else none. Required=false means the console needs no unlock, though an Enterprise allowlist may still apply.