Amazon Cognito + minidauth keep your login, add keys nobody holds

What stays and what moves

Stays with Amazon Cognito

Accounts, sessions, passwords and the sign-in screen. Nothing about how your users log in changes.

Moves to the network

The key that encrypts and signs, which exists only as shares that 14 of 20 independent nodes have to cooperate to use, and the decision about who holds a role, which takes several of your admins approving it.

Adding it to a Amazon Cognito app

1. Store the link in custom:tide_vuid

   A custom attribute on the user pool, written after the user links their Tide identity.

2. Add one callback route

   The user links their Tide identity in a page served by the Tide network, which neither your app nor minidauth can see into. The shared link.js drop-in adds the routes; you tell it who is signed in and where to store the vuid.

3. Read roles from minidauth, not from Amazon Cognito

   A Pre Token Generation trigger can add group claims to a Cognito token, and it is the obvious place to put roles. A role that arrives in a token your AWS account can mint is a role your AWS account can grant itself. If you copy anything into the token, copy only the vuid, and let the example read roles from minidauth on every request.

What setup creates

A user pool with email sign-in and a tide_vuid attribute, an app client using the authorization code grant with openid and email, a hosted UI domain, and the callback registration with minidauth. It writes everything to .env and reuses it on the next run. npm run teardown removes the pool and domain again. The app's minidauth operator only needs the relying-party role, which can start and finish a sign-in and read grants, and nothing else.

Users without a Tide account

The Amazon Cognito example also mounts a /tideless page. There, the signed-in Amazon Cognito user encrypts and decrypts with no Tide account at all: their Amazon Cognito user id is the subject, a role the quorum granted that id is the gate, and the browser never holds a credential. It needs a public, voucher-gated decrypt policy, which the setup guide covers.

Run the example

npm run setup builds the whole Cognito side for you. The example shares its minidauth code with the others; it has not yet been run against a real user pool.

npm install
AWS_REGION=ap-southeast-2 MINIDAUTH_OPS_TOKEN=<ops token> npm run setup
npm start                                   # http://localhost:3001

npm run teardown                            # when you're finished

minidauth itself has to be running first, with a vendor key created and its policies deployed. The quick start is two Docker commands.

Stuck on the Amazon Cognito side? Join the Discord and I'll help you get it running.

Also works with: Clerk · Auth0 · Supabase · Better Auth