SAML single sign-on

Each organisation can connect its own identity provider with SAML 2.0. It is set up in the app under Settings → Security (/organisation/security), so it works in the cloud edition and in self-hosted installs alike, and every organisation on a shared deployment has its own provider.

Note

The deployment-wide OpenID Connect provider described in Single sign-on still works and is configured with environment variables. SAML is per organisation and is configured in the app. Both can be used at once.

How it works

1. A person opens Sign in with your company’s SSO (SAML) on the sign-in page (/auth/saml) and enters their work email.
2. Shield360 finds the organisation that has verified that email’s domain and sends them to its identity provider with a sign-in request.
3. The provider posts a signed response back to the organisation’s ACS URL. Shield360 checks it and signs them in.

Shield360 only accepts a response when:

• the assertion is signed by one of the certificates in the provider’s metadata (an unsigned assertion is refused, even inside a signed response, and a response carrying more than one assertion is refused);
• it comes from the provider’s entity ID and is addressed to this organisation’s entity ID (each organisation has its own audience);
• it is inside its NotBefore / NotOnOrAfter window, which it must have, and was issued in the last ten minutes;
• its InResponseTo matches a sign-in this organisation started in the last ten minutes, used once. Responses the provider sends unasked are refused unless IdP-initiated sign-in is turned on;
• its assertion ID has not been accepted before (replay protection).

Set it up

1. Copy the service provider details

Open Settings → Security. The first section lists the values your provider needs:

Field	Value
Entity ID (audience)	https://<your Shield360>/api/auth/saml/<organisation id>/metadata
ACS URL (reply URL)	https://<your Shield360>/api/auth/saml/<organisation id>/acs
Metadata URL	https://<your Shield360>/api/auth/saml/<organisation id>/metadata
Sign-in URL	https://<your Shield360>/api/auth/saml/<organisation id>/login

The binding is HTTP-POST for the ACS and HTTP-Redirect for the request. Shield360 does not sign its requests and does not need encrypted assertions.

2. Create the application in your provider

Follow the guide for your provider below, then give Shield360 the provider’s metadata: its URL (HTTPS, read when you save) or the XML pasted in. The metadata must contain an HTTP-Redirect single sign-on URL and at least one signing certificate. When the provider rotates its certificate, save the settings again to re-read the URL, or paste the new metadata.

3. Verify your email domain

Add your company’s email domain under Verified domains and publish the TXT record shown on the domain itself:

acme.com.  TXT  "shield360-domain-verification=<token>"

Then choose Verify. A domain belongs to one organisation. Until a domain is verified the sign-in page cannot route people to your provider, and the provider cannot sign in anybody who is not already a member.

4. Choose who may join, and with which role

• Existing members sign in through the provider straight away.
• Newcomers on a verified domain are admitted when the organisation’s Roles → New people → Joining setting is Anyone your identity provider signs in, when they hold an invitation, or when SCIM has provisioned them.
• The group-to-role mapping gives each person the role of the first listed group they belong to. People in no mapped group get the organisation’s default role. The mapping is shared with SCIM. It never gives the Auditor role, which only an auditor invitation can.
• Update roles at every sign-in re-applies the mapping each time, so leaving a group at the provider loses the role here.

Caution

An identity provider can only sign in an account that also belongs to another organisation when this organisation has verified that account’s email domain. Without that rule, one customer’s provider could claim another customer’s address.

5. Test, then require SSO

Sign in once through SAML. Then turn on Members must sign in with SAML: passwords, Google, GitHub and the hosted sign-in page stop working for members. The break-glass account (the organisation’s creator by default, or an owner or administrator you choose) keeps its password so that a broken provider never locks you out. Somebody who belongs to two organisations is held to the stricter one.

Entra ID (Azure AD)

1. Entra admin center → Enterprise applications → New application → Create your own application, “Integrate any other application you don’t find in the gallery”.
2. Single sign-on → SAML → Basic SAML Configuration:
   • Identifier (Entity ID): the Shield360 entity ID.
   • Reply URL (ACS URL): the Shield360 ACS URL.
   • Sign on URL: the Shield360 sign-in URL.
3. Attributes & Claims: Entra sends long claim names. Either set the attribute names in Shield360 to match, or add claims with short names:
   • email → user.mail
   • name → user.displayname
   • Add a group claim → Groups assigned to the application; under Advanced options choose Cloud-only group display names (or sAMAccountName for synced groups) and customise the name to groups. Without that, Entra sends group object IDs, and your mapping must use the IDs.
4. SAML Certificates → App Federation Metadata Url: paste it into Shield360’s metadata URL.
5. Users and groups: assign the people and groups who may sign in.

Okta

1. Applications → Create App Integration → SAML 2.0.
2. Configure SAML:
   • Single sign-on URL: the Shield360 ACS URL (leave “Use this for Recipient URL and Destination URL” ticked).
   • Audience URI (SP Entity ID): the Shield360 entity ID.
   • Name ID format: EmailAddress; Application username: Email.
   • Attribute statements: email → user.email, name → user.displayName.
   • Group attribute statements: groups, filter Matches regex .* (or a narrower filter).
3. Sign On → Metadata URL: paste it into Shield360’s metadata URL.
4. To let people start from the Okta dashboard, turn on Allow IdP-initiated sign-in in Shield360.
5. Assignments: assign people and groups.

Google Workspace

1. Admin console → Apps → Web and mobile apps → Add app → Add custom SAML app.
2. Google Identity Provider details: download the IdP metadata and paste the XML into Shield360.
3. Service provider details:
   • ACS URL: the Shield360 ACS URL.
   • Entity ID: the Shield360 entity ID.
   • Name ID format: EMAIL; Name ID: Basic Information → Primary email.
4. Attribute mapping: Primary email → email; First name or Last name → name; under Group membership, choose the groups to send and set the app attribute to groups.
5. Turn the app On for everyone (or for an organisational unit).

Google Workspace does not offer SCIM for custom SAML apps: provision people by inviting them, by letting your verified domain join automatically, or from another directory with SCIM.

Troubleshooting

Failed SAML sign-ins are recorded in the audit log (Govern → Records → Audit log, action auth.sign-in, reason saml_…) with the organisation and address, never the response itself.

Message	Cause
Single sign-on did not complete	The signature, audience, issuer, validity window or InResponseTo did not match. Re-read the metadata after a certificate rotation; check the entity ID and ACS URL.
Start the sign-in here	The provider started the sign-in and IdP-initiated sign-in is off.
This account belongs to another organisation	Verify the email’s domain.
Your account has been deactivated	SCIM has deactivated the person.