Skip to content

    Type a page, a command such as keryn scan, or a rule id.

    Single sign-on and directory sync

    View as Markdown

    Your people sign in to your Keryn Cloud organization through your company’s identity provider, leavers lose access when your directory says so, and you can see who did what.

    Everything on this page is done by an owner or admin of the organization in the Keryn account (api.keryn.app/account) under Enterprise. Changes to sign-in settings, members and keys ask for a code from your authenticator app first.

    Feature Status
    Sign-in through OpenID Connect (authorization code flow with PKCE) Available
    Sign-in through SAML 2.0 (signed assertions, started from Keryn) Available
    Prove your domain with a DNS record Available
    Require sign-in through your identity provider Available
    Remove people through SCIM 2.0 directory sync Available
    Organization API keys and service accounts that say who created them Available
    Roles: Viewer, Triage, Member, Admin, Owner Available
    Audit trail of membership, role, key, sign-in setting and data changes Available
    Trust your identity provider yourself, without asking Keryn Coming
    Roles from identity provider groups (Viewer to Admin) Coming
    Teams that follow directory groups, and projects per team Coming
    Session length and idle timeout per organization, sessions list with sign-out Coming

    Not supported: single logout (SAML SLO); sign-in started from your identity provider’s dashboard (IdP-initiated SAML, refused by design because it is a known attack path). Point your identity provider’s app tile at https://keryn.app/account instead.

    Tested with: signed test assertions and tokens from a test identity provider, including the refusal cases, and a SAML round trip with mocksaml.com. No real Okta, Microsoft Entra ID or Google Workspace tenant has been tested end to end yet; plan a test sign-in before you require the connection.

    When Trusted identity provider appears under Enterprise, enter the provider’s HTTPS origin (for example https://example.okta.com) and confirm with your authenticator code. Your organization needs a domain verified by DNS or an already verified SSO connection. If the card is unavailable, contact Keryn support with the HTTPS origin.

    Then open Enterprise > Add a connection. Keryn names the connection after your domain (example.com becomes example-com); you need that name for the addresses below.

    OpenID Connect (Okta, Microsoft Entra ID, Google Workspace, Auth0, Keycloak)

    Section titled “OpenID Connect (Okta, Microsoft Entra ID, Google Workspace, Auth0, Keycloak)”
    1. In your identity provider, create a web application (confidential client, authorization code flow):
      • Redirect URI: https://api.keryn.app/api/auth/sso/callback/<connection-name>
      • Scopes: openid email profile
    2. In Keryn, enter the company domain, the Identity provider issuer (for example https://example.okta.com), choose OpenID Connect, and enter the client ID and client secret. Keryn reads the issuer’s discovery document and always uses PKCE.
    1. In your identity provider, create a SAML application:
      • ACS URL: https://api.keryn.app/api/auth/sso/saml2/sp/acs/<connection-name>
      • SP entity ID: https://api.keryn.app/api/auth/sso/sp
      • NameID: the email address. Sign the assertions.
    2. In Keryn, enter the company domain, the issuer (your identity provider’s entity ID), choose SAML 2.0, and enter the sign-in URL and the signing certificate.

    Keryn accepts only a response to a sign-in it started, once, with a validity window (NotBefore and NotOnOrAfter). Unsigned assertions are refused.

    Show DNS record gives a TXT record named _better-auth-token-<connection-name>.<your domain>. Publish it, then choose Verify domain. Until the domain is verified the connection does nothing. Once it is verified, anyone who types an address on that domain at sign-in goes to your identity provider.

    Sign out, sign in through the connection once, then open Enterprise > Sign-in policy, choose your domain under Require sign-in through and save. Keryn refuses to require a connection you have not just signed in through, so you cannot lock yourself out.

    Access method or setting When sign-in through your identity provider is required
    Password, emailed link, passkey, GitHub, Google or Microsoft sign-in The person can still sign in to Keryn, but nothing in your organization answers until they sign in through your identity provider.
    Invitations Go only to addresses on the connection’s verified domains.
    Devices paired earlier (browser, desktop app, CLI) Signed out when you turn the requirement on; the save tells you how many. People pair again through your identity provider.
    Organization API keys and service accounts Keep working. They are not people (see below).
    Authenticator code Optional on top: an authenticator check at most 8 hours old for access to the organization.

    A membership ends when an admin removes the member, the member leaves, or your directory deactivates or deletes them over SCIM. To connect your directory, open Enterprise > Directory sync, create a token, and give your identity provider the endpoint https://api.keryn.app/api/auth/scim/v2 with that token. The token is shown once.

    From the moment a membership ends:

    • the person’s sessions no longer reach your organization;
    • every device they paired for your organization stops working, and adding the person back does not revive a device an admin revoked;
    • the audit trail records who removed them.

    Developers lists API keys and devices:

    • Paired by a person: approved from a client, and it stops when that person leaves.
    • Service account from an admin: made for automation. It belongs to the organization, outlives the admin’s membership and works until it expires or is revoked.

    Each shows who created it. When an admin leaves, review the service accounts listed as theirs and revoke or reissue them.

    Role May do
    Viewer Read results, scans and usage. Never scans.
    Triage Viewer, plus record decisions on findings. Scans only when given scan access individually.
    Member Triage, plus scans when the sign-in policy, or their own access, allows.
    Admin, Owner Everything, including people, keys, devices, sharing, sign-in settings, audit and data.

    Invitations default to Viewer. A role change applies at once to the person’s sessions and to every device they paired. Nobody can raise their own role or invite someone above their own. Every organization’s data is kept apart, and that separation is tested on every change to Keryn Cloud.

    Coming: letting your identity provider’s groups decide each person’s role at every sign-in (the strongest listed role wins, and a person in no listed group becomes a Viewer), teams whose members follow a directory group, and projects given to a team. Owners will never change, and a sign-in without groups will count as no groups, so a misnamed claim lowers access rather than granting it.

    Data > Audit trail lists membership, role, invitation, team, key, device, sign-in setting, sharing and data changes, with who made them and when, and exports them as a file. Admins see it; members do not.

    A person can belong to up to three organizations, and a sign-in session lasts up to 7 days.