Skip to main content

SAML 2.0

A workspace can sign people in through a SAML 2.0 identity provider. SAML providers live alongside OpenID Connect providers and follow the same rules: they are registered by an owner through the workspace API, created disabled, enabled only once a domain is verified, limited to the workspace's verified domains, and can require MFA.

Register the provider​

POST /api/v1/sso/providers with "protocol": "saml":

FieldRequiredMeaning
slug, labelslug yesAs for OpenID Connect.
idp_entity_idyesYour identity provider's entity id.
idp_sso_urlyesIts single sign-on URL. Must be https://.
idp_certificateyesIts signing certificate, PEM (-----BEGIN CERTIFICATE-----). Replace it with a PATCH when the provider rotates its key.
saml_email_attributenoThe attribute holding the email address, if not one of the usual ones (below).
allow_jit, jit_role, require_mfanoAs for OpenID Connect.

Then claim and verify a domain, and enable the provider, exactly as for OpenID Connect.

What to give your identity provider​

ValueAddress
Service provider metadata{MURMLE}/api/v1/auth/saml/metadata
Assertion consumer service (ACS), HTTP-POST binding{MURMLE}/api/v1/auth/saml/<slug>/acs
Audience / service provider entity id{MURMLE}/saml/metadata
Name ID formatEmail address

Enter the ACS address with your own slug in place of <slug>.

Murmle does not sign its authentication requests; an identity provider configured to require signed requests will not work with it. Assertions must be signed.

Signing in​

  • From Murmle: {MURMLE}/api/v1/auth/saml/<slug>/login starts a sign-in at your identity provider.
  • From your identity provider: IdP-initiated sign-in, such as an app tile in a portal, is supported.

Attributes​

Murmle needsRead from, in order
EmailThe configured saml_email_attribute; otherwise email, emailAddress, the claims-schema emailaddress, or urn:oid:0.9.2342.19200300.100.1.3; otherwise the Name ID if it is an email address.
NamedisplayName, name, or the Microsoft displayname claim.

Attributes match on either their Name or FriendlyName. New members get the provider's jit_role; group attributes in the assertion do not set roles (use SCIM for group-based roles).

What Murmle checks on every assertion​

A correctly signed assertion can still be hostile, so the signature is only the first check:

  • Signature, with claims read only from the element that was actually verified, which defeats XML signature-wrapping attacks.
  • Audience - an assertion minted for another service is refused.
  • Issuer - must be your configured identity provider.
  • Validity window - NotBefore and NotOnOrAfter, with 60 seconds of clock tolerance.
  • Recipient - must be this ACS address.
  • InResponseTo - must match a request Murmle made; must be absent for IdP-initiated sign-in.
  • Replay - each assertion id is accepted once.
  • Domain - the address must be in one of the workspace's verified domains.

The XML parser does not resolve external entities or fetch anything from the network.

Not supported​

  • Single logout: signing out of Murmle does not sign the person out of the identity provider.
  • Signed authentication requests (see above).