Single sign-on
Murmle has no passwords. Every sign-in goes through an identity provider: one of the built-in providers, or your organisation's own.
Built-in providers
The deployment's operator can enable Panhari, Google, Microsoft and LinkedIn. The login page shows the ones that are configured, with Panhari first when it is enabled. Signing in with a built-in provider for the first time creates an account and a personal workspace.
When someone signs in with a new provider and their email matches an existing account, the two are linked only if the provider vouches for the address (Google's verified-email claim, for example). Microsoft accounts never vouch for an email in this way - a Microsoft tenant administrator can give a user any address - so a Microsoft sign-in whose email matches an existing account that signed up another way is refused rather than linked.
Your organisation's own provider (OpenID Connect)
A workspace can register its own OpenID Connect provider - Okta, Microsoft Entra ID, Keycloak or any other - without anything being deployed. SAML 2.0 is covered on its own page.
Registering a provider, claiming domains and verifying them are done by a workspace owner
through the workspace API under /api/v1/sso. Every change is recorded in the
audit log.
1. Register the provider
POST /api/v1/sso/providers:
| Field | Required | Meaning |
|---|---|---|
slug | yes | A short name, 1-64 lower-case letters, digits and hyphens, unique across the deployment. It appears in the sign-in and callback addresses. The built-in names (panhari, google, microsoft, linkedin, dev, sso) are reserved. |
label | no | The name people see. Defaults to the slug. |
issuer | yes | Your provider's issuer URL. Must be https://. Murmle reads the provider's endpoints from its discovery document, so moving the provider is a configuration change. |
client_id | yes | From the application you register at your provider. |
client_secret | yes, unless a public client | Encrypted at rest and never returned; the API only says whether one is set. |
is_public_client | no | For a provider application that issues no secret. PKCE is always used. |
scopes | no | Default openid email profile. |
allow_jit | no | Default on: people signing in for the first time become members. |
jit_role | no | The role new members get: creator (default), presenter, analyst or viewer. |
require_mfa | no | Default off. See Requiring MFA. |
extra | no | Optional overrides: email_claim, name_claim, mfa_acr_values. |
At your provider, register Murmle's callback address:
{MURMLE}/api/v1/auth/<slug>/callback
GET /api/v1/sso/providers also returns this address as a template.
A provider is created disabled. It cannot be enabled until the workspace has verified at least one email domain.
2. Claim and verify your domain
A workspace provider may only sign in addresses in domains the workspace has verified. This is what stops someone creating a workspace, registering a provider they control, and asserting an address at your company to take over that person's account.
- Claim it:
POST /api/v1/sso/domainswith{"domain": "example.org"}. A domain can be claimed by only one workspace across the whole deployment. - Publish the DNS record the response gives you - a
TXTrecord at_pollinator.example.orgwith a value of the formpollinator-verify=<token>. - Verify it:
POST /api/v1/sso/domains/<id>/verify. The answer says plainly what it found: "Verified.", "No TXT record found at ...", or "A TXT record exists at ... but does not match the expected value." DNS changes can take a while to spread; verify again later.
Verification is re-checked when you ask, and is reversible: a domain whose record has disappeared loses its verified status on the next check, so a lapsed claim cannot keep a provider trusted forever.
3. Enable it
PATCH /api/v1/sso/providers/<id> with {"is_enabled": true}, after testing the round trip.
How people sign in
People sign in through your provider at:
{MURMLE}/api/v1/auth/<slug>/authorize
The login page lists only the built-in providers, so share this address - on your intranet, or as the application link in your provider's portal.
On every sign-in Murmle checks that the address is in one of the workspace's verified domains. An address outside them is refused with "This sign-in method cannot be used with that email address", which deliberately does not name your domains.
Just-in-time membership
With allow_jit on, a person signing in through your provider for the first time gets an account
(if they have none) and membership of the workspace with the jit_role. A provider can never make
someone an owner or admin, and it never changes the role of someone who is already a member, so a
promotion or demotion inside Murmle is not undone at their next sign-in.
Requiring MFA
Murmle has no passwords, so there is no Murmle second factor to add: your identity provider
performs the authentication. With require_mfa on, Murmle requires the provider to prove
it used more than one factor, and refuses the sign-in otherwise with "Your organisation requires
multi-factor authentication" - it is never silently accepted.
| Protocol | Evidence accepted |
|---|---|
| OpenID Connect | The signed ID token's amr contains mfa, or its acr is one of the multi-factor PAPE policies, a multi-factor SAML context class, or a value in the provider's extra.mfa_acr_values (for example Keycloak's "2"). Only the ID token counts, and two single-factor methods do not add up to multi-factor. |
| SAML 2.0 | The assertion's AuthnContextClassRef is a multi-factor class: MultiFactorAuthentication, TimeSyncToken, SmartcardPKI, X509, or Microsoft's multipleauthn. |
This means Murmle can require that your provider performed MFA. It cannot offer MFA to someone
whose provider does not support it, and require_mfa is set through the API only.
Managing providers and domains
| Action | API |
|---|---|
| List providers | GET /api/v1/sso/providers |
| Change, enable, disable, rotate the secret | PATCH /api/v1/sso/providers/<id> |
| Remove a provider | DELETE /api/v1/sso/providers/<id> |
| List, claim, verify domains | GET / POST /api/v1/sso/domains, POST /api/v1/sso/domains/<id>/verify |