Two-factor authentication and single sign-on

Two-factor authentication asks for a code from your phone after your password, so a stolen password alone is not enough to get into SendKettle. Single sign-on lets your team log in with the account they already use at work, through any OpenID Connect provider.

Turn on two-factor authentication for your account

Everyone can do this for their own account, whatever their role.

  1. Click your name at the bottom of the menu and then Profile to open Your profile.
  2. In the Two-factor authentication box, click Set up two-factor authentication.
  3. Open an authenticator app on your phone, such as 1Password, Google Authenticator, Microsoft Authenticator or Aegis.
  4. Scan the QR code with the app. If you can't scan it, type the key shown under the QR code into the app. On a phone you can also tap Open in an authenticator app on this device.
  5. Type the 6-digit code the app shows and click Turn on two-factor.
  6. Save the ten recovery codes that appear. They are only shown once. Keep them in a password manager or print them.

The QR code is made on your own server. The secret key is never sent to another service, and it is stored encrypted.

If you change your mind before step 5, click Cancel setup.

Log in with a code

  1. Enter your email and password on the login page and click Log in.
  2. Type the 6-digit code from your authenticator app and click Log in.

A code works once and is valid for about a minute and a half, so a slightly slow phone clock is fine. After five wrong codes you have to enter your password again.

Codes by text message and security keys

Once the authenticator app is on, you can add other ways past the second step. At login you then choose the one that is at hand.

To get codes by text message (the first workspace needs an SMS provider under Settings, Channels):

  1. Open Your profile and go to Two-factor authentication.
  2. Under Codes by text message, type your mobile number with the country code and click Send a code.
  3. Type the code from the text message and click Turn on text message codes.

At login, click Text me a code and type the code you get. It works for 10 minutes.

To add a security key or passkey:

  1. Under Security keys and passkeys, give the key a name, for example "YubiKey".
  2. Click Add a security key.
  3. Touch the key, or confirm with your fingerprint, face or PIN when your browser asks.

At login, click Use a security key and touch the key. The site needs APP_URL set to the address you open it on, because keys only work on the site they were added on.

Turning off two-factor authentication also removes your phone number and security keys.

Lost your phone

  1. On the code screen, click Use a recovery code instead.
  2. Type one of your recovery codes and click Log in with recovery code.
  3. Go to Your profile and set up two-factor again on your new phone, or create new recovery codes.

Each recovery code works once. Your profile shows how many you have left. If you have none left and no phone, ask an Owner or Admin to help: they can remove your account and invite you again.

New recovery codes or turning it off

  1. Go to Your profile.
  2. Type your current password in the Two-factor authentication box.
  3. Click Create new recovery codes (the old ones stop working) or Turn off two-factor.

A password reset link does not skip the code. After you set a new password you log in with it and your code.

Changing or resetting your password logs you out everywhere else: other browsers, phones and "remember me" logins have to log in again with the new password. Your API keys are revoked too.

Require two-factor for everyone

Installation admins (the Owners of the first workspace, see Workspaces) can make two-factor authentication required and set up single sign-on.

  1. Go to Settings and open the Security tab.
  2. Tick Require two-factor authentication for everyone.
  3. Click Save security settings.

People without two-factor are sent to their profile to set it up the next time they open a page. Until they do, they can only set up two-factor, change their language and theme, read help and Log out: no API keys, email or password changes, and their existing API keys, connected apps (such as an AI assistant) and SMTP relay logins stop working. While it is required, nobody can turn their own two-factor off.

People who log in with single sign-on and have not set up two-factor here are not asked to, because your identity provider checks them. Turn on a second factor at your provider if you want one for them too. Someone who did turn on two-factor here still types their code after single sign-on.

Set up single sign-on

Single sign-on works with any provider that supports OpenID Connect, for example Microsoft Entra ID, Google Workspace, Okta, Auth0, Keycloak and Authentik.

  1. Go to Settings and open the Security tab.
  2. Copy the Redirect URL shown in the Single sign-on box.
  3. At your provider, register a new web application (sometimes called a client or app registration). Paste the redirect URL there. Allow the openid, email and profile scopes.
  4. Copy the issuer URL, the client ID and the client secret from your provider.
  5. Back in SendKettle, tick Turn on single sign-on and fill in Issuer URL, Client ID and Client secret.
  6. Optional: change Button text on the login page, for example to "Log in with Acme".
  7. Click Save security settings.

When you save, SendKettle reads the provider's configuration from the issuer URL to check that it works. The issuer must be a public https address. The client secret is stored encrypted. Leave the secret field blank later to keep the current one.

The login page now shows a button for single sign-on above the password form. Passwords keep working, so you can always log in if the provider is down.

Single sign-on with SAML

For providers that use SAML 2.0 (Okta, Microsoft Entra ID, Google Workspace, OneLogin, Keycloak and others), use the SAML single sign-on box on the same tab. You can use SAML, OpenID Connect or both.

  1. Go to Settings and open the Security tab.
  2. In the SAML single sign-on box, copy the Entity ID (audience) and the ACS URL (reply URL). Download metadata gives both in one file, if your provider can import it.
  3. At your provider, create a SAML application with those two values. Set the NameID to the email address, or send it in an attribute called email. Let the provider sign the assertion with RSA-SHA256.
  4. Copy the provider's entity ID (also called issuer), its login URL (SSO URL) and its signing certificate.
  5. Back in SendKettle, tick Turn on SAML single sign-on, fill in Identity provider entity ID, Login URL (SSO URL) and paste the Signing certificate.
  6. If the email address is in another attribute, type its name under Email attribute.
  7. Click Save SAML settings.

The login page now shows Log in with SAML single sign-on (or the button text you chose). SendKettle only accepts answers that are signed with that certificate, meant for this app, sent to the ACS URL, still valid and started from its own login page; each answer works once. Encrypted assertions are not supported. Automatic accounts, the default role and the allowed domains under Who may log in apply to SAML too.

Tick Require single sign-on for linked accounts and the allowed domains to turn passwords off for everyone who is linked to the provider or whose address is on your Allowed email domains. They can't log in with a password or ask for a reset link, so the provider's second factor, conditional access and offboarding always apply. Owners keep their password, so you can still get in when the provider is down.

Who may log in

  • Someone who has logged in with single sign-on before is recognised by their provider account, even if their email address changes.
  • Someone who already has an account here with the same email address is linked to it only when the provider confirms the address is verified (email_verified), and only after they log in here once with their password (and code) in the same browser within ten minutes. The login page asks for this. An address on your Allowed email domains is not enough on its own.
  • Someone new gets an account only when Create an account for new people the first time they log in is ticked. They get the Role for new accounts, which can be anything up to Admin. Owners are always invited by hand.
  • When Allowed email domains is filled in, only addresses on those domains can log in with single sign-on.

Without automatic accounts, invite people first on the Users page, then they can log in with single sign-on.

When it does not work

The login page shows the reason, and the audit log records a "Failed single sign-on" entry. Common causes:

  • The redirect URL at your provider does not exactly match the one in Settings.
  • The client ID or secret was copied with a space at the end.
  • The provider does not share the email address. Allow the email scope.
  • The address is not on your allowed domains, or there is no account and automatic accounts are off.