ServiceFloGuide

Single sign-on

With single sign-on, people press Sign in and land on your organisation’s own sign-in page: the one they already use for email. Their password is never typed into ServiceFlo, and whatever that page asks for (a code from a phone, for example) applies here too.

ServiceFlo speaks SAML 2.0, which Microsoft Entra ID, Okta, Shibboleth, Keycloak, Google Workspace and most others understand. The system that runs your organisation’s sign-in page is called the identity provider below.

In this alpha, single sign-on has been tested with made-up sign-ins only, not yet against each identity provider by name. Try it with one colleague before you tell everyone, keep the account you made at install (see “If it breaks”), and tell us what you had to change.

You need: a real install with HTTPS (see Install), and someone who can add an application to your identity provider. Often that is not you; the first two sections are written so you can send them on.

1. What to give your identity provider

Ask for a new SAML application (Entra ID calls it an “enterprise application”, Okta an “app integration”). Replace help.example.org with your site’s address:

They ask for Give them
Entity ID (also “Identifier” or “Audience URI”) https://help.example.org/saml2/metadata/
Reply URL (also “ACS URL” or “Single sign-on URL”) https://help.example.org/saml2/acs/
Name ID format Persistent. Any format works: ServiceFlo does not use the Name ID to find people.
Signing Sign the assertion (most do by default).

Once single sign-on is switched on (section 3), the same details are at https://help.example.org/saml2/metadata/ as a file an identity provider can read by itself.

Then ask them to send these details about each person. The names matter: they must match exactly.

Detail Name to send it under Needed?
Username uid Yes. Without it nobody can sign in.
Email address mail Strongly advised: ticket emails go here.
First name givenName Optional
Last name sn Optional
Full name displayName Optional

Choose the username with care. It is how ServiceFlo recognises a person, so it must be the same every time and never be handed to someone else. If you also connect a directory (directory.md), send the same username the directory uses (in Active Directory, the sAMAccountName), so that a sign-in and the directory meet in one account.

Microsoft Entra ID sends the email address and names under its own long names, and ServiceFlo understands those as they are. It sends no username, so add one: under Attributes & Claims, add a claim named uid with no namespace, and choose where it comes from, for example user.onpremisessamaccountname if your accounts come from Active Directory.

If your identity provider cannot change the names it sends, tell ServiceFlo their names instead with SAML_ATTRIBUTE_MAPPING (see the end of this page).

2. What to ask for back

One thing: the metadata URL. It is a web address that describes the identity provider (Entra ID: “App Federation Metadata Url”; Okta: “Metadata URL”). ServiceFlo reads it to learn where to send people and how to check that an answer is genuine.

The server ServiceFlo runs on must be able to open that address.

3. Switch it on

Add two lines to .env:

SAML_ENABLED=true
SAML_IDP_METADATA_URL=https://login.example.org/your-app/federationmetadata.xml

ServiceFlo builds its own addresses from WAGTAILADMIN_BASE_URL, which the install page had you set. Check that it is your real https:// address.

Then restart:

docker compose -f docker-compose.prod.yml up -d

4. Try it

  1. Open https://help.example.org/saml2/metadata/. You should see a page of XML. An error here means a setting in .env is wrong or missing.
  2. In a private window (so you stay signed in elsewhere), open your site and press Sign in. You should land on your organisation’s sign-in page, and after signing in, back in ServiceFlo under your own name.
  3. Open the menu under your name: the username shown should be the one you expected.

Who gets an account

  • Someone who already has an account with that username (whatever its capitals) is signed in to it. This is how your agents and admins keep their teams and roles.
  • Someone new gets a requester account at their first sign-in: they can ask for help and follow their requests, nothing more. If a directory is connected and knows them, their name and department are filled in from it. If they had only ever emailed the service desk, they keep those tickets.
  • To let in only people you have added, a superuser opens Settings › Installation › Usernames and sign-in and unticks Make an account at a person’s first single sign-on. Anyone else then sees a page telling them to ask the service desk.

Nobody becomes an agent or an admin by signing in. Add people to teams as in Your first hour.

Signing out

Sign out signs a person out of ServiceFlo, not out of your organisation. They land on a page that says so. On a shared computer they should close the browser too.

If it breaks

Single sign-on depends on a second system, so keep a way in that does not:

  • The account you made at install still works. Open https://help.example.org/signin/ and use its username and password, under the single sign-on button. Keep that password somewhere safe.
  • To turn single sign-on off, set SAML_ENABLED=false in .env and restart.
What you see Likely cause
An error at /saml2/metadata/ SAML_IDP_METADATA_URL is missing, mistyped, or the server cannot reach it.
“Sign-in did not work” after signing in The Reply URL or Entity ID at the identity provider does not match section 1 exactly (https, the host name, the final /), the assertion is not signed, or the two clocks differ by minutes.
“You have no account here yet” No uid was sent, so ServiceFlo cannot tell who it is; or account-making is off and this person has no account; or their account is switched off. Back office › Audit log, at the end of Settings, has a line for each.
Signed in as the wrong or a second account The username sent is not the one their existing account has. Compare the two, then fix what is sent as uid.

Settings in full

All go in .env. Only the first two are needed.

Setting What it does
SAML_ENABLED true switches single sign-on on.
SAML_IDP_METADATA_URL The identity provider’s metadata URL.
SAML_SP_BASE_URL ServiceFlo’s own address, if it differs from WAGTAILADMIN_BASE_URL.
SAML_ENTITY_ID ServiceFlo’s entity ID, if your identity provider insists on a particular one.
SAML_CREATE_UNKNOWN_USER false stops a first sign-in from ever making an account, whatever the Settings page says.
SAML_ATTRIBUTE_MAPPING The names your identity provider sends, if not those in section 1. Setting it replaces the built-in list, so name every detail you want.
SAML_SP_KEY_FILE, SAML_SP_CERT_FILE A key and certificate of ServiceFlo’s own, only if your identity provider wants encrypted answers.

An example of SAML_ATTRIBUTE_MAPPING, for an identity provider that sends the username as employeeLogin and the email address as emailAddress:

SAML_ATTRIBUTE_MAPPING={"employeeLogin": ["username"], "emailAddress": ["email"], "displayName": ["full_name"]}