Verify Cognito before go-live
Run eleven checks on your own Cognito user pool before live work starts. Each check has a command and an expected result.
This page applies when your server runs in Cognito mode. In OIDC mode there is no pool, so the IAM steps do not apply. OIDC mode needs its own login and revocation checks.
Before you start
Run these checks on your own pool, in order, before live work starts. Use two test people who are not real staff. Record each result in the Launch acceptance record.
The checks
| # | Command or action | Expected result | Pass or fail |
|---|---|---|---|
| 1 | Apply the lifecycle permissions from Grant the lifecycle permissions. Run the simulate-principal-policy check in Check the permissions. Add cognito-idp:AdminCreateUser to the check. Add the seven SAML provider actions only if CH_SSO_IDP_PROVISIONING=true. |
Each action reads allowed. |
|
| 2 | aws cognito-idp get-user-pool-mfa-config --user-pool-id POOL_ID |
MfaConfiguration is ON. SoftwareTokenMfaConfiguration.Enabled is true. |
|
| 3 | curl https://YOUR_HOST/v1/health |
The identity field reads ok. |
|
| 3a | Sign in as a native test user. Decode the access token payload on your own machine. See Install the pre-token Lambda. | The payload holds email, email_verified and identity_provider. identity_provider reads COGNITO. |
|
| 4 | Sign in to the web app as a native test user. | Sign-in asks for the TOTP code and succeeds after you enter it. | |
| 5 | Run ch login on a laptop. Approve the sign-in in the browser. Then run ch whoami. |
ch whoami shows the member, the home workspace and the server version. |
|
| 6 | Invite a test email address from the web app. | The Cognito invitation mail arrives. The invitation shows in the list. The person signs in and accepts. | |
| 7 | If you use SAML federation, add the SSO connection. Then mint a SCIM token and set up your identity provider. See SCIM. Push one test user. | The user appears as a member of the top-level workspace. A SCIM read returns active: true. |
|
| 8 | Deactivate the SCIM test user in your identity provider. Then run aws cognito-idp admin-get-user --user-pool-id POOL_ID --username USER. |
The output shows "Enabled": false. That user’s ch whoami returns 401. A browser refresh fails. journalctl -u codeherder | grep cognito_access_denied=true returns nothing. |
|
| 9 | In a window before go-live, remove cognito-idp:AdminDisableUser from the policy. Deprovision a second test user. Then restore the policy and deprovision that user again. |
The server logs the WARN line with cognito_access_denied=true and your alert fires. After you restore the policy, admin-get-user shows "Enabled": false. See Alert on a denied revoke. |
|
| 10 | Disable or delete the test users. | No test user can sign in. |
A step passes only when you see the expected result. If a step fails, fix the cause and run it again. Do not skip a step.
When every step passes, copy the date and result into the Launch acceptance record. Your instance operator and your administrator sign it.
Related guides
- Self-hosted Cognito sign-in — the permissions, the check and the alert
- SCIM — mint a token and set up your identity provider
- Self-hosted acceptance journey — the run that comes next
- Self-hosted responsibilities and launch acceptance — the record to sign
Last updated
