Configure Basic Auth and OIDC Login in Kestra

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

Kestra supports three authentication methods: Basic Auth (enabled by default), OpenID Connect (OIDC), and passwordless One-Time-Password (OTP).

Configure JWT signing keys to secure session tokens. These keys must be the same across all Webserver instances.

micronaut:
  security:
    token:
      jwt:
        generator:
          refresh-token:
            secret: refresh-token-256-bits-secret
        signatures:
          secret:
            generator:
              secret: signature-256-bits-secret

Basic authentication

The default installation comes with no users defined. To create an administrator account, use the following CLI command:

./kestra auths users create --admin --username=<admin-username> --password=<admin-password> --tenant=<tenant-id>

When using --admin, --tenant is required to specify which tenant the admin role applies to. Omit --tenant only when creating a user without group or role assignments.

Single sign-on (SSO)

Single Sign-On (SSO) is an authentication process that allows users to access multiple applications with one set of login credentials (e.g., Sign in with Google). Kestra supports SSO using the OpenID Connect (OIDC) protocol, which is a simple identity layer built on top of the OAuth 2.0 protocol.

Enable OIDC in your Micronaut configuration:

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

See the Micronaut OIDC configuration guide for full details. See Single Sign-On to configure SSO with Google, Microsoft, and other providers.

Passwordless (One-Time-Password)

Passwordless login lets users sign in without a password. When a user enters their email address, Kestra sends a one-time code to that address. The user enters the code to authenticate.

OTP requires a mail service to deliver codes. Configure the mail service before enabling OTP — see Enterprise and Advanced configuration for the full property reference.

Enable OTP and optionally tune its defaults:

kestra:
  security:
    one-time-password:
      enabled: true
      expiration: PT5M       # how long a code remains valid (default: 5 minutes)
      code-length: 6         # number of digits in the code (default: 6)
      rate-limit:
        max-requests: 10     # maximum code requests per window (default: 10)
        window: PT1H         # rate limit window (default: 1 hour)

Was this page helpful?