Enable different authentications and single sign-on

Raytha has four ways to sign in: email and password, a one-time code sent by email, JWT and SAML. You decide which ones are available to administrators and which to website users from Settings > Authentication. This page explains each method and walks through turning them on.

What you need

• The Manage System Settings permission.
• For one-time codes and password resets, working email. See Set up SMTP and email.
• For JWT or SAML, a system that can sign tokens or a SAML identity provider (IdP), and the Website URL set under Settings > Configuration so the addresses Raytha shows you are correct.

The Authentication screen

Open Settings > Authentication. Each sign-in method is a scheme. The list shows Label, Developer name, Type, and two switches: Admins and Users, each On or Off. Click a label to edit it. New scheme offers JWT and SAML.

Two schemes are built in and cannot be deleted:

Scheme	How people sign in	Starts as
Email address and password	They enter an email and password. Includes "Forgot password?" and, for website users, self-registration.	On for admins and users
Magic link	They enter an email address and receive a six-digit code, which they type in. The code is single use.	Off for both

Each scheme has Enabled for users and Enabled for admins. A person can only sign in with a scheme if it is enabled for their kind of account. Raytha will not let you switch off the last scheme that is enabled for administrators, so you cannot lock everyone out of the admin by accident.

Email address and password

This works with no setup. The settings you can change are:

Field	Meaning
Brute force max attempts	Failed sign-ins per email address before further attempts are refused. Default 10.
Brute force window (seconds)	How long failures count, and how long someone waits. Default 60.
Login button text	The label on the public login page.

After the limit, the person sees "Too many failed login attempts. Please try again later." A successful sign-in clears the count.

If you turn this scheme off for users, the website's registration and "Forgot password" pages also stop working, because they depend on it.

Magic link

1. Make sure email works.
2. Open Magic link in the list.
3. Tick Enabled for users, Enabled for admins, or both.
4. Set Magic link expiry (seconds). The default is 900 (15 minutes).
5. Click Save.

On the admin sign-in page you now see "Sign in with a one-time code". The code email comes from the template raytha_email_login_beginloginwithmagiclink. If the email does not arrive, nothing else will work; check the email log.

Single sign-on with JWT or SAML

With single sign-on, Raytha trusts another system to say who the person is. Either way the same rules apply:

• Raytha finds the account by the identifier from your system, then by email. If there is no match, it creates a new website user.
• Single sign-on never creates an administrator and never grants admin access. To let someone sign in to the admin this way, add them under People > Admins first, with the same email, then tick Enabled for admins on the scheme.
• Each sign-in updates the account's email and, when sent, first and last name.
• Deactivated accounts are refused.
• If your system sends group names, Raytha matches them to user group developer names. See Public users and user groups.

Create a JWT scheme

Use JWT when you already have an application that knows who the user is and can sign a token. The token is signed with a shared secret (HS256).

1. Click New scheme and choose JWT.
2. Enter a Label. It names the scheme in the list and on the admin sign-in page ("Continue with …").
3. Enter a Developer name. It becomes part of every sign-in URL and cannot be changed later.
4. Enter the Login button text shown on the public login page.
5. Enter the Sign in URL: the sign-in page of your application. Optionally enter a Sign out URL; Raytha never calls it, but templates can link to it.
6. Click Generate next to JWT secret and then the copy button, and keep the value for your application. Use at least 32 random characters if you type your own.
7. Tick JWT high security. It requires a unique jti in every token and accepts each one once, so a leaked link cannot be replayed.
8. Tick Enabled for users and/or Enabled for admins, then click Create.

The scheme's page now shows a JWT setup guide with the exact addresses for your site, a claims list, an example payload and signing snippets. In short, Raytha sends the browser to your sign-in URL with raytha_callback_url in the query string; your application signs a token with the person's email, name and optional groups, and sends the browser back to that callback address with token=… added.

Create a SAML scheme

Use SAML when your organisation has an identity provider such as Entra ID, Okta, Google Workspace or Keycloak.

1. Click New scheme and choose SAML.
2. Fill in Label, Developer name and Login button text as above.
3. Enter the Sign in URL: your IdP's SAML single sign-on URL (HTTP-Redirect).
4. Paste the IdP's signing certificate, PEM format with the BEGIN and END lines, into SAML certificate. Raytha verifies every response against it.
5. Enter Service provider entity ID (sent as Issuer). This is Raytha's own identifier, not the IdP's. Use the same value you give the IdP as the app's Entity ID or Audience. If the field is empty, a link offers a suggested value.
6. Tick the audiences and click Create.

In your IdP, set the assertion consumer service (ACS) URL to the address shown in the SAML setup guide on the scheme's page. It looks like https://your-site/account/login/saml/<developer name> for website users and https://your-site/raytha/login/saml/<developer name> for administrators.

The addresses

Purpose	Website users	Administrators
Start sign-in (link to this)	/account/login/sso/<developer name>	/raytha/login/sso/<developer name>
JWT return address	/account/login/jwt/<developer name>	/raytha/login/jwt/<developer name>
SAML ACS address	/account/login/saml/<developer name>	/raytha/login/saml/<developer name>

Add ?returnUrl=/a/local/path to a start link to choose where the person lands afterwards.

The developer documentation goes deeper: Single sign-on overview, JWT single sign-on and SAML single sign-on.

Check that it works

1. Open a private browser window.
2. For users, open /account/login. For admins, open /raytha. You should see a button for the new scheme: your Login button text for users, "Continue with <Label>" for admins.
3. Click it, sign in at the other system, and confirm you land on the site or the admin dashboard.
4. Open People > Users and check the new account, its name and its groups.

When only one scheme is enabled for users and it is single sign-on, /account/login redirects straight to your system, with no Raytha login page in between.

Gotchas

• Enabled for admins is not enough for a new admin. The administrator must already exist in Raytha with the same email.
• The developer name is permanent. It is in every URL you gave your IdP or application. Create a new scheme if you need another.
• Wrong addresses behind a proxy. The addresses are built from Website URL. If it is empty or wrong, the guide shows the wrong host. Set it under Settings > Configuration.
• Test the admin route in a second browser. Keep one signed-in admin session open until you have confirmed the new method works, so a mistake does not lock you out.
• Passwords for single sign-on accounts. A user created by single sign-on gets a random password nobody knows. They can use "Forgot password" if the built-in scheme is enabled for users.

Next steps

• Public users and user groups
• Single sign-on overview
• Set up SMTP and email
• Troubleshooting login problems