Configure SSO with Google, Microsoft, Okta, and Keycloak

For the complete documentation index, see llms.txt. For a full content snapshot, see llms-full.txt. Append .md to any kestra.io/docs/* URL for plain Markdown.

Available on:Enterprise EditionCloud

Single Sign-On (SSO) lets users authenticate to Kestra using an external identity provider such as Google, Microsoft, Okta, or Keycloak.

Configure OIDC

Kestra supports SSO using the OpenID Connect (OIDC) protocol, a simple identity layer built on top of OAuth 2.0. Enable OIDC in your configuration file:

micronaut:
  security:
    oauth2:
      enabled: true
      clients:
        oidc-provider:
          client-id: "{{ clientId }}"
          client-secret: "{{ clientSecret }}"
          openid:
            issuer: "{{ issuerUrl }}"

Replace oidc-provider with your chosen provider’s name, {{ clientId }} with your client ID, {{ clientSecret }} with your client secret, and {{ issuerUrl }} with your issuer URL.

For more configuration details, refer to the Micronaut OIDC configuration guide.

Users and groups

First login

Kestra identifies an SSO user by their email. When no Kestra user has this email yet, Kestra creates one only if one of the following gives them access:

  • One of the groups in the user’s groups claim exists in Kestra, in any tenant.
  • A tenant has a default role.
  • The user has a pending invitation. Kestra accepts it at login.

Otherwise, the login is refused and no user is created.

Group sync

Set kestra.security.oidc.groups-claim-path to the claim holding the user’s groups, for example groups. With LDAP in GROUP_SYNC_ONLY mode, the user’s LDAP groups are merged with the groups from the claim.

Group sync never creates groups. Create the groups in Kestra first, with the same names as the identity provider groups, and bind them to roles in each tenant (see RBAC). The names must match the values the identity provider sends: Microsoft Entra ID, for example, sends group object IDs rather than names by default.

At every login:

  • The user joins every Kestra group, in every tenant, whose name matches one of their identity provider groups.
  • The user leaves any group they joined through the identity provider that the identity provider no longer sends. Group memberships added manually in Kestra are kept.
  • When the user leaves the last group that gave them access to a tenant, they lose access to that tenant. They keep it only if a role, including a default role, is bound directly to them in that tenant, or if SCIM provisioned them there.

After group sync, a returning user must still have access to a tenant, or the login is refused.

Provider guides

Provider-specific setup guides:

Was this page helpful?