Migrate from Amazon Cognito

Cognito's two-tier model (User Pools + Identity Pools) maps onto Avnology ID's single identity model. Most teams only use User Pools, which is where this guide focuses.

Prerequisites

avnology CLI installed.
Admin API key in .env.
AWS CLI with permission to call cognito-idp:ListUsers and cognito-idp:AdminGetUser on the source user pool.

Equivalent concepts

Cognito	Avnology ID
User Pool	Organization
App Client	OAuth 2.1 client
Identity Pool	Service accounts / external federation (not a direct analog)
User	Identity
Attribute (`email`, `phone_number`, `given_name`, `family_name`, …)	Identity trait (same names)
Custom attribute (`custom:tier`)	`traits.custom.<name>`
Group	Role / Keto relation
Lambda trigger (Pre sign-up, Pre token generation)	Webhook Hook
Hosted UI	Hosted sign-in page (`/sign-in`)
`USER_PASSWORD_AUTH` flow	Password grant (deprecated — use OAuth 2.1 code + PKCE)
`ADMIN_NO_SRP_AUTH`	Admin `POST /v1/sessions`
Token endpoint	`POST /oauth2/token`
JWKS	`/.well-known/jwks.json`

Export users from Cognito

Cognito has no native bulk-export. Use the aws cognito-idp list-users paginator:

aws cognito-idp list-users \
  --user-pool-id us-east-1_XXXXXXXXX \
  --max-items 60 \
  --output json > cognito_raw.json

Cognito's response shape is not the shape the avnology migrate command expects. Convert it to the Auth0 format first — the user fields line up almost 1:1 — and run the Auth0 subcommand:

node scripts/cognito-to-auth0.js cognito_raw.json > cognito_as_auth0.json
avnology migrate auth0 --import cognito_as_auth0.json --dry-run

Cognito does NOT export password hashes. Every user will need to reset their password on first sign-in after migration. Plan for this: send a "please set a new password" email on cutover day.

Example conversion script

// scripts/cognito-to-auth0.js
import fs from "node:fs";
const raw = JSON.parse(fs.readFileSync(process.argv[2], "utf8"));
const out = raw.Users.map((u) => {
  const

OAuth client migration

For each Cognito App Client:

Register a new OAuth client in the Avnology dashboard.
Copy Callback URLs to Avnology's Redirect URIs.
Copy Allowed OAuth Scopes to Avnology's Scopes (openid, profile, email, phone, etc.).
For public clients (SPAs / mobile) enable PKCE.
For confidential clients, rotate to the new secret and store it in your secret manager.

Redirect URL mapping

Cognito URL	Avnology ID URL
`https://<domain>.auth.<region>.amazoncognito.com/oauth2/authorize`	`https://<Domain id="api"/>/oauth2/auth`
`https://<domain>.auth.<region>.amazoncognito.com/oauth2/token`	`https://<Domain id="api"/>/oauth2/token`
`https://<domain>.auth.<region>.amazoncognito.com/.well-known/jwks.json`	`https://<Domain id="api"/>/.well-known/jwks.json`
`https://<domain>.auth.<region>.amazoncognito.com/oauth2/userInfo`	`https://<Domain id="api"/>/userinfo`
`https://<domain>.auth.<region>.amazoncognito.com/logout`	`https://<Domain id="api"/>/oauth2/sessions/logout`

Lambda triggers → Hooks

Cognito trigger	Avnology event
Pre sign-up	`user.pre_create`
Post confirmation	`user.created`
Pre authentication	`session.pre_create`
Post authentication	`session.created`
Pre token generation	`token.pre_issue` (configure a token claim resolver)
Migrate user (password migration)	Password migration hook

The password migration hook is your path out of "every user must reset": it lets Avnology call a webhook you provide to verify a legacy credential at sign-in time, then upgrade the stored hash transparently. Keep the Cognito user pool alive (read-only) for the duration of the migration window and point the hook at a small AWS Lambda that validates against it.

Cutover plan

Import users in a staging Avnology tenant. Without passwords, test the reset-email flow end-to-end.
If you use the password migration hook, stand it up first, then roll out the CLI import.
Plan a maintenance window: Cognito cannot be revoked while user pool authentication is in flight.
Cutover: flip redirect URIs and env vars; send a "reset your password" email (or rely on the migration hook to silently upgrade users).
Keep the Cognito user pool online for 30 days to support any missed accounts, then decommission.

Migrate from Amazon Cognito

On this page