Identity Providers

A new custom Zone has no sign-in until you select an Identity Provider for it. For the full setup with Okta, Microsoft Entra ID, Auth0, Google, PingOne or another OpenID Connect provider, follow Authenticate users with your identity provider. The steps below are a shorter version of the same setup. For end-to-end walkthroughs, see the tutorials for Okta, Microsoft Entra ID, Ping Identity, and Auth0.

• A custom Zone, and the Manager Role on it. See Custom Zones.
• An identity provider that supports OpenID Connect and puts the person’s email in the ID token. Keycard doesn’t sign people in over SAML.

1. Switch to the Zone and get its Redirect URL

   • In Keycard Console, switch to the custom Zone, because Keycard creates a Provider in the Zone you’re in. If you aren’t already in it, go to Zones, open the ⋯ menu on the Zone’s card, and select Switch to zone
   • Click Settings under Zone in the sidebar; on the Connection tab, copy the Redirect URL
   • Keep this URL handy for the next step

2. Configure your identity provider

   • Okta
   • Auth0
   • Google
   • Other Provider

   In Okta:

   1. Navigate to Applications → Create App Integration
   2. Select OIDC - OpenID Connect and Web Application
   3. Add the Redirect URL to Sign-in redirect URIs
   4. Keep the Authorization Code grant type. Sign-in doesn’t use Refresh Token
   5. Assign users to the application
   6. Note your Client ID and Client Secret. The Issuer URL is your Okta domain

   In Keycard Console:

   1. In the Zone, open Providers and click Add Provider
   2. Enter a Name, such as “Okta”
   3. Enter Issuer URL: https://<your-domain>.okta.com
   4. Enter Client ID and Client Secret
   5. Click Create Provider

   For the full walkthrough, see Connect Okta.

   The Issuer URL must equal the provider’s issuer value character for character, including any trailing slash. To find it, open the issuer URL without its trailing slash, followed by /.well-known/openid-configuration (for example https://<your-tenant>.auth0.com/.well-known/openid-configuration), and copy the issuer value exactly. Keycard doesn’t check it when you save the Provider, so a mismatch shows up later, at sign-in.

3. Select the identity provider for the zone

   In Keycard Console:

   1. Still inside the Zone, open Settings
   2. Select the Settings tab
   3. In the Zone sign in configuration section, open the Identity Provider dropdown and select the provider you just configured
   4. Click Save Changes

   Enable directory sync, below the Zone sign in configuration section, can be turned on once the Zone’s Identity Provider is saved. The Zone gets its own SCIM Base URL and sync tokens. Changing the Zone’s Identity Provider later makes those tokens stop working.

Policies can read the groups claim your provider puts on the ID token, as context.subject_claims.groups. Most providers don’t send it until you ask. The claim is a snapshot of membership at sign-in: a change in the provider reaches policy only in sessions that start after the user signs in again. An agent that already holds a refresh token keeps the earlier groups; see What Keycard receives from your identity provider. For membership that policy reads on every request, use Keycard Groups instead; the policy owner treats the claim as legacy (see Groups versus the IdP groups claim).

1. Add the claim in your provider

   In Okta, open the application’s Sign On tab, expand Advanced Settings, and under Group Claims click Edit:

   Field	Value
   Groups claim type	Filter
   Groups claim filter	Name: groups, Filter: Matches regex, Value: .*

   That sends every group. For production, narrow the regex to the groups Keycard needs. Other providers have an equivalent setting; Keycard reads the claim named groups.

2. Ask Keycard to request it

   In Keycard Console, open Providers, select the provider, open Configuration, expand Advanced options, and add groups to Additional Scopes. Keycard then requests the claim at every sign-in.

3. Sign in again

   Users who are already signed in keep their old session until it ends. Have them sign out and back in, and the new session carries the claim. To try a rule against the claim before anyone signs in, use the Subject groups field in Run test.

Access Snowflake uses this setup end to end with an Okta data-analysts group.

Sign-in fails with access_denied: no email address

• Keycard creates a User from the email claim in the ID token and doesn’t read the provider’s userinfo endpoint. Without the claim, Keycard stops the sign-in with access_denied and returns the error to the Application when it can. The error description reads “Identity provider did not supply an email address.”
• Configure the provider to include email in the ID token, then have the User sign in again

OAuth flow fails or redirects to error page

• Verify the Redirect URL is correctly added to your identity provider
• Ensure your identity provider’s issuer URL is correct: open the issuer URL without its trailing slash, followed by /.well-known/openid-configuration, and copy the issuer value exactly, including any trailing slash
• Check that users are assigned to the application in your identity provider

A policy that reads the groups claim never matches

• Confirm the provider sends a claim named groups and the user is in the group the rule names
• Confirm groups is in the provider’s Additional Scopes in Keycard
• Have the user sign out and in again; the claim is read at sign-in, so a membership change waits for the next session. An agent that connected before the change keeps the earlier groups for up to 90 days, because its refresh token keeps using the groups from sign-in. Disabling the person stops it; revoking a grant doesn’t.