Skip to main content
This guide is for the Microsoft Entra ID administrator of your company. It shows how to connect Entra ID to one QX organization. The work has two parts: the IT team configures Entra ID, and the owner of the organization configures QX. The SSO login guide explains the rules that apply to every identity provider.

​
What QX offers

  • A person signs in to QX with the SSO login in Entra ID, through the OIDC protocol. QX never sees the password.
  • Entra ID creates, updates and deactivates the users of QX through user provisioning, with the SCIM 2.0 protocol. QX receives users only. The groups stay in Entra ID.
  • QX recognizes the person by the oid claim, the identifier of the person in the tenant.
  • By default, the role comes from QX: a new person signs in as an operator, and the owner changes the role in Users. If the company prefers, the owner group in Entra ID sets the role at each login.
  • QX does not link users by e-mail and does not create a user at the first login with Entra ID, because the Entra ID token does not confirm the e-mail.
  • The owner turns on required SSO for the whole organization. With the rule on, nobody in the organization signs in with a password, including the owner.
  • When the organization requires two-step verification, the SSO connection chooses where the person proves the second factor: in Entra ID or in the QX authenticator app.
  • A session that starts with the SSO login expires at the time that the owner chooses, from 1 to 8 hours after the login. It does not extend.
  • The owner removes the SSO connection to change the tenant or the app registration, and then configures a new one.
QX accepts an app registration of one tenant only. QX does not offer SAML.

​
The order of the work

Do the steps in this order:
  1. The IT team creates the app registration in Entra ID.
  2. The IT team adds the optional claims and the groups claim.
  3. The owner configures the SSO connection in QX.
  4. The IT team stores the QX login URL in the app.
  5. The owner issues the provisioning key.
  6. The IT team activates user provisioning in Entra ID.
  7. The owner does the login test.
  8. The owner enables SSO login.
  9. The owner turns on required SSO.
Before you start, check two things:
  • The Entra ID user of the owner has the same e-mail as the QX user of the owner.
  • When the owner group sets the role, the owner is in that group.

​
The QX addresses

The owner sees the addresses in Settings › SSO, in the box Addresses for the identity provider. Each address has a Copy button. The login URL shows only after the owner saves the SSO connection. The other two addresses are these:

​
1. Create the app registration in Entra ID

The names of the menus and fields in this step: not checked against an official source.
  1. In the Microsoft Entra admin center, open App registrations and click New registration.
  2. In Name, type QX.
  3. In Supported account types, select the option for one tenant only: Accounts in this organizational directory only.
  4. In Redirect URI, select the Web platform and paste the QX redirect URI.
  5. Click Register.
  6. On the Overview page, copy the Application (client) ID and the Directory (tenant) ID.
  7. In Certificates & secrets, create a client secret and copy its value.
Give the client ID, the client secret and the tenant ID to the owner through a safe channel, such as a password manager.

​
2. Add the optional claims and the groups claim

The Entra ID v2 ID token carries neither auth_time nor amr by default. Both are optional claims. The names of the menus in this step: not checked against an official source.
  1. In the app registration, open Token configuration.
  2. Click Add optional claim, select the ID token and select auth_time and email.
  3. For two-step verification Through Microsoft Entra ID, also select amr.
  4. Only when the owner group sets the role: click Add groups claim and keep the group ID as the value.
The auth_time claim is required. QX asks Entra ID for a new login in the login test, the identity confirmation and the setup of the authenticator app, with prompt=login and max_age=0. Without auth_time, the login test fails, the setup of the authenticator app fails, and the identity confirmation asks for the code of the QX authenticator app. Entra ID support for max_age: not checked against an official source. The email claim is also required. QX refuses a token without email. Entra ID sends email only when the person has an e-mail address in Entra ID. The groups claim carries the object ID of each group. So the owner group is the Object ID of the group. With the option Groups assigned to the application, the token carries only the groups assigned to the app, with no nested groups. Above 200 groups, the token replaces the groups with a reference to another address. When the owner group sets the role, QX refuses that login with the groups message. Use Groups assigned to the application to stay under this limit.

​
3. Configure the SSO connection in QX

The owner does these steps in QX:
  1. Open Settings › SSO and click Configure SSO connection.
  2. Select Microsoft Entra ID and click Continue.
  3. In Identity provider address, type https://login.microsoftonline.com/<tenant ID>/v2.0, with the Directory (tenant) ID of step 1. QX refuses common, organizations, consumers and the tenant of the personal Microsoft accounts (9188040d-6c67-4c5b-b112-36a304b66dad) in place of the tenant ID. QX stores the tenant ID in lower case. The address stays fixed after the owner saves the connection.
  4. In Client ID and Client secret, paste the values of step 1.
  5. In Client authentication, keep Basic (client_secret_basic). Entra ID also accepts Post (client_secret_post).
  6. In Role of the people, select Set in QX or Set by the owner group. With the second option, type in Owner group the Object ID of the group.
  7. In Two-step verification, select Through Microsoft Entra ID or Through the QX authenticator app. The section Two-step verification of this guide explains the options.
  8. In SSO session duration, select from 1 to 8 hours. The default is 8 hours.
  9. Click Save SSO connection. If the login of the owner is older than 15 minutes, QX asks for the password.
The form shows neither Link QX users by e-mail nor Create the user at the first login. After the save, the box Addresses for the identity provider shows the login URL. A change to the role of the people, the owner group or the two-step verification ends the sessions that started with SSO. Make the change outside working hours.

​
4. Store the login URL in Entra ID

The My Apps portal opens the app at the loginUrl of the service principal. Store the QX login URL in this value. The portal field that stores the loginUrl: not checked against an official source. Without this value, the person opens QX through the login URL, kept in the bookmarks of the browser.

​
5. Issue the provisioning key

The owner does these steps in QX:
  1. In Settings › SSO, click Manage provisioning keys.
  2. Click Issue provisioning key, then Issue key. If the login of the owner is older than 15 minutes, QX asks for the password.
  3. Copy the key. QX shows the key only once. The key starts with qxp_.
  4. Give the key to the IT team through a safe channel. Do not send the key by e-mail or by message.
  5. After the IT team pastes the key, check I pasted the key into the identity provider and click Back to the keys.

​
6. Activate user provisioning in Entra ID

The names of the menus in this step: not checked against an official source.
  1. Open the QX enterprise application, then Provisioning. Select the automatic provisioning.
  2. In Tenant URL, paste the user provisioning base URL, with no slash at the end.
  3. In Secret Token, paste the provisioning key.
  4. Click Test Connection. Entra ID looks for a user that does not exist, and QX answers with an empty list.
  5. Save the configuration.
  6. In the attribute mappings of the users, change the source of externalId: from mailNickname, the default, to objectId.
  7. Turn off the groups mapping. Entra ID lets you turn off this mapping only after the provisioning job exists. QX does not receive groups.
  8. Assign to the enterprise application the people who use QX.
  9. Turn on provisioning.
The externalId carries the objectId of the person. QX links the person to the login when the oid of the token equals the externalId. The objectId of the person has the same value as the oid (not checked against an official source). With the default mailNickname, the SSO login does not find the person.

​
7. Do the login test

  1. In Settings › SSO, the owner clicks Test login.
  2. QX opens Entra ID and asks for a new login. The owner signs in with their own user.
  3. QX shows “The login test passed. The SSO connection is verified.”
The test links the Entra ID user of the owner to the QX user of the owner. User provisioning does not need to link the owner first. The test needs three things:
  • The token carries auth_time. Without it, the test fails with “The identity provider did not send the time of the login (auth_time).”
  • When the owner group sets the role, the owner is in the owner group.
  • When the organization requires two-step verification through Entra ID, the owner signs in to Entra ID with the second factor.

​
8. Enable SSO login

  1. In Settings › SSO, the owner clicks Enable SSO login. If the login of the owner is older than 15 minutes, QX asks for the password.
  2. A person who is not an owner opens QX from the My Apps portal, or through the login URL, and checks the login.

​
9. Turn on required SSO

  1. In Settings › SSO, the owner clicks Turn on required SSO.
  2. The owner reads the warning and clicks Turn on required SSO again. If the login of the owner is older than 15 minutes, the warning asks for the password.
Each session that started with a password in the organization ends, including the session of the owner. From then on, each user of the organization signs in with the SSO login.

​
Two-step verification

The option of the SSO connection applies when the organization requires two-step verification. A change of the option ends the sessions that started with SSO.
  • Through Microsoft Entra ID: QX accepts the SSO login only when the optional amr claim confirms the second factor. The amr must hold mfa, or a possession method (otp, hwk, swk, sms, tel or sc) together with the password, a PIN or biometrics. Entra ID puts mfa in the amr only after a multi-factor authentication. Without the optional amr claim, QX refuses each login.
  • Through the QX authenticator app: after the login in Entra ID, the person types the code of the QX authenticator app. At the first login, the person sets up the app. The person has 15 minutes to finish. After that time, the person signs in again through Entra ID.
A person who signs in with SSO can also set up the authenticator app in Account security. Before the setup, QX asks for a new login in Entra ID, and the token must carry auth_time. To change the app, the person asks another owner or QX support for a reset of the second factor. When the SSO login is older than 15 minutes, a sensitive act asks for the identity confirmation. QX asks for a new login in Entra ID. When the token carries no auth_time, QX asks for the code of the authenticator app. The confirmation by code needs an app that the person already set up.

​
Session duration

The owner chooses the SSO session duration in Edit SSO connection, from 1 to 8 hours. After that time, the person signs in again through Entra ID. A shorter time also shortens the open sessions, counted from the login. A longer time applies to the next logins only. The identity confirmation does not change the time.

​
How QX treats each person

  • User provisioning creates the user of a new person. The Users screen shows “Waiting for SSO login”. The first SSO login activates the user. A new user is an operator.
  • When the person already has a QX user, user provisioning links that user by the e-mail, in the same organization. The user keeps the history.
  • QX recognizes the person by the oid. The Entra ID sub changes from one app to another, and a new app registration changes the sub of each person.
  • At each login, QX checks that the tid claim is the tenant of the identity provider address.
  • The token carries the e-mail with the email scope. Microsoft says that this value can change and has no verification. So QX does not link or create a user by e-mail with Entra ID.
  • When QX sets the role, the owner changes the role in Users, and the SSO login does not change the role.
  • When the owner group sets the role, the role changes at the next SSO login after a group change. A person in the group signs in as an owner, and the other people sign in as operators. The role is read-only in Users.
  • To deactivate a person, remove the person from the assignment of the app or disable the person in Entra ID. Entra ID sends active=false, and QX deactivates the user. All sessions of the user end at the same moment. After you remove the person from the assignment, Entra ID stops managing the user and never sends the deletion.
  • Entra ID sends the deletion of a person only after the hard delete, 30 days after the soft delete or when an administrator deletes the person permanently. QX turns off the access of the user and stops showing the user to user provisioning. The user and its history stay in QX.
  • To reactivate a person, assign the person to the app again. The user goes back to “Waiting for SSO login” and signs in again at the next SSO login.
  • The name and the e-mail of the person change only in Entra ID. The owner sees the user in QX, but does not change them.
  • A new e-mail in Entra ID does not block the SSO login. The user page shows the Entra ID e-mail when it differs from the e-mail in QX.

​
Replace the provisioning key

The SSO connection keeps up to 2 active keys. With two keys, Entra ID switches to the new key with no gap in user provisioning.
  1. The owner issues a new key, as in step 5. In a session that started with SSO, when the login is older than 15 minutes, QX asks for the identity confirmation.
  2. The IT team opens Provisioning in the enterprise application, pastes the new key into Secret Token, clicks Test Connection and saves.
  3. The owner checks the Last use column of the new key.
  4. The owner clicks Revoke on the old key, then Revoke key.

​
Replace the client secret

  1. In the app registration, the IT team creates a new client secret in Certificates & secrets (not checked against an official source).
  2. The owner opens Edit SSO connection, pastes the new secret into Client secret and clicks Save SSO connection.
A new client secret ends all sessions that started with SSO in the organization. Make the change outside working hours.

​
When Entra ID is down

With required SSO on, nobody signs in to QX while Entra ID is down. The open sessions continue until they expire.
  1. If an owner still has an open session, the owner clicks Turn off required SSO in Settings › SSO. QX asks for no confirmation, so this works while Entra ID is down.
  2. If no owner has an open session, ask QX support. Support turns off required SSO and writes the reason in the audit log.
  3. A person with no password clicks Forgot your password? on the login page and sets a password.
  4. When Entra ID is back, the owner clicks Turn on required SSO.
A user that user provisioning created, and that never signed in to QX, cannot sign in with a password. That user waits for Entra ID to come back.

​
Remove the SSO connection

To change the tenant or the app registration, the owner removes the SSO connection and configures a new one. The new connection has another login URL.
  1. In Settings › SSO, the owner clicks Remove connection. If the login of the owner is older than 15 minutes, QX asks for the password or for the identity confirmation.
  2. The owner reads the warning and clicks Remove connection again.
The removal has these effects:
  • The sessions that started with SSO end, including the session of the owner.
  • SSO login and required SSO stop. People sign in with a password.
  • QX deletes the external identities and the provisioning keys. Entra ID stops creating and deactivating users in QX. Turn off provisioning in the old enterprise application.
  • The users stay in QX. A person who only signed in with SSO creates a password with Forgot your password?, on the login page.
If no owner can sign in, ask QX support. Support removes the connection and writes the reason in the audit log.

​
Refusal messages

​
Sources