License Portal

Setting Up Single Sign-On and Provisioning with Okta

Table of Content

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 your Okta org to the AQT License Portal. Once it is complete, your users will sign in to the portal and to AQT One with their Okta account, and their license and role will be determined by their Okta group membership.

The setup involves creating two apps in Okta. The first is an OIDC Web Application, which handles sign-in. The second is a SAML 2.0 or SWA app with SCIM 2.0 enabled, which handles provisioning: creating, updating and deactivating accounts, and pushing groups so that they can be mapped to licenses. Two apps are needed because Okta does not offer SCIM provisioning on an OIDC app.

Steps 1 to 3 cover sign-in. Steps 4 onwards cover provisioning and are only needed if you want it.

Note: Okta treats the two apps as unrelated, so assigning a user to one does not assign them to the other. AQT matches a user’s sign-in to their provisioned account by their email address on your verified domain, so be sure to assign the same users and groups to both apps.

Before You Begin

To follow this guide, you will need:

  • In Okta, permission to create app integrations and push groups.

  • 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 Okta logins 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: Create the Sign-In App (Okta)

Create an OIDC - OpenID Connect app integration of type Web Application, with the grant type set to Authorization Code, and assign it to whoever should be able to sign in.

The app needs both of the following sign-in redirect URIs:

  • 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.

Both URIs are also shown in the portal under 2. Configure an identity provider > Redirect URIs, where you can copy them.

Back in Okta, the Client ID and Client secret can be found on the app’s General tab, under Client Credentials:

The issuer URI is under Security > API > Authorization Servers. Copy the Issuer URI for the authorization server you use. It takes one of two forms:

  • https://<your-org>.okta.com/oauth2/default, if your org has a custom authorization server.

  • https://<your-org>.okta.com, if it does not. The default server only exists on orgs with API Access Management or on a free Integrator org, and the org authorization server works just as well here.

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, such as Corporate Okta.

  • Authority URL: your Okta issuer URI.

  • 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 issuer exactly. AQT fetches <authority>/.well-known/openid-configuration and compares the issuer value inside it against what you entered. Either form of the issuer works, but entering one when your discovery document reports the other 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: Create the Provisioning App (Okta)

Create a second app integration. Okta accepts either SAML 2.0 or SWA - Secure Web Authentication here, and either will work, because nothing on the app’s first page affects AQT.

On the app’s General tab, click Edit on App Settings, set Provisioning to SCIM, and save. The Provisioning tab will appear once this is saved.

Step 5: 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 6: Configure Provisioning (Okta)

Under Provisioning > Settings > Integration, set the following:

  • SCIM connector base URL: https://license.querytool.com/scim/v2

  • Unique identifier field for users: userName

  • Supported provisioning actions: tick Push New Users, Push Profile Updates and Push Groups

  • Authentication Mode: HTTP Header

  • Authorization: the token from step 5

Note: Paste the token on its own, without a Bearer prefix, as Okta adds the prefix itself. Including it produces Bearer Bearer … , which matches no token and results in a 401 error. Whitespace around the token is trimmed and is harmless.

Then, under Provisioning > To App, enable Create Users, Update User Attributes and Deactivate Users. Leave Sync Password off, as AQT holds no passwords for SSO users.

Note: All three of these actions are off by default and are not covered by the connector test. With all three off, Okta pushes nothing.

Attribute Mappings

Okta’s default attribute mappings work as shipped. Two attributes carry the meaning that AQT acts on:

• emails supplies the address AQT uses to identify the person. Okta populates it by default.

• active controls whether the person has access.

givenName, familyName and displayName are used if they are sent. Everything else is accepted and ignored.

Note: Check which address AQT will use. It takes the primary entry from emails , then a work entry, and only falls back to userName when no address is sent at all. If that address is not on a domain you have verified, the user is declined. If your Okta logins are not email addresses and no emails value is mapped, set Application username format to Email on the app’s Sign On tab.

Step 7: Assign and Push Your Groups (Okta)

Assignments puts users in scope, and nothing is pushed for a user who is not assigned. You can assign people individually or by group:

Assign the same users to the sign-in app from step 2, otherwise they will be provisioned without being able to sign in.

Push Groups sends the groups themselves. Use Find groups by name, leave the push action as Create Group, and save. The Push Status will change to Active on success:

Note: Assigning a group puts its members in scope, while pushing a group sends the group itself, which is what AQT maps to licenses and roles. Both are required.

If AQT already holds a group of that name, choose Link Group instead of Create Group, refreshing app groups first if it is not listed. This also resolves a push that fails because the group already exists.

A pushed group grants nothing until it is mapped, so you can safely push groups and review them before applying any entitlement.

Step 8: Map Groups to Licenses and Roles (Portal)

Go to Settings > SCIM Provisioning > Map your groups. The groups you pushed in step 7 will appear as unmapped, along with their member counts:

Select a group to open the mapping dialog, then choose:

  • Directory group: the group you pushed from Okta.

  • 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.

  • No group can grant Ownership, and the Owner role is not offered when creating a mapping.

  • A group matched by name, rather than by a pushed group, 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.

Step 9: Verify

The Last synced panel under the SCIM section reports the current state of provisioning:

  • No requests received yet means Okta has not reached AQT. Check the base URL and token.

  • N users are waiting for a license seat means provisioning is working and you are out of seats. These users can sign in but cannot activate AQT One. Once you free or buy a seat, they are assigned automatically.

  • 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 Okta last reached AQT.

In Okta, Reports > System Log records provisioning events and their failure messages, and Dashboard > Tasks collects failed provisioning jobs. Where Okta’s own message is not enough, the Last synced panel in the portal says what AQT did with the request.

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].