Overview
QR Dex supports SAML-based single sign-on (SSO) with Microsoft Entra ID, formerly known as Azure Active Directory. Once configured, your team members can authenticate using their existing Microsoft credentials, eliminating the need for separate QR Dex passwords. This guide covers the full setup process from start to finish.
Prerequisites
Before you begin, confirm that you have the following:
- QR Dex Enterprise plan -- SSO is available exclusively on the Enterprise tier. Visit the pricing page to upgrade if needed.
- Microsoft Entra ID admin access -- You need at least the Cloud Application Administrator role in your Microsoft Entra tenant to register and configure enterprise applications.
- QR Dex team owner role -- Only team owners can enable and configure SSO in QR Dex.
Step 1: Register an Enterprise Application
Sign in to the Microsoft Entra admin center at entra.microsoft.com. Navigate to Identity → Applications → Enterprise applications and click New application. Select Create your own application, give it a name such as "QR Dex", choose Integrate any other application you don't find in the gallery (Non-gallery), and click Create.
Step 2: Configure SAML Single Sign-On
In your new enterprise application, navigate to Single sign-on in the left sidebar and select SAML as the method. In the Basic SAML Configuration section, enter the following values:
- Identifier (Entity ID) -- Set this to the Entity ID shown on the QR Dex SSO settings page.
- Reply URL (Assertion Consumer Service URL) -- Set this to your QR Dex SAML callback URL, also found on the QR Dex SSO settings page.
Under User Attributes & Claims, verify that the Unique User Identifier (Name ID) is set to user.userprincipalname or user.mail, depending on which email format your organization uses. Save your changes.
Step 3: Download the Certificate and Collect URLs
Scroll down to the SAML Signing Certificate section and download the Certificate (Base64) file. Then, in the Set up QR Dex section, copy the following values:
- Login URL -- The Identity Provider SSO URL.
- Microsoft Entra Identifier -- The Identity Provider Entity ID.
Alternatively, you can download the Federation Metadata XML file, which contains all the required values in a single document.
Step 4: Configure SSO in QR Dex
In QR Dex, go to the SSO settings page. Enter the values you collected from Microsoft Entra ID:
- Paste the Login URL into the Identity Provider SSO URL field.
- Paste the Microsoft Entra Identifier into the Identity Provider Entity ID field.
- Upload or paste the contents of the Base64 certificate you downloaded.
Click Save to store your configuration.
Step 5: Assign Users and Test
Back in the Microsoft Entra admin center, go to Users and groups for the QR Dex application and assign the users or groups that should have access. Then return to QR Dex and click Test SSO Connection on the SSO settings page. QR Dex will initiate a SAML authentication flow and report whether the connection was successful.
Dedicated Setup Reference
For a detailed walkthrough with screenshots and advanced configuration options, visit the dedicated Microsoft Entra ID SSO setup page.
Troubleshooting
- AADSTS error codes -- If you see an error code starting with "AADSTS", look it up in the Microsoft error code reference. Common causes include mismatched Reply URLs or expired certificates.
- Reply URL mismatch -- Ensure the Reply URL configured in Microsoft Entra ID exactly matches the SAML callback URL shown in QR Dex. Even a trailing slash difference will cause authentication to fail.
- Certificate issues -- Download a fresh copy of the Base64 certificate from Microsoft Entra ID if your current one has expired or was rotated. Update the certificate in QR Dex and save.
- User not assigned -- Verify that the user attempting to log in has been assigned to the QR Dex enterprise application in Microsoft Entra ID, either directly or through a group.
- SSO option not visible -- Confirm that your QR Dex team is on the Enterprise plan. SSO settings are available on the Plus, Pro, and Enterprise plans.