Skip to main content
By default, the people who decrypt sign in with Cognito, which the HYOK stack sets up in your AWS account. If you already manage identities in an OIDC identity provider, such as Okta or Microsoft Entra ID, your users can sign in to the Secure Viewer with it instead. They use their existing account, MFA, and sign-in policies. You manage who can decrypt with a group in your identity provider. With your own identity provider, the stack doesn’t set up Cognito, and there’s no emailed code or passkey step.
This page is about signing in to the Secure Viewer to decrypt HYOK fields. Signing in to the Corsa app itself is configured separately. See Single sign-on.

​
Requirements

You enter these values in the install wizard when you choose Your identity provider (OIDC). Corsa checks that the issuer uses HTTPS and that its discovery document is reachable and matches, then prefills them for your stack.

​
Order of steps

The redirect URI contains the Secure Viewer’s URL, which exists only after the stack is created. So you set up the client in two passes:
1

Create the client

Create the OIDC client in your identity provider, the decryptor group, and the group and email claims. Note the issuer, client ID, and audience.
2

Install the stack

In Corsa, choose Your identity provider (OIDC), enter the values, and deploy the stack.
3

Add the redirect URI

Copy the redirect URI (the stack’s OidcRedirectUri output) and add it to the client’s redirect URIs. For Okta, also add the Secure Viewer’s address (the stack’s ViewerUrl output) as a trusted origin.
4

Complete setup

A workspace Owner who is in the decryptor group opens an encrypted field in Corsa and signs in through your identity provider. This first sign-in completes setup.

​
Example: Okta

1

Create the app integration

In the Okta Admin Console, go to Applications → Applications → Create App Integration. Choose OIDC - OpenID Connect and Single-Page Application.
  • Grant type: Authorization Code. Okta uses PKCE for single-page applications.
  • Sign-in redirect URIs: add a placeholder for now, for example https://localhost/oidc/callback. You’ll replace it after the stack is created.
  • Assignments: assign the decryptor group, or everyone who might decrypt.
2

Create the decryptor group

Go to Directory → Groups, create corsa-hyok-decryptors, and add the people who may decrypt.
3

Add the groups claim

Open the app → Sign On → OpenID Connect ID Token → Edit. Set Groups claim type to Filter, the claim name to groups, and the filter to Equals corsa-hyok-decryptors.
4

Enter the values in Corsa

5

Finish after the stack is created

Replace the placeholder sign-in redirect URI with the OidcRedirectUri output. Then go to Security → API → Trusted Origins and add the ViewerUrl output with CORS enabled.
If you use a custom authorization server, for example https://your-org.okta.com/oauth2/default, use its URL as the issuer and add the groups claim in that authorization server instead.

​
Example: Microsoft Entra ID

1

Register the application

In the Microsoft Entra admin center, go to Identity → Applications → App registrations → New registration. Under Redirect URI, choose Single-page application (SPA) and enter a placeholder, for example https://localhost/oidc/callback. Entra ID uses the authorization code flow with PKCE for SPA redirect URIs.
2

Create the decryptor group

Create a security group, for example corsa-hyok-decryptors, add the people who may decrypt, and note its Object ID.
3

Add the groups and email claims

In the app registration, open Token configuration:
  • Add groups claim: choose Security groups, or Groups assigned to the application, and emit Group ID in the ID and access tokens.
  • Add optional claim: choose ID and add email.
Make sure every decryptor’s Entra ID account has an email address that matches their Corsa account.
4

Enter the values in Corsa

5

Finish after the stack is created

In Authentication, replace the placeholder SPA redirect URI with the OidcRedirectUri output.
Entra ID emits group Object IDs, not group names, in the groups claim. If a user belongs to more than 200 groups, Entra ID leaves the groups out of the token, and that user can’t decrypt. Use Groups assigned to the application and assign the decryptor group to the app to avoid this.

​
How unwrap authorization works

Unwrapping a data key still needs two tokens, as with Cognito. Your identity provider’s token replaces the Cognito token. The Corsa unwrap token and resource binding don’t change.
  1. The user signs in to the Secure Viewer through your identity provider.
  2. Corsa checks that the user may view the record, then issues a short-lived Corsa unwrap token that names the user’s email and the requested fields.
  3. The Secure Viewer sends the wrapped data key to the decryption check in your account with both tokens.
  4. Your stack checks your identity provider’s token:
    • its signature, against the keys published by your issuer (your stack caches them for 10 minutes);
    • iss equals your issuer, and aud or client_id equals your audience;
    • it isn’t expired or not yet valid, with 60 seconds of tolerance;
    • the decryptor claim contains the decryptor value.
  5. Your stack checks the Corsa token as usual: its signature, expiry, your stack and workspace, and the requested field.
  6. The email claim in your token must equal the email in the Corsa token, ignoring case. This ties the person signed in to your identity provider to the Corsa user whose access Corsa checked.
  7. Only then does your stack use your KMS key to unwrap the data key.
So Corsa alone still can’t decrypt: it has no identity in your identity provider. And a user of your identity provider alone can’t decrypt either: they also need a Corsa token issued after Corsa’s access check, for their own email.

​
Grant and remove access

  • Grant: add the person to the decryptor group in your identity provider. They also need a Corsa account with the same email.
  • Remove: remove them from the group, or disable their account. Tokens already issued stay valid until they expire, so keep token lifetimes short. To stop all decryption at once, disable your HYOK key in AWS KMS. See Control access to decryption.

​
Limitations

  • One identity provider per stack. The stack trusts a single issuer and client.
  • Choose at install. The upgrade flow keeps your current identity provider settings. To switch between Cognito and your own identity provider later, contact Corsa. If you switch an existing Cognito stack, your Cognito users stay in your account. Delete them yourself when you no longer need them.
  • Public issuer only. Your stack fetches your issuer’s discovery document and keys from your AWS account over the internet. An identity provider that’s only reachable on your private network doesn’t work.
  • Algorithms. Only RS256 and ES256 token signatures are accepted.
  • Sign-in strength is yours. Corsa doesn’t add a passkey step. Enforce MFA for the client in your identity provider.
  • Revocation isn’t instant. Removing someone from the group takes effect when their current token expires. After you rotate your identity provider’s signing keys, your stack picks up the new keys within 10 minutes.
  • Email must match. Users whose email claim is missing, or differs from their Corsa email, can’t decrypt.
  • No hyok-decryptors Cognito group. The Cognito-specific steps in Setup, including the first administrator, don’t apply.