Integrating with an Identity provider (here) allows you to Synchronize Users and Groups. If you want to require that your users sign-in with their credentials, including your organization’s required MFA steps, you can do so for MS Entra and Okta by following the steps below.

Once configured, any user signing into your XQ team will be required to sign-in with their organizational identity credentials,

Microsoft Entra

Overview

Setting up Entra ID integration requires your team to authenticate using their Microsoft accounts, providing a seamless and secure login experience. The process involves registering an application in Azure, configuring permissions, and connecting it to XQ.

Estimated setup time: 10-15 minutes

Before You Begin

To complete this setup, you’ll need:

• Administrator access to your Azure portal
• Access to the XQ Management Portal
• Your organization’s Tenant ID (we’ll show you where to find this)

Setting Up Entra ID Integration

Follow these steps to configure Entra ID as your identity provider for XQ.

1. Navigate to the Azure Portal
   1. Go to https://portal.azure.com and sign in with your administrator credentials.
2. Open App Registrations

3. Create a New Registration
   1. Click the + New Registration link at the top left of the page.

4. Configure Basic Settings
   1. Fill in the registration form:
      1. Name: Enter a descriptive name for your app (e.g., ‘XQMSG Integration’)
      2. Supported account types: Select the option that matches who can authenticate into your XQ team

5. Add Redirect URIs
   1. In the Redirect URI section, select Web from the dropdown, then enter the following URL:
      1. https://subscription.xqmsg.net/v2/azure/codevalidator

• and then click on Register button

6. Navigate to Certificates & Secrets
   1. After your app is registered, you’ll see the Overview page. Click the Add a certificate or secret link in the top right of the overview section. 
7. Create a Client Secret
   1. Click the New Client Secret button in the Client secrets section.

8. Configure and Save the Secret
   1. Fill in the secret details:
      1. Description: Enter a meaningful description (e.g., ‘XQMSG Integration Secret’)
      2. Expires: Select an expiration period based on your security requirements
      3. Click Add to generate the secret. 
9. Copy the Client Secret Value

Important: Copy the Value that appears after creating the secret. This is your Client Secret, and you’ll need it later when configuring XQ. This value will only be shown once! Store it somewhere safe.

10. Configure Token Settings
    1. Navigate back to the Overview section and then click the Redirect URIs link on the right hand of the page.
    2. On the Authentication page, scroll down to the Implicit grant and hybrid flows section and check both:
       1. ID tokens
       2. Access tokens
    3. Click Save at the bottom of the page.

11. Add API Permissions
    1. Navigate to the API Permissions section in the left menu. Click Add a permission.

12. Select Microsoft Graph Permissions
    1. In the Request API permissions panel:
       1. Click on Microsoft Graph

2. Select Delegated permissions
   1. Use the search field to find and check the following permissions:
      1. email
      2. openid
      3. profile
      4. User.Read
3. Click Add permissions at the bottom

13. Grant Admin Consent
    1. Back on the API permissions page, click the Grant admin consent for [Your Organization] button at the top of the permissions list. Confirm when prompted.

Why this matters: This step allows users in your organization to authenticate without needing to individually consent to permissions.

14. Copy the Application (Client) ID
    • Go back to the Overview section. Find and copy the Application (client) ID. You’ll need this value to configure XQ.

15. Get the Authorization Endpoint
    1. Still on the Overview page, click Endpoints at the top.
    2. Find the OAuth 2.0 authorization endpoint (v2) and copy it.
       • Important: Remove the https:// from the beginning of the URL before using it.
       • Special case: If your endpoint contains /common/ or /organizations/, you’ll need to replace that part with your Tenant ID.
         • Example: login.microsoftonline.com/YOUR_TENANT_ID/oauth2/v2.0/authorize

Connecting to XQ

Now that you’ve gathered all the necessary information from Azure, it’s time to configure XQ. You’ll need to enter the values you collected into the XQ Management Portal.

Required Information

You should have collected the following values from Azure:

• Login Domain (from Step 15)
  • Format: login.microsoftonline.com/YOUR_TENANT_ID/oauth2/v2.0/authorize (without https://)

• Login Audience
  • https://subscription.xqmsg.net

• Login Client ID
  • This is your Application (client) ID
• Login Client Secret
  • This is the secret value you copied and saved securely

Entering Values in XQ

To complete the integration, log into your XQ Management Portal and navigate to the identity provider configuration section. By checking Require Identity Provider Authentication checkbox. Enter the values you collected above in their corresponding fields.

Testing Your Integration

After configuring the integration in XQ, it’s important to test that everything is working correctly.

• Log out of XQ and attempt to log back in using your Entra ID credentials
• Verify that you’re redirected to the Microsoft login page
• Confirm that you can successfully authenticate and access XQ
• Test with multiple user accounts to ensure permissions are working correctly

Troubleshooting

If you encounter issues during setup or testing, here are some common solutions:

• Redirect URI mismatch
  • Make sure the redirect URI in Azure exactly matches the URL you’re using for XQ (staging or production). Even a small difference will cause authentication to fail.

• Permission errors
  • Double-check that you’ve granted admin consent for all required permissions (email, openid, profile, and User.Read).
• Token configuration issues
  • Verify that both ID tokens and Access tokens are enabled in the Authentication settings.
• Tenant ID problems
  • If your endpoint contains /common/ or /organizations/, make sure you’ve replaced it with your actual Tenant ID in the Login Domain field.

Okta

Connecting Okta as a Single Sign-On (SSO) provider with XQ requires your users to authenticate into XQ products using their Okta credentials. This integration uses OpenID Connect (OIDC) to provide a seamless and secure login experience for your team.

Important: This guide covers SSO authentication setup. If you’re looking to synchronize users and licenses from Okta, please refer to our Okta User Management Integration guide.

Prerequisites

Before you begin, ensure you have:

• Administrator access to your Okta account
• Administrator access to the XQ Management Portal
• Your XQ environment URL (Staging or Production)

Part 1: Creating the Okta Application

In this section, you’ll create a new OIDC application in Okta that will enable SSO for XQ.

1. Login to your Okta domain and authenticate using your administrator credentials.
2. In the left-hand navigation menu, click on Applications followed by clicking on Applications again.

3. Click the Create App Integration button.
4. In the modal that appears:
   1. Select OIDC – OpenID Connect as the sign-in method
   2. Select Web Application as the application type
   3. Click Next

5. Provide a name for your application integration (recommended: “XQ Message SSO”). Optionally, you can upload a logo for easier identification.

6. In the Grant type section, check both:
   1. Client Credentials
   2. Refresh Token

7. In the Sign-in redirect URIs field, enter the appropriate URL for your XQ environment:
   1. https://subscription.xqmsg.net/v2/okta/codevalidator
8. In the Sign-out redirect URIs field, enter the URL for your XQ environment:
   • https://manage.xqmsg.com/okta/logout

9. In the Assignments section, select Allow everyone in your organization to access.
10. Important: Do NOT enable immediate access with Federation Broker Mode.

10. Click Save to create the application.
11. After the application is created, copy and save both the Client ID and Client Secret. You’ll need these values when configuring XQ.

Note: The Client Secret will only be displayed once. Make sure to save it in a secure location.

Configuring API Scopes

12. In your application, navigate to the Okta API Scopes tab.
13. Find okta.groups.read in the list and click the Grant button on the right-hand side.

Note: This scope allows XQ to read group information from Okta, which is necessary for applying group-based policies.

Assigning Users to the Application

14. Navigate to the Assignments tab of your application.
15. Assign the users or groups that should be able to authenticate into XQ using this application. You can select specific users, or assign Everyone under Assign to Groups.

Note: Only users who are assigned to this application will be able to use Okta SSO to log into XQ.

Part 2: Creating an Authorization Server

Next, you’ll create a custom authorization server in Okta that will handle authentication requests from XQ.

16. In the left-hand navigation menu, click on Security followed by API.

17. Click on the Add Authorization Server button.
18. Fill in the authorization server details:
    1. Name: Provide a descriptive name (e.g., “XQ Authorization Server”)
    2. Audience: Enter the appropriate URL for your XQ environment:
       • https://subscription.xqmsg.net
    3. Description: Provide a brief description (e.g., “Authorization server for XQ SSO integration”)
19. Click Save to create the authorization server.

Configuring Access Policies

20. Click on the authorization server you just created to open its settings.
21. Navigate to the Access Policies tab and click Add Policy.

22. Fill in the policy details:
    1. Name: Provide a descriptive name (e.g., “XQ Access Policy”)
    2. Description: Provide a brief description
    3. Assign to: Select All clients
23. Click Create Policy.

Creating a Policy Rule

24. Within your newly created policy, click the Add Rule button.
25. Provide a descriptive name for your rule (e.g., “XQ Access Rule”).
26. Leave all other settings at their default values and click Create Rule.

Adding a Custom Scope

27. Navigate to the Scopes tab of your authorization server and click Add Scope.
28. Fill in the scope details with the following values:
    1. Name: verify
    2. Display phrase: Allow XQ Verification
    3. Description: Simple verification
    4. User consent: Implicit
29. Click Save to create the scope.

Getting Your Login Domain

30. Click the Back to Authorization Servers link to return to the authorization servers list.
31. Copy the Issuer URI for your authorization server, but remove the https:// prefix. This will be your Login Domain for XQ.
    • Example: If your Issuer URI is https://dev-12345678.okta.com/oauth2/default, your Login Domain will be dev-12345678.okta.com/oauth2/default

Part 3: Configuring XQ

Now that you have all the required information from Okta, you’ll need to configure these values in the XQ Management Portal. Below is a summary of the values you’ll need:

XQ Field	Where to Find in Okta
Login Domain	Authorization Server Issuer URI (without https://)
Login Audience	Authorization Server Audience
Login Client ID	Application Client ID
Login Client Secret	Application Client Secret

Entering Your Okta Configuration in XQ

To complete the integration:

• Log in to your XQ Management Portal
• Navigate to the Integrations section
• Locate the Okta SSO configuration area
• Enter the four values from the table above
• Save your configuration

Once saved, users assigned to the Okta application will be able to log into XQ using their Okta credentials.

Testing Your Integration

After completing the configuration, it’s important to test the integration:

• Log out of XQ if you’re currently logged in
• Navigate to the XQ login page
• Enter your email in the ‘Email address’ field and click the link delivered to your inbox.
• Select your team, if prompted, and sign-in with your Okta credentials
• Verify you’re successfully redirected back to XQ and logged in

Troubleshooting

If you encounter issues with your Okta SSO integration:

• Redirect URI mismatch: Verify that the redirect URIs in Okta exactly match the environment you’re using (staging vs. production)
• Login Domain issues: Ensure you removed the https:// prefix from the Issuer URI when entering the Login Domain in XQ
• User not assigned: Check that the user attempting to log in is assigned to the Okta application
• Client Secret expired: Client secrets can expire. Generate a new one in Okta and update it in XQ if needed
• Scope not granted: Ensure the ‘verify’ scope was created with the exact specifications in the authorization server

You’re All Set!

Your Okta SSO integration is now configured. Users assigned to the Okta application can now use their Okta credentials to securely log into XQ. This provides a seamless single sign-on experience while maintaining strong security practices.

Need Help?

If you encounter any issues or have questions about the Okta SSO integration, please contact our support team at support@xqmsg.com.