Skip to content
English
Contact us
  • There are no suggestions because the search field is empty.

Set up single sign-on (SSO) with SAML

Configure your identity provider so users can sign in to Simana with SAML 2.0.

Single sign-on (SSO) lets users sign in to Simana through an identity provider using SAML 2.0. You can use SSO on its own or add SCIM 2.0 provisioning to synchronise directory users and groups.

For automatic provisioning, see Set up automatic user provisioning with SCIM.

Before you begin

  • You need administrator access to the organisation in Simana and permission to create applications, configure SAML and assign users in your identity provider.
  • Use the Simana address your users will actually use when testing sign-in.
  • For SSO without SCIM, prepare a pilot user with an existing Simana account and confirmed direct membership of your organisation.

This guide uses generic identity-provider terminology. Menu names vary between providers; look for the equivalent application, SAML, claims and provisioning settings.

If you also plan to use SCIM: creating a provisioning token changes login eligibility for the organisation. Once provisioning is configured, users need an active SCIM mapping to sign in through SAML, including users who already have Simana accounts. Revoking or allowing tokens to expire does not remove that requirement. Plan and provision the pilot users before rolling provisioning out. Follow the SCIM setup article before testing those users.

1. Add the identity provider in Simana

  1. Sign in to Simana as an organisation administrator.
  2. Open the organisation’s administration panel.
  3. Find Identity providers, turn its switch on and open its cog.
  4. Select Add SAML identity provider.
  5. Open the new provider’s cog to reach Configure SAML identity provider.
  6. Set Name to a recognisable label, such as Organisation sign in. This label is also shown when users choose a sign-in provider. Leave the provider’s own switch off while configuring it.
  7. Copy Simana entity ID for the next step.

The SAML fields update as you edit them; this panel has no separate Save button. A new provider starts disabled. The organisation’s Identity providers switch enables identity-provider functionality for the whole organisation. Turning it off stops SAML sign-in and SCIM provisioning while retaining settings, tokens and templates.

2. Create a SAML application in your identity provider

  1. Open your identity provider’s administration console and find its applications area.
  2. Create a custom application or integration using SAML 2.0 and give it a recognisable name.
  3. Paste Simana entity ID into the service-provider identifier field, often called SP entity ID, Identifier or Audience. Copy the generated value from Simana; do not invent or edit it in the provider.
  4. Set Reply URL, ACS URL or Assertion Consumer Service URL to https://api.simana.app/saml/callback/. This URL is universal. Preserve the trailing slash. The ACS receives the sign-in response and is different from Simana entity ID.
  5. Configure HTTP-Redirect for incoming authentication requests and HTTP-POST for responses.
  6. Configure the application to sign its SAML response or assertion with the certificate you will copy into Simana. Simana requires a valid signature on at least one of them.
  7. Configure an unencrypted assertion. The current Simana flow expects a normal SAML Assertion rather than an EncryptedAssertion.
  8. Configure a stable, non-empty user subject, called NameID. Simana requests the unspecified NameID format. Keep the subject mapping stable so returning users retain their identity link.
  9. If your provider requires signed authentication requests, turn that requirement off for this application. Simana’s current authentication requests are unsigned.
  10. Save the application and assign a pilot user or pilot group.

Begin testing from the Simana login page. The current flow expects a response to a sign-in request started in Simana, with its request reference and RelayState.

3. Copy the IdP entity ID and SSO URL into Simana

  1. Open the application’s SAML configuration, setup instructions or federation metadata section.
  2. Find IdP entity ID or Issuer, copy the full value and paste it into Simana’s IdP entity ID. This identifies the identity provider issuing the SAML response; it is not the Simana entity ID. Simana checks the response and assertion issuer against this value.
  3. Find the Single sign-on URL or SAML SSO endpoint using HTTP-Redirect.
  4. Copy its complete HTTPS URL and paste it into Simana’s Single sign-on URL. Do not use the provider’s general homepage or application launch URL.

If these values are only available in metadata XML, download or open the file through the provider’s admin console and use these mappings:

Value Location in SAML metadata
IdP entity ID The entityID attribute on the relevant EntityDescriptor containing the provider’s IDPSSODescriptor.
Single sign-on URL The Location attribute on SingleSignOnService whose Binding is urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect.
Signing certificate The X509Certificate text within the relevant IdP KeyDescriptor for signing. A descriptor without an explicit use can also supply a signing key; confirm which certificate is active.

Metadata can contain several entities, endpoints or certificates. Use those for this application and its active signing key. See the SAML 2.0 metadata standard.

4. Add the signing certificate

  1. In the application’s SAML signing settings, identify the certificate currently used to sign responses or assertions.
  2. Download its public X.509 certificate in Base64 or PEM text format. If the download is binary DER, request a PEM or Base64 export instead.
  3. Open the text certificate and copy it in full, including -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- when present.
  4. Paste it into Simana’s Signing certificate field. Simana also accepts the Base64 certificate body from metadata without the PEM header and footer.
  5. Confirm that it matches the key the application actually uses.

Use the public signing certificate, never a private key. Paste certificate text, not a filename, URL or fingerprint. Do not substitute the certificate used for the provider’s HTTPS website. When the SAML signing key changes, update this field and retest sign-in; Simana does not automatically follow metadata changes.

5. Configure email and optional group attributes

  1. Open the application’s Attributes, Claims or Attribute mappings settings.
  2. Add an outgoing email attribute mapped to the directory value containing the user’s actual email address.
  3. Copy the outgoing attribute’s exact name into Simana’s Email attribute. Simana initially uses email; keep it only if your provider sends an attribute with that name. If the outgoing name is a URI, copy the entire URI.
  4. Ensure the pilot user has a valid value for the mapped email. Use the same email as their Simana account and, when using SCIM, their SCIM userName.
  5. If you want SAML group values included, add an outgoing group attribute, choose which groups it sends and copy its outgoing name into Group attribute. Otherwise, leave this field blank.
  6. Save the mappings in the identity provider.

Attribute names are configuration keys, not user values. Enter email, not a person’s email address; enter groups, not the name of one group. An email-like NameID alone is insufficient: Simana also requires the separate attribute named by Email attribute.

The optional SAML Group attribute lets Simana read group values from the assertion. It does not configure SCIM group synchronisation or grant memberships by itself. For provisioning and access rules, see Set up automatic user provisioning with SCIM.

Microsoft Entra: check the full outgoing claim name

The Attributes & Claims summary may show only a short name such as emailaddress, alongside its source, user.mail. Open Attributes & Claims → Edit → emailaddress to check Name and Namespace. Entra includes the namespace in the outgoing SAML attribute name.

For example, Name emailaddress with Namespace http://schemas.xmlsoap.org/ws/2005/05/identity/claims produces http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress. Enter that full string in Simana’s Email attribute, not emailaddress or user.mail. See Microsoft’s claim configuration guidance.

6. Enable and test SSO

  1. Confirm the Name, IdP entity ID, SSO URL, signing certificate, Simana entity ID and email attribute are populated.
  2. Return to Simana’s provider list and turn the provider’s switch on.
  3. Prepare the pilot user. For sign-in-only setup, use an existing Simana account with confirmed direct membership of the organisation. If provisioning is configured, first provision the user through SCIM and confirm they are active.
  4. Open a separate browser session and go to the normal Simana login page.
  5. Enter the pilot user’s email and select Continue. Simana redirects to a single eligible provider or offers a provider choice when several are eligible.
  6. Complete authentication in the identity provider.
  7. Confirm the user returns to Simana signed in, then reload and verify the session remains active.

Simana discovers providers from the user’s account and eligible organisation or identity links. Matching an email domain alone does not make a provider available.

Troubleshooting

Symptom What to check
Provider does not appear after entering an email Check for an existing Simana account and confirmed organisation membership for sign-in-only setup, or an active SCIM mapping for provisioning setup. Confirm both switches are enabled and the SAML configuration is complete.
Issuer or audience rejected Check that IdP entity ID matches the response issuer and the provider’s SP identifier matches Simana entity ID exactly.
Destination or recipient rejected Set Reply URL to https://api.simana.app/saml/callback/, including the trailing slash.
Signature rejected Check that the configured certificate matches the application’s active SAML signing key and the response or assertion is signed.
Subject or email missing Check that NameID is non-empty and the separate email claim’s outgoing name matches Email attribute.

Ongoing checks

Retest sign-in when the SAML signing key changes. Simana logout ends the Simana session and leaves the identity-provider session active. A later SSO login may therefore succeed without another credential prompt.

If you also use SCIM, verify intended access, group removal and user deactivation with pilot accounts before wider rollout. See the testing and lifecycle details in Set up automatic user provisioning with SCIM.