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":
| Field | Required | Meaning |
|---|---|---|
slug, label | slug yes | As for OpenID Connect. |
idp_entity_id | yes | Your identity provider's entity id. |
idp_sso_url | yes | Its single sign-on URL. Must be https://. |
idp_certificate | yes | Its signing certificate, PEM (-----BEGIN CERTIFICATE-----). Replace it with a PATCH when the provider rotates its key. |
saml_email_attribute | no | The attribute holding the email address, if not one of the usual ones (below). |
allow_jit, jit_role, require_mfa | no | As for OpenID Connect. |
Then claim and verify a domain, and enable the provider, exactly as for OpenID Connect.
What to give your identity provider
| Value | Address |
|---|---|
| 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 format | Email 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>/loginstarts 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 needs | Read from, in order |
|---|---|
The 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. | |
| Name | displayName, 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 -
NotBeforeandNotOnOrAfter, 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).