Skip to main content
You install HYOK yourself from the Corsa app. It takes about 30 minutes. You need an Owner in your Corsa workspace and someone who can deploy a CloudFormation stack in your AWS account.

​
Before you start

  • AWS account and region. You need an AWS account where you can deploy a CloudFormation stack. Use a dedicated account or one with tight access boundaries. You declare the account ID and region in Corsa before you deploy, and Corsa rejects a stack that reports a different account or region. The app lists only the regions where Corsa publishes HYOK releases.
  • What the stack creates. Settings → Encryption → Review resources lists everything the stack creates. Share it with your AWS team so the person deploying has the permissions they need.
  • Identity provider. Decide how your users sign in to decrypt: Cognito, set up by the stack in your account, or your own OIDC identity provider. See Choose an identity provider.
  • Matching Corsa accounts. Every person who will decrypt needs a Corsa workspace membership with the same email as their HYOK sign-in.
  • Fields. Decide which eligible fields to encrypt. Review the features lost with HYOK for those fields first.
Manage your AWS infrastructure with Terraform? See Install HYOK with Terraform.

​
Deploy the stack

1

Start HYOK setup in Corsa

A workspace Owner opens Settings → Encryption, selects HYOK, and chooses the fields to encrypt.
2

Declare the AWS account and region

Enter the AWS account ID and pick the region for the stack. With Cognito sign-in, your Corsa email becomes the first administrator.
3

Choose the identity provider

Keep Cognito (the default), or choose Your identity provider (OIDC) and enter its details. Corsa checks that the issuer uses HTTPS and that its discovery document is reachable. See Use your own identity provider.
4

Review the release

Corsa shows the release version, its release digest, and every file that will run in your account. Review it or hand it to your security team. See Verify the release.
5

Copy the callback token

Corsa shows a single-use callback token once. It registers your stack with your workspace. Copy it now: it’s never part of the launch link, and Corsa can’t show it again.
6

Open the launch link

Sign in to the AWS console in the account you declared, then click Launch stack. The console opens a CloudFormation quick-create page that Corsa prepared for your workspace. The suggested stack name is CorsaHyok. You can change it: Corsa records the name your stack reports.The launch link is short-lived. The app shows when it expires. If it expires, click Launch stack again to get a fresh one.
7

Paste the callback token

Paste the token you copied into the CorsaCallbackToken field. The console hides the value. Leave the other prefilled parameters unchanged: Corsa filled them in for your workspace, your identity provider, and the release you reviewed.
8

Create the stack

Select the acknowledgment checkboxes the console shows, then click Create stack. Creation takes about 10 minutes. The stack checks that the release matches the one you reviewed before it installs anything.
9

Wait for Corsa to confirm

When the stack finishes, it sends its signed details to Corsa. Corsa checks that they come from the account and region you declared, then Settings → Encryption shows the stack as Active and starts the first health check. If the stack hasn’t finished after 30 minutes, the app links to the stack’s events in the AWS console.
10

Verify the running stack

Run the running-stack check in AWS CloudShell to confirm the stack runs the release you reviewed.
The launch link and the callback token both expire. If the stack wasn’t created in time, start again from Launch stack. See Troubleshooting.

​
Choose an identity provider

Your users sign in to the Secure Viewer with an identity from your side before they can decrypt. You choose where that identity comes from when you install. With your own identity provider, you register the Secure Viewer as an OIDC client that uses the authorization code flow with PKCE. After the stack is created, you add its redirect URI to that client. For requirements, examples for Okta and Microsoft Entra ID, and limitations, see Use your own identity provider.

​
Built-in guardrails

The stack protects you from the most damaging mistakes even if nobody reviews a change. AWS enforces both guardrails, so they don’t depend on anyone following the docs.

​
Signed code only

The code that runs in your stack only accepts updates signed by Corsa’s release process. AWS refuses any other code. What it protects against: someone replacing the code that handles your keys. That includes an attacker with access to your account, a compromised deployment pipeline, or a well-meant manual edit in the AWS console. The stack can only ever run code from a signed Corsa release. The small installer that sets up the stack is the one exception. Its code is part of what you review before you deploy. An administrator in your account can still turn this protection off. If that happens, the stack’s health reports codeSigning: false and Corsa shows Code signing off as drift.

​
Protected keys

A stack update can never replace or delete:
  • your HYOK key, which wraps your data keys;
  • the signing key your stack uses for its messages to Corsa;
  • your Cognito users, when you use Cognito.
What it protects against: an update that would silently create new resources in their place. A new HYOK key makes all existing HYOK data permanently unreadable. Replacing your Cognito users deletes them and their passkeys. An update that tries either fails instead of running. Don’t override this protection when you update the stack. It covers stack updates only. It doesn’t stop someone from scheduling a key for deletion directly in KMS. Deleting the stack doesn’t delete the keys or your Cognito users. If the protection is removed or changed, the stack’s health reports stackPolicy: false and Corsa shows Stack policy missing as drift.

​
Register the first administrator

This section applies to Cognito sign-in. With your own identity provider, the first sign-in through your identity provider by a workspace Owner completes setup instead.
1

Open the Secure Viewer

The Owner who ran setup signs in to Corsa and opens any client with an encrypted field. The Secure Viewer prompts them to sign in.
2

Confirm the email code

They enter the one-time code emailed to them.
3

Create a passkey

They register a passkey (for example Touch ID, Windows Hello, or a security key). Later sign-ins use the passkey.
The first administrator is added to the hyok-decryptors group automatically.

​
Add decryptors

With your own identity provider, add people to the decryptor group in your identity provider instead. See Use your own identity provider. With Cognito, decryption requires membership of the hyok-decryptors group in your AWS account. Corsa can’t add or remove users there.
1

Create the user

In the AWS console, open Cognito in the stack’s account and region, and select the user pool your HYOK stack set up. Go to Users → Create user. Use the same email as the user’s Corsa account.
2

Add the user to the group

Open the user and add them to the hyok-decryptors group.
3

First sign-in

The user opens an encrypted field in Corsa, confirms the emailed code, and registers a passkey.
To remove access, remove the user from hyok-decryptors or disable the user. Their next unwrap fails. Values already displayed in an open page stay visible until the page is closed.

​
Choose how data enters Corsa

With HYOK, protected fields must be encrypted before Corsa stores them. All three ingest paths are supported: Corsa rejects plaintext values for protected fields sent through other paths, such as a raw API call without encryption.