Skip to main content

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:

FieldRequiredMeaning
slugyesA 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.
labelnoThe name people see. Defaults to the slug.
issueryesYour 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_idyesFrom the application you register at your provider.
client_secretyes, unless a public clientEncrypted at rest and never returned; the API only says whether one is set.
is_public_clientnoFor a provider application that issues no secret. PKCE is always used.
scopesnoDefault openid email profile.
allow_jitnoDefault on: people signing in for the first time become members.
jit_rolenoThe role new members get: creator (default), presenter, analyst or viewer.
require_mfanoDefault off. See Requiring MFA.
extranoOptional 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.

  1. Claim it: POST /api/v1/sso/domains with {"domain": "example.org"}. A domain can be claimed by only one workspace across the whole deployment.
  2. Publish the DNS record the response gives you - a TXT record at _pollinator.example.org with a value of the form pollinator-verify=<token>.
  3. 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.

ProtocolEvidence accepted
OpenID ConnectThe 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.0The 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​

ActionAPI
List providersGET /api/v1/sso/providers
Change, enable, disable, rotate the secretPATCH /api/v1/sso/providers/<id>
Remove a providerDELETE /api/v1/sso/providers/<id>
List, claim, verify domainsGET / POST /api/v1/sso/domains, POST /api/v1/sso/domains/<id>/verify