Authenticate users with your identity provider

This guide configures sign-in for a custom Zone. If you’re evaluating Keycard in your organization Zone, you can use your existing Keycard sign-in. For your team’s Console sign-in, see workforce SSO.

You need Manager access to a custom Zone and admin access to your identity provider. To test sign-in, have a protected MCP server or application in that Zone that you can connect a client to.

1. Copy your Zone’s redirect URL

   From your organization Zone, open Zones and choose ⋯ → Switch to zone on your Zone’s card. Inside the Zone, open Zone → Settings → Connection and copy the Redirect URL, not the Issuer URL above it.

   Keycard Console

   Location: Settings under Zone → Connection (inside the Zone)

   Zone configuration

   OAuthOAuth endpoints for the zone

   Issuer URL

   Base URL for OAuth/OIDC issuer (use this for MCP Server SDK configuration)

   https://<zone-id>.keycard.cloud

   Redirect URL

   Callback URL to configure in your Identity Provider (Okta, Google, etc.)

   https://<zone-id>.keycard.cloud/oauth/2/redirect

2. Register an application with your identity provider

   Create an OpenID Connect web application and use the URL you copied as its sign-in redirect URI. Keep its issuer, client ID, and client secret for the next step.

   Keycard requires an email claim in the ID token and sends the client secret using client_secret_post. Configure those settings with your provider:

   • Okta
   • Microsoft Entra ID
   • Auth0
   • Google
   • PingOne
   • Other OIDC

   In Okta Admin Console, open Applications and Resources → Applications → Create App Integration. Choose OIDC - OpenID Connect, then Web Application. Add the redirect URL under Sign-in redirect URIs, and assign the people who should sign in.

   Copy the client ID and secret from General. For Okta’s org authorization server, the issuer is https://<your-domain>.okta.com, without a trailing /.

   Full Okta walkthrough

3. Add the provider to Keycard

   In the same Zone, open Providers → Add Provider. Enter a name, the Issuer URL, Client ID, and Client Secret, then click Create Provider. Enter the Client ID and Client Secret even though Console marks them Optional; without them Keycard doesn’t use the application you registered.

   Keycard Console

   Location: Providers → Add Provider (inside the Zone)

   Create provider

   Issuer URL *

   The OAuth issuer URL for your provider

   <issuer-url>

   Client ID Optional

   OAuth 2.0 client identifier for your provider

   <client-id>

   Client Secret Optional

   Optional for some providers, stored securely and encrypted by Keycard

   <client-secret>

   The issuer must match the issuer value in the provider’s discovery document exactly, including any trailing /.

4. Use the provider for Zone sign-in

   Open Zone → Settings → Settings. Under Zone sign in configuration, select the provider you created in Identity Provider.

   Keycard Console

   Location: Settings under Zone → Settings (inside the Zone)

   Zone configuration

   Zone sign in configuration

   Identity Provider

   Choose an identity provider to use for the zone sign in. Go to Providers

   Microsoft Entra IDExternal OAuth

   Click Save Changes.

1. Connect a client to your protected server or application in the Zone.
2. Sign in through your identity provider with the account you want to test. The client should finish connecting. If you’re already signed in, you may see consent screens instead: allow access on each.
3. In Keycard Console, open People and confirm that account’s User appears in the Zone. A first sign-in creates the User unless your directory already provisioned it.

Your identity provider now authenticates users for this Zone. Your policies determine their access to its resources.

To make access depend on directory membership, configure your provider to include a top-level groups claim in the ID token. The setup depends on your provider:

Provider	Group configuration
Okta	On the application’s Sign On tab, add a Group claims filter named groups. Request the groups scope in Keycard for the org authorization server. For a custom authorization server, add a groups claim on the server: set Include in token type to ID Token and Always, and Include in to Any scope. Ensure its access policy includes this application, and don’t request the groups scope.
Microsoft Entra ID	Add a groups claim under Token configuration. Policies compare group object IDs, not names. Don’t request a groups scope.
PingOne	Under Attribute Mappings, map groups to Group Names.
Auth0 or Google	These integrations don’t supply the groups claim Keycard reads. Use Keycard Groups instead.

When your provider requires a groups scope, open its Configuration → Advanced options in Keycard, add groups to Additional Scopes, and save.

Limit the claim to the groups your policies need. Okta’s org authorization server fails sign-in above 100 matching groups; Entra omits the claim above 200; PingOne replaces lists over 25 values with [SIZE_LIMIT_EXCEEDED].

A new Zone lets every signed-in person through by default, so a group rule changes access only in a Policy Set of your own. See Build a custom Policy Set.

Write a policy using context.subject_claims.groups, then use Run test to check the rule against the group values you expect.

Group changes don’t update existing authorizations immediately. Existing refresh tokens can retain earlier group values. To stop new credentials when access must end, disable the person in Keycard.

How identity claims and group changes reach policy

Keycard reads the ID token from your provider. It requests openid, profile, and email, plus the Provider’s Additional Scopes, and doesn’t call the provider’s UserInfo endpoint.

Claim	How Keycard uses it
iss and sub	Recognize the provider account and link it to a User in the Zone.
email	Set the User’s email when sign-in creates the User, or link the sign-in to a User that directory sync created with the same email. Later sign-ins don’t update it.
groups	Store a snapshot of group membership with the sign-in session.
User Identifier Claim, if configured	Set the User’s identifier at creation, which becomes sub in Keycard-issued tokens.

Policy receives context.subject_claims.email and context.subject_claims.groups. Other identity-provider claims don’t reach policy.

Change	When it takes effect
Someone joins or leaves a group in your provider	In sessions that start after they next sign in to the Zone through your provider.
An agent was already authorized for them	The agent keeps the groups it got at authorization until its refresh token expires, up to 90 days later, even if the person signs in again. Revoking a grant doesn’t refresh them; to cut off access sooner, disable the person in Keycard.
Someone joins or leaves a Keycard Group, including one that directory sync fills	On the next request. Policy reads Keycard Groups every time it evaluates.
You disable the person in your provider	They can’t sign in again. Agents already authorized for them keep working until you disable the person in Keycard, or directory sync, if you use it, deactivates their User.

Keycard Groups, including SCIM-synced groups, are read on every request. SCIM provisioning creates and updates directory records; it doesn’t sign users in.

A Keycard access token carries the User identifier and requested scopes, not email or groups. Policy allows or denies the requested scopes; Keycard doesn’t trim them to an allowed subset. See Token claims.

No User Identity Provider configured in Zone

Your client reports invalid_request: No User Identity Provider configured in Zone. Select your provider in Zone → Settings → Settings → Identity Provider and save. If it isn’t listed, it belongs to another Zone. Switch to this Zone and create the Provider here.

Identity provider did not supply an email address

Configure the provider to include email in the ID token. In PingOne, add an email attribute mapping. In Entra, ensure the person’s account has an email address.

An account with this email already exists

The provider authenticated the person, but Keycard couldn’t create their User. Another User in the Zone, such as a disabled one, already has that email from the same provider, or the same identifier if you set a User Identifier Claim. Look up the account under People.

“This sign-in conflicts with an existing account” means the User is already linked to a different account at the same provider with that email. That can happen after an account is recreated, or after you replace a Microsoft Entra ID app registration, because Entra ID issues a different sub for each registration.

Grant access by directory group shows how to use an Okta group to choose the Snowflake role an agent can use on someone’s behalf.