License Portal
Setting Up Single Sign-On and Provisioning with Your Identity Provider
Connect an OIDC and SCIM-compatible identity provider to AQT for sign-in and provisioning.
This article is intended for workspace Admins who are setting up single sign-on and SCIM provisioning for their organization. If you are looking to activate AQT on your own computer, please see Activating or Deactivating AQT instead.
This guide connects any identity provider that supports OIDC and SCIM 2.0 to the AQT License Portal. Once it is complete, your users will sign in to the portal and to AQT One with their directory account, and their license and role will be determined by their directory group membership.
If you use Okta or Microsoft Entra ID, please follow the guide for your provider instead, as those guides name every screen and cover the details specific to each platform: [Setting Up Single Sign-On and Provisioning with Okta] and [Setting Up Single Sign-On and Provisioning with Microsoft Entra ID]. This guide covers what AQT needs from any provider and leaves you to find the equivalent screens in your own.
There are two halves to the setup. OIDC handles sign-in, and SCIM handles provisioning, which means creating, updating and deactivating accounts, and pushing groups so that they can be mapped to licenses. Steps 1 to 3 cover sign-in. Steps 4 onwards cover provisioning and are only needed if you want it.
Note: Some providers will not do both jobs from a single application. Okta and Entra both need two applications, for different reasons. If your provider offers no SCIM or provisioning settings on the application you registered for sign-in, this is usually why, and creating a second application is the answer.
Before You Begin
To follow this guide, you will need:
Administrator access to your identity provider, with enough permission to register an application and configure provisioning.
A workspace in the License Portal where you are an Admin, with SSO enabled. If OIDC (OpenID Connect) is not listed under Settings > Authentication methods, please contact support.
A domain you can prove you own. Domain verification is step 1 and is not optional, because no sign-in or provisioning is matched to your workspace until a domain has been verified.
Available license seats. Provisioning does not purchase seats, so if there is no free seat, a user is still provisioned but will wait until one becomes available.
Everything on the AQT side of the setup is found under Settings > Authentication methods > OIDC (OpenID Connect).
Step 1: Verify Your Email Domain
In the portal, go to OIDC > 1. Verify a domain > Add domain and enter a domain that your users’ email addresses end in. The domain will be listed as Pending verification, along with the DNS record you need to publish:
Name: _aqt-verify.<your-domain>
Value: the token shown against that domain
Add this as a TXT record with your DNS provider. Most DNS providers only want the prefix, _aqt-verify, and will append the domain themselves.
Once the record has propagated, click Check DNS against the domain. The badge will change to Verified when it passes.
You can verify several domains and attach them all to the same identity provider. Make sure you verify the domains your directory accounts actually use, because a user whose email address falls outside a verified domain will not be matched to your workspace.
Please note that a verified domain cannot be removed while an identity provider is attached to it.
Step 2: Register AQT with Your Identity Provider
Register a confidential web application that uses the authorization code flow. AQT always sends a PKCE challenge (S256), so leave PKCE enabled or optional. No scopes are needed beyond openid, profile and email.
The application needs both of the following redirect URIs, which some providers call reply URLs or callback URLs:
Portal sign-in: https://license.querytool.com/api/auth/oidc/callback
AQT One activation: https://activation.querytool.com/api/auth/oidc/callback
Note: Be sure to add both URIs. The desktop client authenticates against the activation server rather than the portal, so the second URI is what allows users to sign in from AQT One itself. If you register only the first, portal sign-in will work but AQT One activation will not.
Both URIs are also shown in the portal under 2. Configure an identity provider > Redirect URIs, where you can copy them.
Before moving on, collect three things from your provider:
The client ID.
The client secret. Many providers only show a secret once, so copy it now.
The issuer, which is the base URL that the provider’s discovery document sits under. If your provider publishes a URL ending in /.well-known/openid-configuration, the issuer is everything before that.
Step 3: Add the Identity Provider (Portal)
Go to OIDC > 2. Configure an identity provider > Add provider and fill in the following:
Verified domain: the verified domain, or domains, that this provider should cover.
Display name: the name that should appear on the sign-in button.
Authority URL: the issuer from step 2.
Client ID and Client Secret: the values from step 2.
Fallback license group: set this to None if you are using SCIM.
Allow Just-In-Time Provisioning: turn this off if you are using SCIM.
Click Test connection, and once the test passes, create the provider.
Note: The Authority URL must match your provider’s issuer exactly. AQT fetches <authority>/.well-known/openid-configuration and compares the issuer value inside it against what you entered. A missing path segment, or a tenant-specific issuer entered in its generic form, will fail with “Identity provider issuer mismatch”. The error message shows both strings so that you can compare them. A trailing slash is fine, as it is trimmed before the comparison.
You will notice there is no redirect URI field. AQT derives its callback URLs from its own base URLs, which is why the URIs registered in step 2 must match exactly.
Using SSO for sign-in only, without SCIM? Turn Allow Just-In-Time Provisioning on and set Fallback license group to the license that new users should receive. If JIT is off and SCIM is not configured, anyone without an existing account will be refused at sign-in and told to ask an administrator for an invitation. Only leave JIT off if you intend to invite every user by hand; in that case, their account is linked to their directory identity the first time they sign in with SSO.
Sign-in is now set up. The remaining steps add provisioning.
Step 4: Generate a SCIM Token (Portal)
Go to Settings > SCIM Provisioning > Generate Token, select the identity provider you created in step 3, and give the token a name.
Note: The token is shown once and cannot be retrieved afterwards. To rotate it, generate the replacement before revoking the old one, as both can be live at the same time.
The same panel shows the SCIM endpoint:
https://license.querytool.com/scim/v2
The SCIM section only appears once an OIDC identity provider has been enabled in step 3.
Step 5: Point Your Provider at the SCIM Endpoint
In your provider’s provisioning settings, supply the following:
Endpoint, which some providers call the tenant URL, base URL or connector base URL: https://license.querytool.com/scim/v2
Authentication: an HTTP header bearer token, using the token from step 4.
AQT expects the token to arrive as Authorization: Bearer <token>. Most providers add the Bearer prefix themselves and want the token on its own, so check which yours does before pasting. If the prefix is added twice, the result is Bearer Bearer … and a 401 error. Whitespace around the token is trimmed and is harmless.
Enable whatever your provider calls creating users, updating users, deactivating users and pushing groups. Group push is often a separate setting from user provisioning, and the group mapping in step 7 depends on it.
Note: Some providers leave the write actions off by default and do not include them in their connection test. A passing test proves that the endpoint and token are correct, and nothing more.
Attributes
Your provider’s default attribute mappings will generally work as shipped. Two attributes carry the meaning that AQT acts on:
emails supplies the address AQT uses to identify the person, preferring the primary entry and then a work entry. If your provider sends no emails value, userName is used instead, and it must then be an email address. An address that is not on a verified domain is declined.
active controls whether the person has access.
name.givenName, name.familyName and displayName are used if they are sent. Everything else is accepted and ignored.
Note: A roles attribute on a user is ignored, as roles come from group mappings. This is deliberate: an absent attribute is indistinguishable from an instruction to remove something, so a user who dropped out of a role attribute for any reason would be quietly demoted. A group that stops matching does nothing until you decide what it should do.
Step 6: Push Your Groups
Push the groups that should mean something in AQT, which is usually one per license tier plus one for administrators. There is no need to push your whole directory, as extra groups are harmless but add noise.
Pushing a group is not the same as putting its members in scope. Most providers treat these as separate settings, and you need both: scope decides whose accounts are sent, while group push sends the group object itself.
A pushed group grants nothing until it is mapped, so you can safely push groups and review them before applying any entitlement.
Step 7: Map Groups to Licenses and Roles (Portal)
Go to Settings > SCIM Provisioning > Map your groups. The groups you pushed will appear as unmapped, along with their member counts:
Select a group to open the mapping dialog, then choose:
Directory group: the group pushed from your directory.
License group: the license its members should receive. This is optional.
Role: User or Administrator.
A mapping is applied on save to everyone already in the group, so no re-push is needed. Repeat this until every group you care about is mapped:
The list is ordered by precedence, and a few rules apply:
A user who is in more than one mapped group takes the license group of the highest mapping in the list. You can reorder the list with the arrows.
A new mapping is added at the bottom of the list, so move it up if it should outrank an existing one.
Each directory group gets a single mapping.
The license group is optional. To give administrators a role without consuming a seat, map their group to Administrator with no license group.
You can map a group before it exists here by naming it, and the mapping binds the moment a group of that name arrives. A group matched this way can only grant the User role, because display names are not unique and a name match is not a reliable enough identity to grant administrator rights.
No group can grant Ownership, and the Owner role is not offered when creating a mapping.
Step 8: Verify
The Last synced panel under the SCIM section reports the current state of provisioning:
No requests received yet means your provider has not reached AQT. Check the endpoint and token. Some providers also run on a fixed cycle and may simply not have run yet.
N users are waiting for a license seat means provisioning is working and you are out of seats. Please see [How SCIM Provisioning Behaves in AQT] for what happens next.
Recently declined or ignored lists requests that arrived but changed nothing. Each entry is labelled: Unknown member means a pushed group names someone who has not been provisioned, usually because they are not in scope; Not attached means the address is on a domain you have not verified; and Role ignored means a role attribute arrived and was discarded.
N users couldn’t be given a license means a mapping points at a license group that no longer exists, and the mapping needs to be repaired.
A green tick with a timestamp means provisioning is healthy, and the timestamp shows when your provider last reached AQT.
AQT returns the reason for any declined request in the response body, so its error text will generally appear verbatim in your provider’s own provisioning log.
For details on what provisioning will and will not change, what happens when seats run out, and how deactivation and removal behave, please see How SCIM Provisioning Behaves in AQT.