Developer
- Knowledgebase
- Developer

Developers

SAML 2.0 Single Sign-On (SSO)

06 Nov 2023
6 Minutes to read
Contributors

Print
Share
Dark
Light
PDF

SAML 2.0 Single Sign-On (SSO)

Updated on 06 Nov 2023
6 Minutes to read
Contributors

Print
Share
Dark
Light
PDF

Article summary

Did you find this summary helpful?

Thank you for your feedback

Setting up Single Sign-On using SAML 2.0

Cirrus supports the most-widely supported standard for Enterprise Single Sign-On (SSO): SAML 2.0 (Wikipedia ⧉).
Single Sign-On gives users access to Cirrus (as "Service Provider" aka "SP") via your organisation's login server, called "Identity Provider" aka "IdP". This way your organisation can control access to Cirrus and users do not have to remember a separate Cirrus username/password. The latter drastically reduced your maintenance effort by eliminating managing logins in Cirrus and most login questions to your helpdesk.

Key Benefits

Easy adoption and use - as users can use their existing username and password
Lower administrative burden - a.o. less forgotten password calls; a single system, namely yours, to deactivate users.
Optimal Compliance - using your organizations access and password policies and 2FA, especially in "Enforce" mode.

Requirements:

SAML 2.0 capable Identity Provider (IdP).

Single Sign-On Modes

SSO Mode	Automatic Redirect	Username/Password Login	Remarks
Mixed (SSO button on Login form)	No	Possible	Normal mode: User gets the option to login via SSO or using username/password.
Automatic (Login form available)	Yes	Possible via special URL	User gets send to Customer IdP unless going directly to special login form URL (base url + /#login, e.g. demo.cirrusplatform.com/#login)
Enforce (Login form disabled)	Yes	Disabled: 404 Error	User gets send to Customer IdP, username/password completely disabled.

Cirrus Service Desk Account

Before enabling "Enforce" ensure the Cirrus Service Desk has an active valid service user in the Customer IdP (or at least two personal users)

Exit URL

Unless a Exit URL is configured, the logout button will just redirect the user to the IdP and may be logged in again into Cirrus straight away.

Step 1. Setup service provider (SP) [in Cirrus]

Setting up SAML 2.0 can be via Admin > SAML Integration (listed under Web Services):

Check the option 'Enable SAML2 Authentication' - all further options will be unlocked for editing.
The link behind SAML SP metadata URL will produce the SAML Metadata XML document [Wikipedia] you normally need to configure your IdP. If you IdP cannot support such metadata URL you can open it manually and copy the required data.
NOTE: The link will return the correct metadata after all the SAML integration settings have been filled correctly and "Save configuration" clicked.
SAML Identity Provider name - enter the name that will be used on the login screen of your environment:

4. Enter the Login attribute name - this attribute from your side will be used for identifying users on the Cirrus side. NOTE: the login attribute name is case-sensitive.

5. Lookup user in Cirrus via - To lookup the user, this user field is searched with the value of the Login attribute name. Both user id (= external id) and username fields contain unique values in Cirrus. Select the appropriate value for your setup.

6. Metadata upload - Choose a way to import your identity provider metadata. Metadata via URL is the strongly preferred method but it can also be imported using a metadata xml but then note:

Metadata used for validation, must be kept up-to-date / available

The metadata is used by Cirrus to validate the authenticity and integrity of incoming SAML messages so it must be up-to-date and valid. If you import a metadata xml please add a reminder in your calendar to update it when it's current keys/certificates expire.
This is not needed when you use the metadata url, as Cirrus can and will retrieve the latest info from your Identity Provider (so it merely must be kept available!).

7. Single Sign-On Mode - See Single Sign-On Modes above for the full explanation.
NOTE: When choosing "Automatic" or "Enforced" you probably want to configure Exit URLs otherwise, the logout button will just redirect the user to the IdP and may be logged in again into Cirrus straight away. See Exit URL of the Administration guide.

Exit URL

Unless a [Exit URL](/exit-url) is configured, the logout button will just redirect the user to the IdP and may be logged in again into Cirrus straight away.

Step 2. Setup your Identity Provider (IdP) [at customer]

There are a lot of different Identity Provider solutions available on the market. The integration settings can be different for each solution. Common steps are:

Configure the Service Provider metadata URL provided by Cirrus. See SAML SP metadata URL field described under 2. of Step 1. If your Identity Provider cannot support a metadata URL you can copy its data but NOTE: your copy will not be automatically updated when the Cirrus metadata changes!
Ensure the Binding "Redirect" is configured ( "POST" and "Artifact" bindings are NOT supported)
Add attribute to be sent with the same name as you specified in Login attribute name under 4. of Step 1. NOTE: the login attribute name is case-sensitive.

NOTES

Cirrus supports SAML 2.0 for Authentication of existing users only

The provisioning and authorisation of users must be done in Cirrus Admin or External API. For Authentication Cirrus will check subject and validity. So-called "SAML Attributes" and (authorisation) claims will be ignored.

RelayState ignored (no deeplinking)

Currently Cirrus does not heed the RelayState parameter. In case you're interested to (co-)sponsor adding support please log a "Request for Product Enhancement".

SAML ForceAuthn is always disabled (false) on purpose so the customer will be in control of the behaviour of their IdentityProvider, e.g. to show a login even when opening a new tab, OR allow this login while the session has not yet expired.

Without metadata URL you must manually keep the metadata up-to-date!

If your Identity Provider cannot support a metadata URL you can copy its data but NOTE: your copy will not be automatically updated when the Cirrus metadata changes. Always use a metadata URL if your Identity Provider supports it!

TROUBLESHOOTING

In order to troubleshoot SAML 2.0 issues you need some minimal technical expertise as you, or your technician, need to be able to open the Developer Toolbar of your web browser (e.g. F12 in Chrome) and find the details of your SAML 2.0 request and response of the SAML_2.0 - Web browser SSO profile ⧉ (Wikipedia).

Information required for support

Your current metadata, see 6. Metadata upload; Recent reponse body of your metadata URL with valid "validUntil" (see
The SAMLResponse token in your request to our SAML endpoint with valid Cirrus user
A screenshot of your SAML setting screen in Cirrus

Example IdP Metadata and what to check

Taken from SAML metadata - Identity provider metadata ⧉ (Wikipedia).
In this example validUntil="2017-08-30T19:10:29Z" means Cirrus should not and will no longer accept this token, since Aug 30th, 2017

NOTE: if the URL your organisation configured under 6. Metadata upload - from URL no longer returns an XML like this example or validUntil is in the past, contact your own IT (and not Cirrus).

  <md:EntityDescriptor entityID="https://sso.example.org/idp" validUntil="2017-08-30T19:10:29Z"
    xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata"
    xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
    xmlns:mdrpi="urn:oasis:names:tc:SAML:metadata:rpi"
    xmlns:mdattr="urn:oasis:names:tc:SAML:metadata:attribute"
    xmlns:mdui="urn:oasis:names:tc:SAML:metadata:ui"
    xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
    <md:Extensions>
... removed to conserve space ...
</md:EntityDescriptor>

Example SAMLResponse token and what to check

Taken from SAML_2.0 - Web browser SSO profile ⧉ (Wikipedia).
In this example the <saml:NameID> of the <saml:Subject> is the Login attribute name so if Lookup user in Cirrus via (formerly Login Attribute type) is set to "user id" a user with user id "3f7b3dcf-1674-4ecd-92c8-1544f346baf8" must exist and be active for this login to be able to succeed. I.e. it's a pre-requisite but not sufficient as of course there are other checks. E.g. <saml:Conditions NotBefore="2004-12-05T09:17:05Z" NotOnOrAfter="2004-12-05T09:27:05Z">means Cirrus will no longer accept this token, since Dec 5th, 2004.

Example is not signed!

Normally to safeguard its integrity and authenticity a SAMLResponse token is signed with a XML Signature using a valid certificate (not shown).

<samlp:Response
    xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"
    xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
    ID="identifier_2"
    InResponseTo="identifier_1"
    Version="2.0"
    IssueInstant="2004-12-05T09:22:05Z"
    Destination="https://sp.example.com/SAML2/SSO/POST">
    <saml:Issuer>https://idp.example.org/SAML2</saml:Issuer>
    <samlp:Status>
      <samlp:StatusCode
        Value="urn:oasis:names:tc:SAML:2.0:status:Success"/>
    </samlp:Status>
    <saml:Assertion
      xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
      ID="identifier_3"
      Version="2.0"
      IssueInstant="2004-12-05T09:22:05Z">
      <saml:Issuer>https://idp.example.org/SAML2</saml:Issuer>
      <!-- a POSTed assertion MUST be signed -->
      <ds:Signature
        xmlns:ds="http://www.w3.org/2000/09/xmldsig#">...</ds:Signature>
      <saml:Subject>
        <saml:NameID
          Format="urn:oasis:names:tc:SAML:2.0:nameid-format:transient">
          3f7b3dcf-1674-4ecd-92c8-1544f346baf8
        </saml:NameID>
        <saml:SubjectConfirmation
          Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
          <saml:SubjectConfirmationData
            InResponseTo="identifier_1"
            Recipient="https://sp.example.com/SAML2/SSO/POST"
            NotOnOrAfter="2004-12-05T09:27:05Z"/>
        </saml:SubjectConfirmation>
      </saml:Subject>
      <saml:Conditions
        NotBefore="2004-12-05T09:17:05Z"
        NotOnOrAfter="2004-12-05T09:27:05Z">
        <saml:AudienceRestriction>
          <saml:Audience>https://sp.example.com/SAML2</saml:Audience>
        </saml:AudienceRestriction>
      </saml:Conditions>
      <saml:AuthnStatement
        AuthnInstant="2004-12-05T09:22:00Z"
        SessionIndex="identifier_3">
        <saml:AuthnContext>
          <saml:AuthnContextClassRef>
            urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport
         </saml:AuthnContextClassRef>
        </saml:AuthnContext>
      </saml:AuthnStatement>
    </saml:Assertion>
  </samlp:Response>

Was this article helpful?

What's Next

Two-Factor Authentication (2FA)

Table of contents

Key Benefits
Single Sign-On Modes
Step 1. Setup service provider (SP) [in Cirrus]
Step 2. Setup your Identity Provider (IdP) [at customer]
NOTES
TROUBLESHOOTING