Authentication Component

Provisions a managed user identity provider with sign-up, sign-in, MFA, and token issuance. Deploy in the global region — authentication providers are globally scoped on all three cloud platforms.

Configuration Fields

Field	Type	Required	Default	Description
type	string	required	—	Must be "authentication"
name	string	required	—	Unique component name.
loginProviders	array of strings	optional	["email"]	Sign-in methods. Values: "email", "phone", "google", "facebook", "apple". Provider support varies — see limitations.
registration	string	optional	"open"	"open" (anyone can sign up) or "admin-only" (admin creates users).
mfa	string	optional	"off"	MFA mode: "off", "optional", "required".
passwordPolicy	object	optional	—	Password strength requirements. See below.
triggers	object	optional	—	Cognito user-pool Lambda triggers: a map of trigger point → function name. See Cognito Lambda Triggers below. (AWS)
groups	array of objects	optional	—	User groups to create in the identity provider. Each element is an object — see Groups fields below.
users	array of objects	optional	—	Users to invite on deploy. Each element is an object — see Users fields below.
links	array of objects	optional	—	Component links to email or SMS components. Each link is an object with sourceComponent, targetComponent, and linkType fields. See Links section below.

Password Policy Fields

Field	Type	Default	Description
minLength	integer	8	Minimum password length. Must be ≥ 6.
requireUppercase	boolean	true	Require at least one uppercase letter.
requireNumbers	boolean	true	Require at least one number.
requireSymbols	boolean	false	Require at least one special character.

Groups Fields

Each element of the groups array is an object with the following fields. Groups are provisioned in the identity provider in the order they are declared.

Field	Type	Required	Description
name	string	required	Unique group name within this component. Must be non-blank.
description	string	required	Human-readable description of the group. Must be non-blank.

Users Fields

Each element of the users array is an object representing a user to invite on deploy. Users are processed in the order they are declared, after all groups have been provisioned. Each groups entry must reference a group name defined in the groups array of the same component.

Field	Type	Required	Description
email	string	required	Email address of the user to invite. Must be non-blank.
groups	array of strings	optional	Group names to assign the user to after the invite is sent. Each value must match a name in the component's groups array. Defaults to no group assignments when absent.

Validation Rules

The plugin validates authentication configuration with the following rules:

Group name: Must be non-blank. Validation error at groups[n].name if missing or blank.
Group description: Must be non-blank. Validation error at groups[n].description if missing or blank.
User email: Must be non-blank. Validation error at users[n].email if missing or blank.
User group references: Each group name in a user's groups array must match a group name defined in the component's groups array. Validation error at users[n].groups if referencing an undefined group.
Array types: Both groups and users must be arrays of objects. Validation error if the field is present but not an array.
Declaration order: Groups and users are provisioned in the order they appear in the arrays.

Provisioning Order

During deployment, the plugin provisions resources in this order:

Create the user pool / identity provider
Create all groups (in declaration order)
Invite all users (in declaration order)
Assign each user to their specified groups

This ensures groups exist before users are assigned to them. If any step fails, the deployment stops and returns an error.

Cognito Lambda Triggers (AWS)

The optional triggers setting attaches Cognito user-pool Lambda triggers to the pool. Each entry maps a trigger point to a function name. The function is an implicit reference (like API Gateway route functions) — you do not add it to links; the plugin wires the dependency automatically so the function is deployed before the pool.

At deploy time the plugin sets the user pool's LambdaConfig to invoke the referenced functions and grants each function permission for cognito-idp.amazonaws.com to invoke it (lambda:InvokeFunction, scoped to the pool ARN). Redeploying updates the wiring declaratively — changing a trigger's function repoints it, and removing a trigger (or setting "triggers": {}) clears it.

triggers Fields

Keys must be one of the supported Cognito trigger points; values are function names that must resolve to a function component in the configuration.

Trigger point	When it fires
preSignUp	Before a user is created during sign-up.
postConfirmation	After a user confirms their account.
preAuthentication	Before a sign-in request is authenticated.
postAuthentication	After a user is authenticated.
preTokenGeneration	Before tokens are issued — customise/augment claims.
customMessage	To customise messages (verification, invitation, MFA).
defineAuthChallenge	To define a custom authentication challenge flow.
createAuthChallenge	To create a custom authentication challenge.
verifyAuthChallengeResponse	To verify a custom challenge response.
userMigration	To migrate users from an existing directory at sign-in.

Example: preTokenGeneration trigger

{
  "type": "authentication",
  "name": "staff-auth",
  "providerSettings": {
    "mfa": "required",
    "triggers": {
      "preTokenGeneration": "mfa-enforcer"
    }
  }
}

Here mfa-enforcer is a function component declared elsewhere in the same configuration. The plugin deploys it first, sets it as the pool's pre-token-generation trigger, and grants Cognito permission to invoke it. This pairs naturally with "mfa": "required": the pool enforces a second factor while the trigger adds enrol-before-full-scope routing and custom claims.

Validation: serverless:validate checks that triggers is an object, each key is a known Cognito trigger point, and each value names a function that exists in the configuration. Unknown trigger points or missing functions fail validation before any cloud call.

Deploy permissions: attaching triggers requires lambda:AddPermission on the deploy identity (in addition to cognito-idp:*, which covers UpdateUserPool) — see Credentials.

Cloud Resources Created

Cognito User Pool — with the configured password policy, MFA, and login providers.
Cognito User Pool Client — app client for token issuance (no client secret, suitable for SPAs).
Cognito User Groups — one per entry in groups.
User Pool LambdaConfig (only when triggers are declared) — the pool is wired to invoke the referenced Lambda functions at the configured trigger points, and each function is granted lambda:InvokeFunction permission for cognito-idp.amazonaws.com.

Limitations: Social login providers (Google, Facebook, Apple) require a Cognito domain and OAuth app credentials configured outside the plugin. Lambda triggers are AWS-only.

JSON Example

{
  "type": "authentication",
  "name": "user-auth",
  "providerSettings": {
    "loginProviders": ["email"],
    "registration": "open",
    "groups": [
      { "name": "admin",  "description": "Administrator users" },
      { "name": "member", "description": "Standard members" }
    ],
    "users": [
      { "email": "alice@example.com", "groups": ["admin", "member"] },
      { "email": "bob@example.com", "groups": ["member"] }
    ]
  },
  "links": []
}

Full Example with All Fields

{
  "type": "authentication",
  "name": "user-auth",
  "providerSettings": {
    "loginProviders": ["email", "google"],
    "registration": "open",
    "mfa": "optional",
    "passwordPolicy": {
      "minLength": 10,
      "requireUppercase": true,
      "requireNumbers": true,
      "requireSymbols": true
    },
    "groups": [
      { "name": "admin",  "description": "Administrator users" },
      { "name": "editor", "description": "Content editors" },
      { "name": "member", "description": "Standard members" }
    ],
    "users": [
      { "email": "alice@example.com", "groups": ["admin", "editor"] },
      { "email": "bob@example.com", "groups": ["editor", "member"] },
      { "email": "charlie@example.com", "groups": ["member"] }
    ]
  },
  "links": [
    {
      "sourceComponent": "user-auth",
      "targetComponent": "transactional-email",
      "linkType": "AUTHENTICATION_TO_EMAIL"
    },
    {
      "sourceComponent": "user-auth",
      "targetComponent": "notification-sms",
      "linkType": "AUTHENTICATION_TO_SMS"
    }
  ]
}

Links

Use the links array to declare which components this authentication provider connects to. Each link is an object with three required fields:

sourceComponent (string): The name of this authentication component
targetComponent (string): The name of the email or SMS component to connect to
linkType (string): Either "AUTHENTICATION_TO_EMAIL" or "AUTHENTICATION_TO_SMS"

Cognito Lambda triggers also link the authentication component to functions (link type AUTHENTICATION_TO_FUNCTION), but these are implicit — derived from the triggers map, not written in links.

AUTHENTICATION_TO_EMAIL — SES Email Configuration

When an AUTHENTICATION_TO_EMAIL link is present, the User Pool is configured to use Amazon SES (DEVELOPER mode) as the email sender for invitation and password-reset emails. This replaces the default Cognito email service which is limited to 50 emails per day and may not work in SES sandbox environments.

How It Works

The Email component must be deployed before the Authentication component — the link ensures this ordering automatically.
The SES sourceArn is automatically resolved from the linked Email component's deployment result (no manual ARN needed).
Cognito sends invite emails with a temporary password when users are first created.
Without the link, Cognito falls back to its built-in email (limited to 50/day; may fail in SES sandbox).

Example: Auth with SES Email Link

{
  "type": "authentication",
  "name": "Auth_Service",
  "providerSettings": {
    "passwordPolicy": {
      "minimumLength": 8,
      "requireUppercase": true,
      "requireLowercase": true,
      "requireNumbers": true,
      "requireSymbols": false
    },
    "groups": [
      { "name": "admins", "description": "Full access administrators" },
      { "name": "editors", "description": "Content editors" }
    ],
    "users": [
      { "email": "admin@example.com", "groups": ["admins"] }
    ]
  },
  "links": [
    {
      "sourceComponent": "Auth_Service",
      "targetComponent": "Email_Service",
      "linkType": "AUTHENTICATION_TO_EMAIL"
    }
  ]
}

Example Links

"links": [
  {
    "sourceComponent": "user-auth",
    "targetComponent": "transactional-email",
    "linkType": "AUTHENTICATION_TO_EMAIL"
  },
  {
    "sourceComponent": "user-auth",
    "targetComponent": "notification-sms",
    "linkType": "AUTHENTICATION_TO_SMS"
  }
]

Idempotent Deployment

The authentication component deployment is fully idempotent. Re-deploying is safe and will not create duplicate resources or re-invite existing users:

User Pools are found by name before creating — no duplicate pools are created.
User Pool Clients are found by name before creating — no duplicate clients.
Users that already exist (UsernameExistsException) are silently skipped.
Groups that already exist (GroupExistsException) are silently skipped.

This means running mvn serverless:deploy multiple times is safe — existing resources are reused, not duplicated.

References

The authentication component can link to other components for sending verification emails and MFA codes.

← Referenced by

API Gateway

API validates JWT tokens issued by this provider on protected routes.

Can link to →

Sends verification and password-reset emails via the email component.

Can link to →

SMS

Sends OTP codes for MFA via the SMS component.

Triggers (implicit) →

Function

Cognito user-pool Lambda triggers declared via triggers (e.g. preTokenGeneration).