Configure Basic Auth and OIDC Login in Kestra

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

JWT signing keys secure session tokens and must be identical 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

micronaut:
  security:
    token:
      generator:
        access-token:
          expiration: 36000
      cookie:
        cookie-max-age: 10h

Basic authentication

The default installation comes with no users defined. An administrator account is created with the CLI:

./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.

OIDC is enabled in the 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.

OTP is enabled via the following configuration:

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)