> ## Documentation Index
> Fetch the complete documentation index at: https://docs.corsa.finance/llms.txt
> Use this file to discover all available pages before exploring further.

# Set up HYOK

> Install the Corsa HYOK CloudFormation stack in your AWS account yourself with a launch link from the app, choose Cognito or your own OIDC identity provider, and understand the guardrails the stack enforces.

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](#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](/encryption/index#fields-you-can-encrypt) to encrypt. Review the [features lost with HYOK](/hyok/limitations) for those fields first.

<Note>
  Manage your AWS infrastructure with Terraform? See [Install HYOK with Terraform](/hyok/terraform).
</Note>

***

## Deploy the stack

<Steps>
  <Step title="Start HYOK setup in Corsa">
    A workspace **Owner** opens **Settings** → **Encryption**, selects **HYOK**, and chooses the fields to encrypt.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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](/hyok/oidc).
  </Step>

  <Step title="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](/hyok/release-verification).
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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](/hyok/operations#health-checks). If the stack hasn't finished after 30 minutes, the app links to the stack's events in the AWS console.
  </Step>

  <Step title="Verify the running stack">
    Run the [running-stack check](/hyok/release-verification#level-3-check-the-running-stack) in AWS CloudShell to confirm the stack runs the release you reviewed.
  </Step>
</Steps>

<Note>
  The launch link and the callback token both expire. If the stack wasn't created in time, start again from **Launch stack**. See [Troubleshooting](/hyok/troubleshooting#setup-and-launch).
</Note>

***

## 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.

| | Cognito (default) | Your own OIDC identity provider |
| - | - | - |
| Who manages users | You, in Cognito in your AWS account. The stack sets it up | You, in your existing identity provider, for example Okta or Microsoft Entra ID |
| Sign-in | Emailed one-time code, then a passkey | Your identity provider's sign-in, with its MFA and policies |
| Who can decrypt | Members of the `hyok-decryptors` group | Users whose token carries your decryptor group claim |
| Setup steps after install | [Register the first administrator](#register-the-first-administrator), then [add decryptors](#add-decryptors) | An Owner signs in once through your identity provider |

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](/hyok/oidc).

***

## 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](/hyok/operations#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](/hyok/operations#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.

<Steps>
  <Step title="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.
  </Step>

  <Step title="Confirm the email code">
    They enter the one-time code emailed to them.
  </Step>

  <Step title="Create a passkey">
    They register a passkey (for example Touch ID, Windows Hello, or a security key). Later sign-ins use the passkey.
  </Step>
</Steps>

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](/hyok/oidc#how-unwrap-authorization-works).

With Cognito, decryption requires membership of the `hyok-decryptors` group in **your** AWS account. Corsa can't add or remove users there.

<Steps>
  <Step title="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.
  </Step>

  <Step title="Add the user to the group">
    Open the user and add them to the `hyok-decryptors` group.
  </Step>

  <Step title="First sign-in">
    The user opens an encrypted field in Corsa, confirms the emailed code, and registers a passkey.
  </Step>
</Steps>

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:

| Path | How protected fields are encrypted |
| - | - |
| API with the Node.js SDK | The SDK encrypts on your side with your pinned public key. See [Encrypt with the SDK](/hyok/sdk) |
| Corsa KYC integrations | Corsa encrypts on arrival with your published public key. Corsa sees the plaintext only in passing, as described in the [trust model](/hyok/index#trust-model) |
| Manual entry in the app | Users type protected values into Secure Viewer input fields, which encrypt in the browser |

Corsa rejects plaintext values for protected fields sent through other paths, such as a raw API call without encryption.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.