Overview
QR Dex supports SAML-based single sign-on (SSO) so your team members can log in with their existing Okta credentials. Once configured, users assigned to the QR Dex application in Okta will be able to authenticate without creating a separate password. This guide walks you through the complete setup process.
Prerequisites
Before you begin, make sure you have the following in place:
- QR Dex Enterprise plan -- SSO is available exclusively on the Enterprise tier. Visit the pricing page to upgrade if you are on a different plan.
- Okta admin access -- You need administrator privileges in your Okta organization to create and configure applications.
- QR Dex team owner role -- Only team owners can enable and configure SSO in QR Dex.
Step 1: Create a SAML Application in Okta
Log in to the Okta Admin Console and navigate to Applications → Applications. Click Create App Integration, select SAML 2.0 as the sign-in method, and click Next. Give the application a name such as "QR Dex" and optionally upload the QR Dex logo for easy identification.
Step 2: Configure SAML Settings in Okta
On the SAML configuration screen, enter the following values:
- Single Sign-On URL -- Set this to your QR Dex SAML callback URL. You can find this value in the QR Dex SSO settings page.
- Audience URI (SP Entity ID) -- Set this to the Entity ID also found on the QR Dex SSO settings page.
- Name ID format -- Select EmailAddress.
- Application username -- Choose Email.
Leave the remaining fields at their defaults unless your organization requires custom attribute mappings. Click Next, complete the feedback step, and click Finish.
Step 3: Collect Okta Configuration Details
After creating the application, navigate to the Sign On tab. You will need three pieces of information from this page:
- SSO URL -- The Identity Provider Single Sign-On URL.
- Entity ID -- The Identity Provider Issuer value.
- Certificate -- Download the X.509 signing certificate.
Step 4: Configure SSO in QR Dex
In QR Dex, go to the SSO settings page. Enter the three values you collected from Okta:
- Paste the SSO URL into the Identity Provider SSO URL field.
- Paste the Entity ID into the Identity Provider Entity ID field.
- Upload or paste the contents of the X.509 certificate you downloaded.
Click Save to store your configuration.
Step 5: Test the Connection
After saving, click Test SSO Connection on the SSO settings page. QR Dex will attempt a SAML authentication flow with Okta and report whether it succeeded. If the test passes, assign users to the QR Dex application in Okta so they can begin logging in via SSO.
Dedicated Setup Reference
For a detailed configuration walkthrough with screenshots and advanced options, visit the dedicated Okta SSO setup page.
Troubleshooting
- Login loop or redirect error -- Double-check that the Single Sign-On URL and Audience URI in Okta exactly match the values shown in QR Dex. Trailing slashes or protocol mismatches (http vs https) are a common cause.
- Certificate error -- Make sure you uploaded the correct X.509 certificate from Okta. If Okta has rotated its certificate, download the new one and update it in QR Dex.
- User not provisioned -- Confirm the user is assigned to the QR Dex application in Okta and that their email address matches an existing QR Dex account or that auto-provisioning is enabled.
- SSO option not visible -- Verify that your team is on the Enterprise plan. SSO settings are available on the Plus, Pro, and Enterprise plans.