Where to look
| Source | Where | What it shows |
|---|---|---|
| Stack events | CloudFormation → <your-stack-name> → Events | Creation and update failures |
| Decryption audit log | Your AWS account. Settings → Encryption → Review resources shows where | One audit line per unwrap: user, token ID, field, outcome, denial reason |
| Stack activity log | Your AWS account. Review resources shows where | Registration with Corsa, first administrator, passkey events, key protection updates |
| KMS usage | CloudTrail, events for your HYOK key | Every Decrypt call |
| Health | The health endpoint and Settings → Encryption | Stack status as Corsa sees it |
Setup and launch
| Symptom | Likely cause | Fix |
|---|---|---|
The CloudFormation console can’t open the launch link, for example Request has expired or Access Denied | The launch link expired. Launch links are short-lived | Click Launch stack again in Settings → Encryption to get a fresh link. You don’t need a new callback token if you haven’t used it yet |
| Creation fails with a release download error | The release link in your launch expired before the stack downloaded the release | Delete the failed stack, then start again from Launch stack. It’s safe to retry |
| Creation fails with a checksum or digest error | The downloaded release doesn’t match the release you reviewed | Don’t work around it. Start again from Launch stack, and contact Corsa if it repeats |
| The region you want isn’t in the list | Corsa doesn’t publish HYOK releases in that region | Pick a listed region |
| The stack completes, but Corsa shows Account mismatch or Region mismatch and not Active | The stack was created in a different AWS account or region from the one you declared. Corsa rejected its outputs | Delete that stack and deploy again from Launch stack, signed in to the declared account with the declared region selected. Corsa never registered the misplaced stack, so no data was encrypted with its key. Deleting the stack doesn’t delete its KMS keys: schedule them for deletion in that account |
| The stack completes but Corsa doesn’t show Active | The callback token expired or was already used, or the stack can’t reach Corsa | Check the stack activity log, then start again from Launch stack in Corsa |
| The callback token is rejected | Tokens are single use | Get a new token from Settings → Encryption |
| Setup hasn’t finished after 30 minutes | The stack is still creating, or creation failed | Use the link in the app to open the stack’s events, and find the first failed resource |
Upgrades and guardrails
| Symptom | Likely cause | Fix |
|---|---|---|
An update or creation fails with a code signature error, such as CodeVerificationFailedException | Only signed code runs, and the code isn’t signed by Corsa. For example, someone uploaded code by hand or deployed changes that didn’t come from Corsa | Don’t turn off the protection. Update the stack only through Launch stack, Upgrade stack, or Roll back. If nobody in your team made the change, treat it as a security incident and contact Corsa |
An update fails with Action denied by stack policy | The update would replace or delete one of your keys or your Cognito users, and the stack’s built-in protection blocked it. CloudFormation rolls the update back | This is the protection doing its job. Don’t override it. Check that you started the update from Upgrade stack and kept the existing parameter values, then contact Corsa |
| The pre-upgrade check fails | The change set would replace one of your keys or your Cognito users | Don’t execute the change set. Delete it and contact Corsa |
| Upgrade stack says the release is older than the installed one | Corsa refuses downgrades, except a rollback to the immediately previous release | Use Roll back for the previous release. For anything older, contact Corsa |
| Upgrade stack says an upgrade is already pending | You started an upgrade to another release and it hasn’t completed | Complete that upgrade first. To abandon it, contact Corsa |
| The update completed, but the app still shows the upgrade as pending | The stack’s details didn’t reach Corsa yet, or it reported a different release | Wait a few minutes. If the app then shows Release mismatch, see Drift |
An update fails and the rollback ends in UPDATE_ROLLBACK_FAILED | A resource couldn’t be restored | Open the stack events to find the resource, then contact Corsa. Don’t delete the stack |
Sign-in and passkeys
| Symptom | Likely cause | Fix |
|---|---|---|
| No email code arrives | Cognito’s default email limits, or spam filtering | Check spam, then retry. For many users, set up Amazon SES email sending in Cognito |
| Passkey registration fails | The browser blocks passkeys in embedded frames, or the device has no authenticator | Use a current Chrome, Edge, or Safari, and allow the popup the Secure Viewer opens |
| User can sign in but can’t decrypt | The user isn’t in hyok-decryptors, or their HYOK email differs from their Corsa email | See the reason in the decryption table |
Your own identity provider (OIDC)
| Symptom | Likely cause | Fix |
|---|---|---|
Setup rejects the identity provider settings (HYOK_OIDC_INVALID) | The issuer isn’t HTTPS, or the client ID, audience, decryptor claim, or decryptor value is missing | Correct the values. See Requirements |
Setup can’t reach the issuer (HYOK_OIDC_DISCOVERY_FAILED) | <issuer>/.well-known/openid-configuration isn’t reachable from the internet, or its issuer differs from the URL you entered | Open the discovery URL in a browser and copy its issuer value exactly, including any trailing path such as /v2.0 or /oauth2/default |
Sign-in fails with a redirect URI error, for example Okta’s redirect_uri error or Entra ID’s AADSTS50011 | The client doesn’t list the Secure Viewer’s redirect URI | Add the Secure Viewer’s redirect URI (the stack’s OidcRedirectUri output) to the client’s redirect URIs exactly |
| Sign-in fails with a CORS error in the browser console (Okta) | The Secure Viewer’s origin isn’t a trusted origin | In Okta, add the Secure Viewer’s address (the stack’s ViewerUrl output) under Security → API → Trusted Origins with CORS enabled |
Sign-in fails with AADSTS9002326 (Entra ID) | The redirect URI is registered under the Web platform | Register it under Single-page application (SPA) instead |
| The user signs in but can’t decrypt | The token doesn’t contain the decryptor value in the decryptor claim. In Entra ID, the claim holds group Object IDs, and users in more than 200 groups get no groups claim | Add the user to the decryptor group, check the claim configuration, and in Entra ID use Groups assigned to the application |
The user signs in but every unwrap reports email_mismatch | The email claim is missing, or differs from the user’s Corsa email | Add the email claim to the token, and make sure the email matches the user’s Corsa account |
| Unwraps fail after you changed the client or the issuer’s signing keys | The audience no longer matches the one you entered in Corsa, or your stack still caches the old keys | Check the audience. New signing keys are picked up within 10 minutes |
| Setup doesn’t complete after the Owner signs in | The Owner who signed in isn’t in the decryptor group, or their email differs from their Corsa email | Add them to the group, or have another Owner who is in the group sign in |
Decryption
Find thereason in the decryption audit log line for the failed unwrap:
| Reason | Meaning | Fix |
|---|---|---|
cognito_token | Missing or expired Cognito session | Sign in again |
not_decryptor | The user isn’t in hyok-decryptors | Add them to the group |
user_disabled | The Cognito user is disabled | Enable the user if access is intended |
email_mismatch | The HYOK email differs from the user’s Corsa email | Create the Cognito user with the same email as their Corsa account |
token_missing, token_expired | No Corsa unwrap token, or it expired | Reload the page |
token_signature, token_kid, token_alg, token_claims, token_malformed | The Corsa unwrap token failed verification, for example wrong audience or workspace | Reload the page. If it persists, contact Corsa |
jwks_unavailable | The stack couldn’t fetch Corsa’s token signing keys | Check that the stack has outbound internet access, then contact Corsa |
resource_not_authorized | The requested field isn’t listed in the Corsa token | Reload the page |
resource_binding | The wrapped key is bound to a different field | Ciphertext was copied between fields or workspaces. Contact Corsa |
legacy_v1_disabled | A value encrypted before resource binding, and the stack no longer accepts such values | Contact Corsa to re-encrypt the value or change the incident setting |
invalid_request, invalid_ciphertext, invalid_key_length | Malformed request or envelope | Reload the page. If it persists, contact Corsa |
rate_limited | Too many unwraps by one user in a short time | Wait and retry |
internal_error | KMS or another AWS call failed | Check that your HYOK key is enabled and its policy is unchanged |
Health
healthStatus | Meaning | Fix |
|---|---|---|
ok | All checks pass | None |
degraded with kms: false | Your HYOK key is disabled, pending deletion, or the policy changed | Re-enable the key or restore the policy |
degraded with cognito: false | Cognito sign-in unreachable | Check the AWS Health Dashboard for Cognito in your stack’s region |
degraded with oidc: false | Your identity provider’s issuer is unreachable from the stack | Check your identity provider’s status and that its discovery document is public |
degraded with stackPolicy: false | The stack’s key protection was removed or changed | See Drift |
degraded with codeSigning: false | The stack no longer refuses code that Corsa didn’t sign | See Drift |
| No recent health | Corsa can’t reach the health endpoint, or the signature check failed | Check that the stack is in a complete state in CloudFormation, then contact Corsa |
SDK and API
| Symptom | Likely cause | Fix |
|---|---|---|
| SDK error about the key fingerprint | expectedKeySpkiSha256 doesn’t match the configured public key | Fetch the key again from your account and compare fingerprints |
400 when writing a protected field | The value is plaintext, or the envelope is malformed | Encrypt with the SDK, or use an integration or the app |
| Exact search doesn’t find a known value | The value was hashed with different normalization, for example by an outdated SDK | Upgrade the SDK and re-save the value |