Skip to main content

SSO Configuration - Entra

Updated

This article details out how to configure your StockIQ instance to integrate with your Microsoft Entra Identity Provider (IDP). In this article we will go over how to create and configure an appropriate application registration in your Microsoft Entra Admin Center instance, how to configure Stock IQ to utilize this app registration, and how to correctly add or update existing users in StockIQ so that their existing permissions map to their Entra authenticated identity within the application.

Prerequisites

  • Your instance must support TLS/SSL encryption, that is the website must be https
    • If your instance does not support TLS/SSL (that is that the website is http and not https), contact StockIQ support
  • You must have an Entra account
  • Your instance must be upgraded to a version of StockIQ that supports SSO integration
    • SSO is currently supported across all recent releases of StockIQ
    • If you think you are on an older version of StockIQ contact StockIQ support to get your version upgraded to the latest

Before Beginning

  • Ensure that the you have access to your Microsoft Entra Admin Center (https://entra.microsoft.com/#home).You should be able to:
    • Create and edit application registrations 
  • Have ready the following pieces of information:
  • Ensure that existing StockIQ user's have the appropriate work email saved as their email within StockIQ
    • After the configuration is completed, authentication of users will be handled by  your IDP
    • Roles and Permissions are still handled by the StockIQ application, to ensure that an authenticated user is correctly mapped between your IDP and StockIQ's User database table, the emails of both the user's IDP identity and the record must match
      • Example: You have a StockIQ user whose email is john@your-company.com, however, in your IDP that same user's email is jdoe@your-company.com. You will want to update the existing StockIQ user so that their email correctly matches their IDP record. 

Create App Registration

The first step to configure StockIQ for integration with your Entra IDP for SSO is to create a new Entra app registration.

Some key notes before beginning:

  • The name of the app registration doesn't matter, if your IT department has a standard nomenclature they like to use they are welcome to.
  • For supported account types, ultimately you can choose what you would like, you are responsible for the security of your Entra environment. We strongly suggest that you only support accounts within your organization to minimize your risk profile.
  • When configuring the redirect URI, the desired platform we require is SPA. This will ensure that Proof for Key Code Exchange (PKCE) is enforced on the authorization code flow and strengthens the authentication security.

Process

  1. Login to your instance of the the Microsoft Entra Admin Center (https://entra.microsoft.com/#home).
  2. Navigate to the Applications > App Registrations
  3. Click 'New registration' and provide the following information:
    1. Name: This will be the friendly name of the StockIQ app registration. We suggest StockIQ.
    2. Supported Account Types: We suggest 'Accounts in this organization' (single-tenanted) . It is the most secure but will limit access to StockIQ to users in the your organization only.
    3. Redirect URI: Set the platform to 'Single-page application (SPA)' and enter in your instance URI, note that this is different between the legacy releases (Sunshine Peak and older) and the latest releases (Huron Peak and newer). If you are unsure of your release version, contact StockIQ Support. Note that the redirect URI is case sensitive
            Sunshine Peak: 'https://your-instance.stockiqtech.net/Account/Login'
            Huron Peak:      'https://your-instance.stockiqtech.net/signin-oidc'

      Note that if your instance specifies a port number you will need to adjust the URI accordingly, such as 'https://your-instance.stockiqtech.net:8020/Account/Login' or 'https://your-instance.stockiqtech.net:8020/signin-oidc'
    1.  
  2. Verify the information you entered is correct and click 'Register'

Configure App Registration

Now that the app registration is completed we will need to configure a few things. Open your newly created app registration, if it is not already.

  1. In the 'Overview' tab, note and copy off to a text file the Client ID and Tenant ID, we will need them later. Note that these values are not considered sensitive information by Microsoft.
  2. Navigate to the 'Authentication' tab. Confirm that the redirect URI is correctly configured to point at 'https://your-instance.stockiqtech.net/Account/Login' or whatever your valid instance URI is.
  3. Under the 'Implicit grant and hybrid flows' section of the 'Authentication' tab, ensure that ID tokens is checked and hit save.
  4. In the 'Token Configuration' tab, grant the email claim.
    1. Click 'Add'
    2. Token type is ID
    3. Select the 'email' claim

Configure StockIQ

Now that the app registration has been correctly configured, it is time to configure your StockIQ instance.

  1. Navigate to your instance
  2. In the 'System Configuration' section, search for 'SSO', select 'SSO Authentication Settings'
  3. In the SSO settings window, enter the following information:
    1. Enabled: Ensure that this is checked.
    2. Name: This value really doesn't matter, its just to help remember which App Registration is controlling SSO for StockIQ. Make it match the name of the app registration you created in Entra.
    3. Authority: This is the authority URL that is authenticating your users. For Entra the value is: https://login.microsoftonline.com/{TenantId}/v2.0
      1. Replace {TenantId} with the tenant ID from your Entra instance. You should already have this written down.
    4. Issuer: This is the ISS claim that comes back in the access token, for Entra V2 it is the same as the Authority, copy and past the Authority into the Issuer field.
    5. Client ID: This is the Client ID of the app registration that was configured in the previous two steps. You should have it written down somewhere as instructed in a previous step but if not you can easily find it by navigating back to the App Registration and getting it from the 'Overview' tab
  4. Hit 'Save'

Restart the Application

For this step, it is possible that you will need to coordinate with StockIQ support to have them restart your hosted instance of StockIQ. If you host your own instance of StockIQ you can restart the StockIQ application on your own.

  1. On the server that is hosting your instance;
    1. Open IIS Manager
    2. Find the correct StockIQ instance
    3. Restart the application.

Confirm Changes

Now that SSO has been configured it is time to confirm that the changes were successful.

  1. Navigate to your instance
    1. If you are already authenticated, log out, Home>User Options>Sign Out
    2. You should be redirected automatically to the login screen
  2. You will notice that the login page looks slightly different, instead of fields for username and password there is one field for email address
    1. Enter your email address into the email address field and hit 'Log In'
  3. You should be prompted by Microsoft to give the newly created app registration permission to read your email address from your identity. You must give access to use SSO.
  4. You should be authenticated and should be able to operate within StockIQ exactly as you did before.

Things to Remember

Please remember the following:

  • Authentication of user is happening within your Entra instance, meaning if you wish to restrict a user's access you have two options:
    • Disable a user's account from within StockIQ at Admin>Users, select the user in question, disable them by unchecking Is Active and saving their changes
    • Remove a user from their Entra instance. This option would really only be chosen if they were also removing the employee from their organization (e.g. terminating employment)
  • Adding new users
    • Adding new users happens much the same, an admin level StockIQ user would create a new record for the user, setting the roles and permissions, and saving the new user record.
    • One important reminder is that the email address of the user record in StockIQ MUST MATCH the user's email address within your Entra account.

Related articles