Sign-in methods

People sign in to your instance with a username or with an email address. You choose one during setup, and it can't change once the first account exists.

Usernames

People create an account with a username and a password. The instance never asks for an email address, and features that send email, such as address verification and password resets, are off.

When someone forgets their password, they use their recovery kit. The app shows the kit when the account is created, and people can make a new one in their account settings. Using the kit sets a new password, signs the account out everywhere and gives the person a new kit.

Email addresses

People create an account with an email address, a username and a password. The instance sends email to verify addresses and reset forgotten passwords. rexctl asks for your email server during setup, and rexctl email set changes it later. Until email is set up, nobody can reset a forgotten password by email, and you can create a reset link for them.

Single sign-on

People can sign in through your own identity provider, such as Authentik or Keycloak, over OpenID Connect. Set it up in the admin panel on the "Instance Config" page, in the "Single Sign-On (SSO)" card. Fill in the details from your provider, turn on "Enable SSO" and register the "Redirect URI" that the card shows with your provider.

The issuer URL is required, and Fluxer only accepts sign-ins that your provider issued under it. It accepts the issuer with or without a trailing /. For Microsoft Entra ID, use your tenant's issuer, https://login.microsoftonline.com/<tenant>/v2.0, not /common. SSO that was set up without an issuer stays off until you add one. Upgrade first, then run rexctl config set sso.issuer <issuer URL> right away. Fluxer moves the existing links to the issuer when it finds the same provider there. Don't add the issuer before you upgrade, because older versions leave the links behind. People who are already signed in stay signed in, and if Require SSO is on, rexctl admins sign-in-link <admin> gets you in.

On an email instance, and whenever "Allowed Email Domains" is filled in, Fluxer only takes an email address that your provider marks as verified with the email_verified claim. Microsoft Entra ID doesn't send that claim. Add the optional xms_edov claim to the ID token in your Entra app registration, and Fluxer accepts it in its place. Register Fluxer as a single-tenant app. OneLogin also leaves email_verified out by default. Set your OneLogin app to send the email_verified claim, or every sign-in on an email instance is refused with SSO_EMAIL_NOT_VERIFIED.

Every URL for your provider has to use https and a public address. If your provider runs on your own network or in Docker next to Fluxer, run rexctl config set sso.allow_private_addresses true. The URLs still have to use https.

The browser opens your provider's sign-in page, and the API then connects to your provider from inside its container. When your provider runs on the same machine behind the same reverse proxy, the browser part can work while the API can't connect to the provider's public hostname, often because of hairpin NAT or IPv6 in Docker. Sign-in then fails after about 10 seconds, and the API logs say fetch failed. sso.allow_private_addresses doesn't help here. rexctl doctor checks that the API can load your provider's discovery document and connect to its token endpoint, and says which host failed and why. To fix it, run rexctl config edit and send the provider's hostname to this machine for the api service.

services:
  api:
    extra_hosts:
      - "id.example.com:host-gateway"

Your reverse proxy has to accept connections from Docker, for example by listening on every interface. You can also make the provider's hostname resolve to an address that the API container can connect to.

With "Automatically provision users on first SSO login" on, the first sign-in from someone new creates their account. This happens even when registration is closed or needs an invite, and if new accounts need your approval, they still wait for it. To choose who gets in, limit access to Fluxer at your provider or fill in "Allowed Email Domains". In single-community mode, "Community Roles From Groups" maps groups at your provider to roles in the community, and each SSO sign-in adds or removes those roles. If the provider leaves out the groups claim, the person loses every mapped role. Keycloak leaves the claim out when someone is in no groups. Entra leaves it out when someone is in too many groups. Limit the token to the groups you map.

When your provider's discovery document lists client_secret_post, Fluxer sends the client secret in the request body. When it lists no methods, or lists client_secret_basic and not client_secret_post, Fluxer uses HTTP Basic authentication first. If the provider turns the first attempt down with a 400 or 401 for any reason other than invalid_grant, Fluxer tries the other method once and remembers what worked. Fluxer doesn't follow redirects from your provider's discovery, token, userinfo or keys URLs, and each URL you enter has to be the one that answers. Fluxer can't use signed userinfo responses (application/jwt), and sign-in fails with SSO_USER_INFO_SIGNED_RESPONSE_UNSUPPORTED until you turn off userinfo signing for the client at your provider. When a sign-in fails at the provider, the API logs say what the provider sent back.

"Require SSO" turns off password and passkey sign-in and local registration for everyone. Before you turn it on, make sure at least one admin can sign in through your provider.

While Require SSO is on and your provider is down, nobody can sign in until it's back, and the sign-in page says the provider is unavailable. To get in, run rexctl admins sign-in-link <admin> for a one-time admin sign-in link, or rexctl config set sso.enforced false to turn Require SSO off. If SSO has no issuer yet, that command is refused. Set the issuer with rexctl config set sso.issuer <issuer URL>, or as a last resort turn SSO off with rexctl config set sso.enabled false. While Fluxer can't connect to your provider at its issuer URL, it refuses any SSO change that leaves Require SSO on.

If someone has two-factor authentication or a passkey on their Fluxer account, Fluxer asks for it each time they sign in with SSO on the web or in the desktop app, even if your provider asked for its own. The mobile app doesn't ask for it yet once the account is linked, and it still asks before an account is first linked by email.

On a username instance you can turn on "Usernames come from your sign-in provider" (sso.username_from_provider in rexctl). It's off by default and doesn't depend on Require SSO. While it's on, each SSO sign-in sets the person's username from the preferred_username claim, and people who sign in with SSO can't change it in Fluxer.

Usernames can only use letters, numbers and underscores, up to 32 characters. Fluxer keeps the part before any @, turns accented letters into plain ones, turns dots, dashes and spaces into underscores, drops other characters, removes the word fluxer and keeps the first 32 characters. For example, john.doe@corp.com becomes john_doe. Different people can end up with the same username. alice@corp.com and alice@partner.com both become alice, and whoever signs in first keeps it. If your provider sends an email address or UPN as preferred_username, such as Entra ID with more than one domain, map that claim to a value that is unique across your tenant.

If the claim is missing, isn't usable or belongs to someone else, the person keeps their current username. A rename in the admin panel lasts until the person's next SSO sign-in. Turn off username editing at your provider, or anyone who can edit their own preferred_username can take any free name here.

Existing accounts

When someone signs in with SSO for the first time and an account already has their email address, Fluxer only signs them in to that account if the instance sends email and the account's email address is confirmed. If the account has two-factor authentication, Fluxer asks for it first. Otherwise the sign-in stops and tells them to sign in to the account another way and connect single sign-on from their account settings in the web app.

People connect an existing account from their account settings in the web app, where a row for your provider has a "Connect" button. Fluxer asks them to confirm it's them first, the same way it does before other account changes, and connecting works while Require SSO is on. On a username instance, or an email instance that doesn't send email, this is the only way an existing account gets linked. Turn on SSO, ask people to connect their accounts and turn on Require SSO after that. If someone can't sign in to connect, an admin can link their account with PUT /admin/users/{user_id}/sso-identities.

Changing the issuer

Fluxer links each SSO account to the issuer it signed in through. When you change the issuer while accounts are linked to the old one, Fluxer asks what to do with those links. If it's the same provider at a new address, move the links so people keep their accounts. If it's a different provider, leave them, because the same subject there can be a different person. People then link to the new provider by their verified email the first time they sign in through it. In the admin panel, pick this under "SSO Links When the Issuer Changes". With rexctl, add --migrate-identities or --no-migrate-identities to rexctl config set sso.issuer <issuer URL>.

Fluxer moves the links without asking when only a trailing / changes, or when you add an issuer to SSO that had none and its authorization endpoint is the one already in use.

Fluxer can't tell a new address for the same provider from a different provider. If you moved the links to a different provider by mistake, sign-ins from it fail with SSO_ACCOUNT_LINKED_TO_ANOTHER_IDENTITY. Unlink those accounts with DELETE /admin/users/{user_id}/sso-identities, and each person links again by email at their next sign-in.

Removing someone

A session from an SSO sign-in lasts 30 days, and after that the person signs in through your provider again. Sessions that started before this version of Fluxer don't have this limit. If you turn someone off at your provider, they lose access at their next SSO sign-in, or the first time their app contacts Fluxer after their sessions are 30 days old. An app that stays connected keeps getting messages until then. To remove them right away, use "Terminate All Sessions" on their account's page in the admin panel. While Require SSO is off, they can still sign in with a password or passkey if they have one. Unlinking their SSO account with DELETE /admin/users/{user_id}/sso-identities signs them out on every device. Signing out of Fluxer doesn't sign anyone out of your provider.

Lost passwords

On a username instance, or an email instance that doesn't send email, you can create a reset link for someone who has lost their password. The "Create Password Reset Link" button on the account's page in the admin panel does the same.

rexctl users reset-link alex

The link works once and expires after an hour, and anyone who has it can set a new password for the account. Send it to the person over a channel you trust. Creating the link deletes their recovery kit, and they can make a new one in their account settings.

If you lose access to your own admin account on such an instance, rexctl users reset-link works on the machine without signing in. On an email instance that sends email, reset your password from the sign-in page.

More settings

The "Sign-in & new accounts" card on the "Instance Config" page has the other settings for new accounts, such as letting people start with just a display name and deleting accounts that have no way to sign back in.