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

​
What QX offers

  • A person signs in to QX with the SSO login in OneLogin, through the OIDC protocol. QX never sees the password.
  • OneLogin 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 OneLogin.
  • 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 OneLogin sets the role at each login.
  • The owner can turn on the e-mail binding. With it, the first SSO login links the person to the QX user with the same 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 person types the code of the QX authenticator app after the login in OneLogin.
  • 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 OneLogin account or app, and then configures a new one.
QX does not ask OneLogin for a new login. When a sensitive act asks for the identity confirmation, QX asks for the code of the QX authenticator app.

​
The order of the work

Do the steps in this order:
  1. The IT team creates the OIDC app in OneLogin.
  2. The IT team assigns the app to the people and configures the groups.
  3. The owner configures the SSO connection in QX.
  4. The IT team pastes the QX login URL into the app.
  5. The owner issues the provisioning key.
  6. The IT team activates user provisioning in OneLogin.
  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 OneLogin 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 name SCIM Base URL comes from the OneLogin SCIM guide. The names of the other two fields follow the OneLogin admin portal (not checked against an official source). The login URL shows only after the owner saves the SSO connection. The other two addresses are these:

​
1. Create the OIDC app in OneLogin

The names of the tabs and the fields in this list follow the OneLogin admin portal (not checked against an official source).
  1. In the admin portal, add the app OpenId Connect (OIDC).
  2. In Display Name, type QX and save.
  3. In the Configuration tab, in Redirect URI’s, paste the QX redirect URI.
  4. Leave Login Url empty for now. Step 4 fills the field.
  5. In the SSO tab, under Token Endpoint, select the method Basic. It is the QX Basic (client_secret_basic). The method POST is the QX Post (client_secret_post).
  6. In the SSO tab, copy the client ID and the client secret.
The identity provider address is https://<subdomain>.onelogin.com/oidc/2, with the subdomain of the OneLogin account. Give the client ID and the client secret to the owner through a safe channel, such as a password manager.

​
2. Assign the app and configure the groups

  1. Assign the app to the people who use QX.
  2. Only when the owner group sets the role: configure the Groups parameter of the app so that it includes the owner group.
  3. Only when the owner will turn on the e-mail binding: make OneLogin send email_verified, as the OneLogin guide “Enabling the email_verified claim” explains.
When the owner group sets the role, QX asks for the groups scope at each login and reads the groups claim. When QX sets the role, QX does not ask for this scope. OneLogin fills the groups claim from the Groups parameter of the app. This parameter often comes from the OneLogin roles or from the AD member_of. The values are names. A person with no role gets no claim. OneLogin does not send email_verified when the administrator does not map this claim. Without it, QX links nobody by e-mail.

​
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 OneLogin and click Continue.
  3. In Identity provider address, type https://<subdomain>.onelogin.com/oidc/2. QX checks the format of the subdomain and stores the subdomain 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, select the same method as the app: Basic (client_secret_basic) or 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 name of the group exactly as OneLogin sends it at the login.
  7. Only with the owner group: check the line “With the owner group, QX also asks for the groups scope.”
  8. If QX users will sign in before user provisioning links each one, select Link QX users by e-mail. The option works only when QX sets the role, and it needs the email_verified of step 2.
  9. In Two-step verification, the only option is Through the QX authenticator app.
  10. In SSO session duration, select from 1 to 8 hours. The default is 8 hours.
  11. Click Save SSO connection. If the login of the owner is older than 15 minutes, QX asks for the password.
After the save, the box Addresses for the identity provider shows the login URL. QX compares the identity provider address with the iss of each token, character by character. Whether the iss of the OneLogin tokens equals the discovery issuer: not checked against an official source. The login test checks the match. A change to the role of the people, the owner group or the e-mail binding ends the sessions that started with SSO. Make the change outside working hours. A new client ID or a new Client authentication needs the SSO login disabled and asks for a new login test. The owner makes the change in this order:
  1. If required SSO is on, click Turn off required SSO.
  2. Click Disable SSO login. All sessions that started with SSO end, including the session of the owner. The owner signs in again with the password, or creates a password with Forgot your password?.
  3. Click Edit SSO connection, change the value and click Save SSO connection.
  4. Click Test login.
  5. Click Enable SSO login.
  6. If required SSO was on, click Turn on required SSO.

​
4. Paste the login URL into OneLogin

  1. Open the OIDC app in OneLogin, in the Configuration tab.
  2. In Login Url, paste the QX login URL.
  3. Save the app.
The OneLogin portal opens QX through this address, and QX starts the login.

​
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 OneLogin

The OneLogin SCIM guide uses a SCIM Provisioner with SAML app. Whether the OIDC app of step 1 also offers provisioning: not checked against an official source. With a separate provisioning app, assign to it the same people as the OIDC app. QX does not use the SAML fields of that app.
  1. In the Configuration tab of the provisioning app, in SCIM Base URL, paste the user provisioning base URL, with no slash at the end.
  2. In SCIM Bearer Token, paste the provisioning key. OneLogin sends the key in the Authorization: Bearer header.
  3. In SCIM JSON Template, send externalId with the value of the sub of the login, as the text below explains.
  4. Do not select Include in User Provisioning on the Groups parameter. QX does not receive groups.
  5. Click Save.
  6. Click Enable. OneLogin asks for a user that does not exist and expects an empty list or 404. Then API Status shows Enabled.
  7. Turn on the provisioning of the app in Enable provisioning.
QX recognizes the person by the sub of the login. The default OneLogin template offers externalId with $user.external_id, as an optional attribute, and offers $user.id, the OneLogin user ID. This line of the template sends the user ID:
Whether the sub of the OneLogin login equals $user.id: not checked against an official source. When the two values differ, the login test of the owner fails with “The identifier of the login does not match the identifier of user provisioning.” When externalId cannot carry the sub, leave externalId out of the template, as in the default template. Then the owner selects Link QX users by e-mail, and the IT team maps email_verified (step 2). User provisioning creates the user with no externalId, and the first SSO login completes the binding. The default template sends userName with {$parameters.scimusername}, which is usually the e-mail. QX needs an e-mail in userName or in emails. What QX does with the calls of OneLogin:
  • OneLogin updates the user with a PUT of the whole user. A PUT with no externalId keeps the value that QX stored.
  • To suspend the person, OneLogin sends active false in a PUT. QX deactivates the user.
  • For a person deleted in OneLogin, the administrator chooses Delete, Suspend or Do Nothing. With Delete, OneLogin sends DELETE.
  • OneLogin asks for responses in application/json. QX answers in this type when the Accept header asks only for application/json. In the other cases, QX answers in application/scim+json. Whether OneLogin accepts that type: not checked against an official source.

​
7. Do the login test

  1. In Settings › SSO, the owner clicks Test login.
  2. QX opens OneLogin. The owner signs in with their own user. OneLogin can use the session that is already open in it.
  3. QX shows “The login test passed. The SSO connection is verified.”
The test links the OneLogin user of the owner to the QX user of the owner. User provisioning does not need to link the owner first. The test needs two things:
  • When the owner group sets the role, the owner is in the owner group.
  • When user provisioning already created the owner, the externalId of the owner equals the sub of the login.

​
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 OneLogin portal and checks the login.
A person signs in to QX from the OneLogin portal. The QX page Sign in with SSO asks the person to open QX from the portal of the identity provider.

​
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

With OneLogin, the SSO connection offers only Through the QX authenticator app. The option applies when the organization requires two-step verification. After the login in OneLogin, 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 OneLogin. When the login of an SSO session is older than 15 minutes, a sensitive act asks for the identity confirmation. With OneLogin, the confirmation is always the code of the QX authenticator app. The confirmation by code needs an app that the person already set up. A person who signs in with SSO can also set up the authenticator app in Account security. Before the setup, QX asks for a login in OneLogin with the same identity. OneLogin can use the session that is already open in it. To change the app, the person asks another owner or QX support for a reset of the second factor.

​
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 OneLogin. 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.
  • 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.
  • QX does not create a user at the first login through OneLogin. A person with no QX user signs in after user provisioning creates the user.
  • To deactivate a person, suspend the person in OneLogin. User provisioning deactivates the user in QX. All sessions of the user end at the same moment.
  • When OneLogin sends active true for a deactivated user, the user goes back to “Waiting for SSO login” and signs in again at the next SSO login.
  • When OneLogin sends DELETE, QX turns off the access of the user and stops showing the user to user provisioning. The user and its history stay in QX. When OneLogin provisions the same person again, with the same externalId, QX brings back the same user.
  • The name and the e-mail of the person change only in OneLogin. The owner sees the user in QX, but does not change them.
  • A new e-mail in OneLogin does not block the SSO login. The user page shows the OneLogin 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, OneLogin 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 code of the QX authenticator app.
  2. The IT team pastes the new key into SCIM Bearer Token, in the provisioning app, 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 OneLogin, the IT team generates a new client secret in the SSO tab of the OIDC app (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 OneLogin is down

With required SSO on, nobody signs in to QX while OneLogin 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 OneLogin 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 OneLogin 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 OneLogin to come back.

​
Remove the SSO connection

To change the OneLogin account or app, 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. OneLogin stops creating and deactivating users in QX. Turn off provisioning in the old OneLogin app.
  • 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