Agent SSO

Overview

With Agent SSO, your agents sign in to Quiq through your company's identity provider (IdP), such as Okta or Microsoft Entra ID, instead of a Quiq username and password. You manage it in Admin > Security > Agent SSO.

Setup is shared between three people:

Supported identity providers

• Okta
• Auth0
• Microsoft Entra ID (formerly Azure Active Directory)
• OneLogin
• PingOne
• Oracle Cloud (OCI IAM)
• Duende IdentityServer, Apereo CAS and Google, set up through the Other (OpenID Connect) option

If your provider isn't listed, contact Quiq Support.

Sign-in through a CRM integration (Oracle Service Cloud, Salesforce or Zendesk) is set up separately and isn't covered here.

Before you start

Have these ready:

1. An application for Quiq in your IdP. The setup page shows the steps for your provider and the exact callback URL to register. Your IdP admin usually does this part.
2. From that application: the client ID, the client secret, and your IdP's domain or tenant details. For Entra ID that's the Directory (tenant) ID.
3. The client secret's expiry date, if your IdP sets one. Recording it means Quiq warns your admins before it runs out.
4. A test user in your IdP who can try signing in once you're done.
5. A decision on usernames. Each agent's Quiq username comes from one field your IdP sends, usually their email address. Agents whose current Quiq username matches that field keep their roles, queues and history. Anyone who doesn't match signs in as a new agent.

Plan a time with Quiq Support

Pick a time with Quiq Support when you'll have everything above ready and can finish setup straight away. Quiet hours are best.

Step 1: Quiq Support sets your identity provider

Ask Quiq Support to set your tenant's identity provider. Until they do, the Agent SSO page shows: "No identity provider has been set for this tenant yet."

Step 2: Fill in the setup guide

Go to Admin > Security > Agent SSO. The guide has four steps.

Provider

Your provider is already chosen. The page lists the steps for your IdP's admin console and shows the Callback URL to register. Select Copy and send the URL to your IdP admin if they haven't added it yet. It must match exactly.

What your IdP admin creates:

Connect

Tell Quiq where your IdP lives. For most providers you enter one value and Quiq works out the rest:

Then enter the Client ID and Client secret, and the secret's expiry date if you have it. The secret is stored encrypted and is never shown again.

Microsoft Entra ID: choose the identity source

Entra ID has one more choice, Identity source. It decides where Quiq reads each agent's details from, which decides which usernames you can use.

Agent identity

Quiq username comes from sets which field from your IdP becomes the agent's Quiq username. It has to match your agents' current Quiq usernames.

• Most providers: Email address is the safe choice.
• Auth0: choose Email address. Otherwise usernames come out as IDs like auth0|66f0....
• Entra ID with Microsoft Graph: User Principal Name is the usual choice. If agents used their on-premises account name before, choose Custom field… and enter onPremisesSamAccountName.
• Custom field… lets you name any other field your IdP sends, such as an employee ID.

Username capitalization: leave this on Leave it as the provider sends it unless your IdP sends mixed-case usernames and your Quiq usernames are all lower case (or all upper case). Changing it on a tenant that's already live changes which accounts agents sign in to.

Sign-out from the provider (optional): see Signing agents out from your IdP.

Roles from your IdP (optional): gives new agents Quiq roles based on their groups in your IdP.

• Each rule takes a group from your IdP, at least one permission level (Agent, Manager, Staff Admin or Admin), and optionally routing roles.
• Agents in several matching groups get every role those groups grant. Agents in no matching group get the Agent role.
• Roles apply only when an agent's Quiq account is first created, at their first sign-in. Agents who already exist keep the roles they have. Change those in Admin > Users.
• For OpenID Connect providers, enter the Groups claim name: the name of the field that lists the user's groups. It's usually groups for Okta and Entra ID and memberOf for PingOne. Auth0 uses a namespaced name, such as https://yourcompany.com/groups, that your Auth0 admin sets up. If the name is wrong, nobody gets roles from groups.
• For Entra ID with Microsoft Graph, no claim name is needed. Enter each group's object ID.

Review

Check the provider, client ID, username source and endpoints, then select Save configuration. If the guide shows a warning, go back and fix it before saving.

Step 3: Test

1. Open a private browser window and go to https://<your Quiq domain>/app/messaging.
2. You should be sent to your IdP. Sign in as your test user.
3. You should land in Quiq. In Admin > Users, check that the new agent's username looks right, for example an email address rather than a long ID.

If the username looks wrong, open Edit configuration, fix Quiq username comes from, save, and delete the user that was created by mistake.

After setup

The Agent SSO page shows an overview of your connection:

• Sign-in method: whether agents sign in through SSO or with Quiq passwords. Quiq Support changes this.
• Client secret: the recorded expiry date, and a warning when it's close or past.
• Edit configuration: reopens the setup guide. Your stored client secret stays in place unless you select Change client secret.
• Rotate secret: enter your new client secret when the old one is replaced or about to expire. Quiq uses the new secret as soon as you save it.

Client secret expiry

If you record an expiry date, Quiq reminds you before it runs out:

• The overview shows a warning from 30 days out.
• Admins see a popup when they open Admin, with a link to Agent SSO.
• Every admin on your tenant gets an email 30, 14, 7 and 1 days before it expires, and again once it has.

Signing agents out from your IdP

When this is on, signing out at your IdP also ends the agent's Quiq session. It uses a standard called OpenID Connect Back-Channel Logout: your IdP sends Quiq a signed sign-out message.

Microsoft Entra ID doesn't support this. It only offers browser-based (front-channel) sign-out, so the option is unavailable for Entra ID. For other providers, ask your IdP admin whether yours supports Back-Channel Logout. If it doesn't, leave this off. Sign-in works the same either way.

To set it up:

1. On the Agent identity step, turn on End the Quiq session when the provider ends theirs.
2. Copy the URL shown under the toggle. It looks like https://<your Quiq domain>/idp/backchannel-logout/<provider>.
3. Have your IdP admin paste it into the application's Back-Channel Logout URL setting.
4. Save the configuration.

For Other providers, the Signing keys (JWKS) URL and Issuer on the Connect step must be filled in. Quiq uses them to check the sign-out message really came from your IdP. The named providers fill them in for you.

To test it, sign in to Quiq as your test user, sign out at your IdP, then refresh the Quiq tab. You should be sent back to sign in.

Things to know:

• It only applies to sign-ins made after you turned it on.
• Quiq remembers each sign-in for this purpose for 10 hours. A sign-out at your IdP more than 10 hours after the agent signed in doesn't end their Quiq session.
• Turning it off doesn't sign anyone out.

Going back to Quiq passwords

Contact Quiq Support. They switch your tenant back to Quiq passwords. Your saved SSO configuration stays in place and does nothing until SSO is switched back on.

Agents who were created through SSO don't have a Quiq password. They'll need a password reset.

Troubleshooting