preauthentication

package
v1.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 4, 2026 License: MIT Imports: 14 Imported by: 0

Documentation

Overview

Package preauthentication implements the PreAuthentication hook. It runs when a user starts to sign in, evaluates its optional policy, and carries out the features it has enabled.

Its one feature today, password rotation, is off by default. When enabled, it replaces the password of each native, confirmed user whose password the hooks haven't replaced since a cutoff time with a random one that nobody knows. A password set before the cutoff, such as one leaked in a credential-stuffing attack, stops working, while users who sign in with passwordless factors such as email one-time passwords notice nothing. Cognito doesn't record when a password was set, so rotation keeps its own record of each replacement (see package rotation).

Index

Constants

View Source
const (
	// ActionReplacePassword replaces the user's password with a random one if
	// the hooks haven't replaced it since the cutoff. It is the default when
	// the policy returns no password action, and it wins over
	// ActionSkipPassword.
	ActionReplacePassword = "password.replace"
	// ActionSkipPassword keeps the user's password. It takes an optional
	// "reason", which is logged.
	ActionSkipPassword = "password.skip"
)

Actions a PreAuthentication policy can return. The password actions only have an effect when password rotation is enabled.

View Source
const (
	// UserStatusExternalProvider is the cognito:user_status of federated
	// users. Setting a password would turn a federated profile into a
	// password login.
	UserStatusExternalProvider = "EXTERNAL_PROVIDER"
	// UserStatusUnconfirmed is the cognito:user_status of users who haven't
	// confirmed their sign-up. A permanent password would confirm them
	// without verifying their email address.
	UserStatusUnconfirmed = "UNCONFIRMED"
)

User statuses whose password the hook never replaces.

View Source
const (
	// Timeout bounds the AWS calls that decide a sign-in, such as password
	// rotation's user lookup, record read, and replacement.
	Timeout = 3 * time.Second
	// ReadTimeout bounds reading the rotation record, within Timeout, so a
	// slow read leaves time to replace the password.
	ReadTimeout = time.Second
	// WriteTimeout bounds recording a replacement, after Timeout.
	WriteTimeout = 500 * time.Millisecond
)

Time limits. Cognito waits at most 5 seconds for the whole function, including a cold start, so the hook returns its own error before Cognito gives up.

View Source
const PasswordLength = 128

PasswordLength is the length of the random password set on each user. A user pool's minimum password length can be up to 99, and Cognito accepts passwords of up to 256 characters.

View Source
const PolicyQuery = "data.cognito_hook_preauthentication.result"

PolicyQuery is the rule the optional PreAuthentication policy must define.

View Source
const TriggerAuthentication = "PreAuthentication_Authentication"

TriggerAuthentication is sent when a user starts to sign in with InitiateAuth, AdminInitiateAuth, or managed login.

View Source
const TriggerPrefix = "PreAuthentication_"

TriggerPrefix starts every PreAuthentication trigger source.

View Source
const UnavailableMessage = "Sign-in is temporarily unavailable. Try again in a moment."

UnavailableMessage is the error message Cognito shows the user when the hook rejects a sign-in, as "PreAuthentication failed with error <message>". The details are logged, not returned.

Variables

Actions lists the actions a PreAuthentication policy can return.

View Source
var ErrUnavailable error = unavailableError{}

ErrUnavailable is returned to Cognito, which rejects the sign-in, when an enabled feature can't do its job, such as password rotation failing to tell whether the password must be replaced or to replace it.

Functions

func IsStale

func IsStale(replacedAt *time.Time, rotateBefore time.Time) bool

IsStale reports whether a password last replaced at replacedAt (nil for never) must be replaced for the cutoff rotateBefore.

func SkipReason

func SkipReason(userNotFound bool, status string) string

SkipReason returns why password rotation keeps a user's password whatever the policy decides, or "" when it may replace it: the user doesn't exist, is federated, or hasn't confirmed their sign-up.

Types

type CognitoAPI

type CognitoAPI interface {
	AdminGetUser(ctx context.Context, params *cip.AdminGetUserInput, optFns ...func(*cip.Options)) (*cip.AdminGetUserOutput, error)
	AdminSetUserPassword(ctx context.Context, params *cip.AdminSetUserPasswordInput, optFns ...func(*cip.Options)) (*cip.AdminSetUserPasswordOutput, error)
}

CognitoAPI is the part of the Cognito API password rotation calls.

type Config

type Config struct {
	// Policy decides the actions for each user. It is optional.
	Policy *policy.Engine
	// PasswordRotation enables password rotation. Nil disables it, and the
	// hook makes no AWS calls.
	PasswordRotation *PasswordRotation
}

Config configures the hook.

type Decision

type Decision struct {
	// Actions are the actions the policy returned; empty without a policy.
	Actions []action.Action `json:"actions"`
	// ReplacePassword is false when the password is kept. When it is true
	// and password rotation is enabled, the password is replaced if it is
	// stale.
	ReplacePassword bool `json:"replacePassword"`
	// Reason is why the password is kept.
	Reason string `json:"reason,omitempty"`
}

Decision is what the hook does for a user, resolved from the policy's actions.

func Decide

func Decide(ctx context.Context, p *policy.Engine, in PolicyInput) (*Decision, error)

Decide evaluates the policy for one input and resolves its actions:

  • password.replace is the default, and wins over password.skip.
  • Unknown actions and parameters make the result invalid.

func DefaultDecision

func DefaultDecision() *Decision

DefaultDecision is the decision without a policy, and when the policy fails: replace the password if it is stale.

type Event

Event is a PreAuthentication trigger event.

type Hook

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

Hook handles PreAuthentication events.

func New

func New(cfg Config) (*Hook, error)

New returns the hook.

func (*Hook) Handle

func (h *Hook) Handle(ctx context.Context, e *Event) error

Handle evaluates the policy for one sign-in and carries out the enabled features, leaving the event unchanged. An enabled feature that can't do its job returns ErrUnavailable, and Cognito rejects the sign-in.

type PasswordRotation

type PasswordRotation struct {
	Cognito CognitoAPI
	// Rotations records when each password was replaced.
	Rotations rotation.Store
	// RotateBefore is the cutoff: a password the hooks haven't replaced since
	// this time is replaced at the user's next sign-in.
	RotateBefore time.Time
}

PasswordRotation configures password rotation.

type PolicyInput

type PolicyInput struct {
	cognito.Header
	UserAttributes map[string]string `json:"userAttributes"`
	// ValidationData holds the ClientMetadata of the InitiateAuth or
	// AdminInitiateAuth request.
	ValidationData map[string]string `json:"validationData"`
	// UserNotFound is true for a username that doesn't exist, when the app
	// client prevents user existence errors.
	UserNotFound bool `json:"userNotFound"`
	// PasswordReplacedAt is when the hooks last replaced the password. It is
	// null when they never did, when the record couldn't be read, when
	// password rotation is disabled, and for users whose password the hook
	// never replaces.
	PasswordReplacedAt *time.Time `json:"passwordReplacedAt"`
}

PolicyInput is the policy's input document.

func NewPolicyInput

func NewPolicyInput(e *Event, replacedAt *time.Time) PolicyInput

NewPolicyInput builds the policy input for an event and the time of the user's last replacement, if any.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL