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.
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
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.
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.
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.
- Microsoft Entra ID
- Okta
- OneLogin
- Other SAML 2.0 IdP
- In the Microsoft Entra admin center, go to Enterprise applications and click New application.
- Click Create your own application, name it (for example, "Quilr"), and choose the non-gallery option.
- Open Single sign-on and select SAML.
- Under Basic SAML Configuration, set:
- Identifier (Entity ID) to the Quilr Entity ID.
- Reply URL to the Quilr ACS URL.
- Under Attributes & Claims, check that the email address claim maps to the user's email (
user.mail). If some users have nomailvalue, set Unique User Identifier (Name ID) to their email instead. - Under SAML Certificates, download Certificate (Base64).
- Under Users and groups, assign the people or groups who should sign in.
Bring these values back to Quilr:
Microsoft's guide: Enable SAML single sign-on for an enterprise application.
-
In the Okta Admin Console, go to Applications › Applications and click Create App Integration.
-
Select SAML 2.0, click Next, name the app (for example, "Quilr"), and click Next.
-
On Configure SAML, set:
-
Keep Okta's default signing settings: response and assertion signed with RSA-SHA256, and assertions unencrypted.
-
Click Next, then Finish.
-
On the Assignments tab, assign the people or groups who should sign in.
Bring these values back to Quilr. On the Sign On tab, click View SAML setup instructions:
Okta's guide: Create SAML app integrations.
-
In the OneLogin admin portal, go to Applications and click Add App.
-
Search for SAML Custom Connector (Advanced), select it, name it (for example, "Quilr"), and click Save.
-
On the Configuration tab, set:
-
Set SAML nameID format to Email and SAML signature element to Both.
-
On the Parameters tab, make sure NameID sends the user's email.
-
On the SSO tab, set SAML Signature Algorithm to SHA-256.
-
On the Access tab, assign the users or roles who should sign in.
Bring these values back to Quilr. They are on the SSO tab:
Any SAML 2.0 identity provider works if its app meets these requirements:
- ACS URL and audience match exactly. Send responses to the Quilr ACS URL, with the Quilr Entity ID as the audience.
- The user's email is included. Send it as the Name ID in email address format, or in an
email,mailoremailaddressattribute. - Responses are signed. Sign the response, the assertion, or both, with RSA-SHA256, RSA-SHA384, RSA-SHA512 or ECDSA-SHA256. SHA-1 signatures are rejected.
- Clocks are in sync. Quilr allows up to 2 minutes of clock difference.
Bring these values back to Quilr: the IdP's issuer (entity ID), its SAML sign-in URL, and its X.509 signing certificate.
Step 3: Enter your IdP details in Quilr
Go back to the Identity provider card on the Single sign-on page and fill in:
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
- Click Save and turn on. The button stays greyed out until the required fields are filled in correctly.
- 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
- Open a private or incognito browser window and go to the console sign-in page.
- Click Continue with single sign-on.
- Enter your Work email and click Continue with SSO.
- 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.
- Set Enforce single sign-on to Enforced.
- Click Save.
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:
- In your IdP, create the new certificate without activating it, if your IdP allows that.
- Activate it in your IdP. Straight away, paste it into IdP signing certificate in Quilr and click Save.
- 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
- Set the SAML single sign-on switch to Off.
- 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
Why "We couldn't complete sign-in" appears. Check these in order:
- The certificate in Quilr doesn't match the one your IdP signs with. This often happens after the IdP rotates it.
- IdP entity ID in Quilr doesn't exactly match your IdP's issuer.
- The audience or reply URL in your IdP doesn't exactly match the Quilr Entity ID or ACS URL.
- Your IdP signs with SHA-1. Switch it to SHA-256.
- The response doesn't include the user's email.
- Your IdP's clock is more than 2 minutes off.
If SAML sign-in breaks
- Sign in with Google or Microsoft as an admin.
- Fix the values on the Single sign-on page, or turn SAML off while you fix your IdP.
- 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.
Related
- Roles and permissions - decide what people can see after they sign in
- General - your organization's domains
- Smart Groups - assign roles to groups instead of individuals
- Audit logs - review sign-ins and SSO changes