Skip to main content

Single sign-on

Single sign-on (SSO) lets people sign in to the console with their work account. You connect Quilr to your SAML identity provider (IdP), such as Microsoft Entra ID, Okta or OneLogin.

Go toQuilrAI ConsoleSettingsOrganizationSingle sign-on

Before you start​

  • You need admin access to your IdP, so you can create a SAML application.
  • You need permission to manage organization settings in Quilr. Without it, the page opens but saving fails.
  • Make sure at least one admin can also sign in with Google or Microsoft. That admin can get everyone back in if SAML ever breaks.

How setup works​

Copy from Quilr
Entity ID
ACS URL
Create the IdP app
Paste the Quilr values
Send the user's email
Assign users
Paste into Quilr
IdP entity ID
IdP SSO URL
IdP signing certificate
Turn on and test
Save and turn on
Sign in from a private window ✓
QuilrAI

Step 1: Copy the Quilr values​

The Service provider details card on the Single sign-on page shows the values your IdP needs. Click Copy next to each one instead of typing it.

Quilr valueWhat your IdP may call it
Entity IDIdentifier, Audience URI, SP entity ID
ACS URLReply URL, Single sign-on URL, Assertion Consumer Service URL
Metadata URLMetadata URL. Same value as the Entity ID

The values look like this:

  • Entity ID: https://<your-tenant-url>/platformadminapis/v2/auth/saml/metadata/<tenant-id>
  • ACS URL: https://<your-tenant-url>/platformadminapis/v2/auth/saml/callback

<your-tenant-url> is your tenant's console address, and <tenant-id> is your Tenant ID from General settings. Always copy the exact values from the Service provider details card.

First-time setup

The Metadata URL only works after single sign-on is turned on. For your first setup, enter the Entity ID and ACS URL in your IdP by hand.

Step 2: Create a SAML app in your identity provider​

Pick your IdP. Each tab ends with the values you bring back to Quilr in Step 3.

  1. In the Microsoft Entra admin center, go to Enterprise applications and click New application.
  2. Click Create your own application, name it (for example, "Quilr"), and choose the non-gallery option.
  3. Open Single sign-on and select SAML.
  4. Under Basic SAML Configuration, set:
    • Identifier (Entity ID) to the Quilr Entity ID.
    • Reply URL to the Quilr ACS URL.
  5. Under Attributes & Claims, check that the email address claim maps to the user's email (user.mail). If some users have no mail value, set Unique User Identifier (Name ID) to their email instead.
  6. Under SAML Certificates, download Certificate (Base64).
  7. Under Users and groups, assign the people or groups who should sign in.

Bring these values back to Quilr:

Entra valueQuilr field
Microsoft Entra IdentifierIdP entity ID
Login URLIdP SSO URL
Certificate (Base64) file contentsIdP signing certificate

Microsoft's guide: Enable SAML single sign-on for an enterprise application.

Step 3: Enter your IdP details in Quilr​

Go back to the Identity provider card on the Single sign-on page and fill in:

FieldWhat to enter
IdP entity IDThe issuer your IdP shows for the app
IdP SSO URLWhere sign-in requests are sent. Must start with https://
IdP SLO URLOptional. You can leave it empty
IdP signing certificateThe full X.509 certificate, as PEM or base64. The -----BEGIN CERTIFICATE----- lines are optional

Leave Enforce single sign-on set to Not enforced for now. You can enforce it after your first test passes.

Step 4: Save and turn on​

  1. Click Save and turn on. The button stays greyed out until the required fields are filled in correctly.
  2. You see Single sign-on saved, and the SAML single sign-on switch shows On.

People can now sign in with SAML or with any Google or Microsoft option they already use. Stay signed in to your current session until you finish testing.

Step 5: Test sign-in​

  1. Open a private or incognito browser window and go to the console sign-in page.
  2. Click Continue with single sign-on.
  3. Enter your Work email and click Continue with SSO.
  4. Sign in at your IdP.

You land back in the console, signed in. People can also sign in from the Quilr tile in their IdP's app dashboard.

If sign-in fails, see Troubleshooting.

Enforce single sign-on​

When single sign-on is enforced, Google and Microsoft sign-ins are sent to your IdP instead. Use this when everyone must sign in through your IdP.

  1. Set Enforce single sign-on to Enforced.
  2. Click Save.
warning

While enforced, Google and Microsoft sign-ins also go through SAML. If SAML breaks, admins can't use them to get back in. Test sign-in before you enforce.

Who can sign in​

  • Your IdP decides who can authenticate. Only people assigned to the app in your IdP can sign in.
  • Quilr matches people by email. The email your IdP sends must match the person's email in Quilr.
  • Roles decide what people see. SSO only signs people in. Their role in Roles and permissions sets their access. When you add a user there, choose SAML SSO as their sign-in method.
  • People without a console role go to Self Service. They sign in, but land in Self Service instead of the console.

SAML sign-ins show in Audit logs as Signed in with SAML. Changes to this page are recorded there too.

Rotate the signing certificate​

Quilr holds one IdP signing certificate at a time. When your IdP switches to a new certificate:

  1. In your IdP, create the new certificate without activating it, if your IdP allows that.
  2. Activate it in your IdP. Straight away, paste it into IdP signing certificate in Quilr and click Save.
  3. Test sign-in from a private window.

Sign-ins fail until both sides use the same certificate, so do step 2 in one go.

Turn off single sign-on​

  1. Set the SAML single sign-on switch to Off.
  2. In Turn off single sign-on?, click Turn off.

SAML sign-in stops, but people can still use any Google or Microsoft option with their existing account. Your IdP details are kept. To turn SAML back on, set the switch to On. It saves straight away.

Troubleshooting​

ProblemPossible reasonFix
Save and turn on is greyed outA required field is empty, or a URL doesn't start with https://Fill in IdP entity ID, IdP SSO URL and IdP signing certificate. Check the fields marked Required or Must be an https URL
Saving shows idpSigningCert is not a valid X.509 certificateThe pasted text isn't the certificate, or part of it is missingCopy the full certificate again from your IdP (for Entra, Certificate (Base64))
The sign-in page says Single sign-on isn't available for your accountSAML is off, or your email domain isn't linked to your organizationCheck that the SAML single sign-on switch is On. If it is, contact your QuilrAI representative
The sign-in page says We couldn't complete sign-in with your identity providerQuilr rejected the IdP's response. See the list belowCheck each value against the Single sign-on page, then test again
Your IdP says the user isn't assigned to the appThe person isn't assigned in your IdPAssign them, or a group they belong to, to the app
The Metadata URL shows an errorSingle sign-on isn't turned on yetEnter the Entity ID and ACS URL by hand, or import the metadata after you turn SSO on
Someone lands in Self Service instead of the consoleThey have no console roleGive them a role in Roles and permissions

Why "We couldn't complete sign-in" appears. Check these in order:

  1. The certificate in Quilr doesn't match the one your IdP signs with. This often happens after the IdP rotates it.
  2. IdP entity ID in Quilr doesn't exactly match your IdP's issuer.
  3. The audience or reply URL in your IdP doesn't exactly match the Quilr Entity ID or ACS URL.
  4. Your IdP signs with SHA-1. Switch it to SHA-256.
  5. The response doesn't include the user's email.
  6. Your IdP's clock is more than 2 minutes off.

If SAML sign-in breaks​

  1. Sign in with Google or Microsoft as an admin.
  2. Fix the values on the Single sign-on page, or turn SAML off while you fix your IdP.
  3. Test from a private window, then turn SAML back on.

If single sign-on is enforced, Google and Microsoft sign-ins also go to your IdP, so step 1 won't work. If no admin can sign in, contact your QuilrAI representative.