Authentication and single sign-on overview

Raytha signs people in through authentication schemes. Two are built in: email and password, and magic link. You can add any number of single sign-on schemes that use a JWT from your own app or a SAML identity provider. This page explains how the schemes fit together, the URLs they use, and how Raytha matches a sign-in to an account.

Choose a method

Method	Use it when	Who holds the credentials
Email and password	Visitors register themselves and admins sign in with a password.	Raytha
Magic link	You want passwordless sign-in for people who already have an account.	Nobody. Raytha emails a 6-digit code.
JWT	You already have a site or app with its own login, and Raytha should trust it.	Your app
SAML	Your organization signs in through Okta, Microsoft Entra ID, Google Workspace or another identity provider.	The identity provider

You can enable several schemes at once. The public login page then shows one button per scheme.

Add a scheme

1. Open Settings > Authentication in the admin. You need the system settings permission.
2. Create a scheme and choose JWT or SAML. Built-in schemes already exist and can be edited but not added again.
3. Fill in the fields below, then turn on Enabled for users, Enabled for admins, or both.
4. Open the scheme again. The setup panel shows the exact URLs to give your app or identity provider.

Field	Meaning
Label	The name shown to admins and on the admin sign-in button, as Continue with Label.
Developer name	Part of every URL for the scheme. Raytha lowercases it and turns anything other than letters and digits into an underscore. You cannot change it later.
Login button text	The text of the scheme's button on the public login page.
Sign in URL	Required for JWT and SAML. Where Raytha sends people to sign in. It must be a valid URL.
Sign out URL	Optional. Raytha stores it but never calls it. Signing out of Raytha does not sign anyone out of your app or identity provider.
JWT secret, JWT high security	JWT only. See JWT single sign-on.
SAML certificate, service provider entity ID	SAML only. See SAML single sign-on.
Enabled for users, Enabled for admins	Which kind of account may sign in with this scheme.

At least one scheme must stay enabled for admins, so you cannot lock everyone out by switching the last one off.

URLs

Every scheme has a start URL and a return URL for public users, and another pair for admins. Replace {name} with the developer name.

Purpose	Public users	Admins
Start sign-in	/account/login/sso/{name}	/raytha/login/sso/{name}
JWT token callback	/account/login/jwt/{name}?token=…	/raytha/login/jwt/{name}?token=…
SAML assertion consumer service	/account/login/saml/{name} (POST)	/raytha/login/saml/{name} (POST)

• Start links accept ?returnUrl=/members. After sign-in, Raytha sends the person there if it is a path on your site. Anything else is ignored and they land on the home page, or on the admin dashboard.
• Raytha builds the full URL from the Website URL setting plus the path base. Set it to your public address, such as https://example.com, or the identity provider and your app will be sent to the wrong place. See Configuration and Running behind a proxy.
• A start link works only when the scheme is enabled for that audience. For public users, any failure redirects to the home page. For admins, a scheme that is not enabled for admins answers 401.

How Raytha picks the account

1. It looks for an account with the same stable id (sub in a JWT, the NameID in SAML) that signed in through this scheme.
2. If none matches, it looks for an account with the same email address, across every account. A password account with that email is linked to the scheme.
3. If there is still no account, it creates a public user with a random password.

On every sign-in Raytha overwrites the account's email (unless another account already uses it) and, when sent, the first and last name. New accounts without a first name become SsoVisitor, and without a last name get a random one.

• Single sign-on never creates an admin. To let someone sign in to the admin, create the admin account first under People > Admins with the same email address, and enable the scheme for admins.
• The toggles apply by account type. An existing admin account needs Enabled for admins. Any other existing account needs Enabled for users. The URL you used does not matter. If both are off, every callback fails with Authentication scheme is disabled.
• Deactivated accounts are refused.

User groups

A groups claim or attribute carries user group developer names, such as editors. Raytha matches them exactly against the developer names of your user groups. If at least one matches, the person's groups become exactly the matched set. If none match, or the claim is missing, their groups are left alone. Raytha does not create groups from the claim.

The built-in schemes

• Email and password. Visitors can register at /account/create when the scheme is enabled for users. Passwords need at least 8 characters. Raytha blocks sign-in after repeated failures. The maximum attempts (at least 1) and the window (at least 60 seconds) are settings on the scheme.
• Magic link. Raytha emails a 6-digit one-time code that expires after the configured number of seconds (30 to 604800). It signs in existing, active accounts only, public users or admins depending on the scheme's toggles, and never creates one. It gives the same answer for unknown addresses, so the form does not reveal which emails have accounts. It needs working email sending.

Sign-in requests under /account/login and /raytha/login, including the single sign-on callbacks, share a limit of AUTH_RATE_LIMIT_PER_MINUTE requests per minute for each client IP address, 30 by default. Raytha answers 429 past it. Behind a reverse proxy, make sure Raytha sees the real client address, or every visitor shares one budget.

Gotchas

• The email match trusts your identity provider. Anyone who can issue a token or assertion with an existing user's email signs in as that user. Only point Raytha at a provider you control.
• Enabled for users does not gate new accounts. The toggles are checked against an account that already exists. A valid token or assertion for an unknown email creates a public user even when the scheme is enabled for admins only.
• Emails change on every sign-in. If your provider sends a different address for the same sub, the Raytha account follows it.
• Failures are terse. A failed callback answers 403, and the default 403 page does not say why. Debug on the public callback, whose checks match the admin one, after adding {{ Target.ErrorMessage }} to your 403 error template.
• Keep one working admin method. Test the SSO scheme for admins in a private window before you disable email and password for admins.
• The sign out URL does nothing. To offer sign-out-everywhere, link to your own page from a template.

Next steps

• JWT single sign-on: sign people in from your own app.
• SAML single sign-on: connect Okta, Entra ID or Google Workspace.
• Enable different authentications and single sign-on: the admin screens, step by step.
• API authentication: API keys are separate from sign-in.