Skip to main content

SSO Configuration - Okta

Updated

This article details out how to configure your StockIQ instance to integrate with your Okta Identity Provider (IDP). In this article we will go over how to create and configure an appropriate application in your Okta admin dashboard, and how to correctly add or update existing users in StockIQ so that their existing permissions map to their Okta 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 Okta 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 you have access to your Okta admin dashboard. You should be able to:
    • Create and edit applications
    • Create and edit authorization servers
  • 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 an Application

The first step to configure StockIQ for integration with your Okta IDP is to create a new application in your Okta admin dashboard.

Some key notes before beginning:

  • The name of the application doesn't matter, if your IT department has a standard nomenclature they like to use they are welcome to.
  • Incorrectly configuring the Okta application can lead to authentication failures within StockIQ. Visit the troubleshooting page if you encounter issues.

Process

  1. Login to your Okta admin dashboard
  2. Navigate to Applications > Applications
  3. Click 'Create App Integration'
    • Sign-in method should be OIDC - OpenID Connect
    • Application type should be Single-Page Application
  4. Configure your new app integration
    • App integration name - can be whatever you like but we would suggest something with 'StockIQ' in the name so you can easily find it.
      • Make note of this app integration name as you can use it later when configuring StockIQ.
    • Grant type should be Authorization Code
      • Under 'Advanced' click Implicit (hybrid)
    • Sign-in redirect URIs - note that this is different between Sunshine Peak and Huron Peak releases. If you are unsure which version of Stock IQ you are using you can contact StockIQ support. Note that this URI is case sensitive.
    • Assignments - here you can elect to allow everyone in your organization to authenticate against this application, or to limit access to user groups that you control. The choice does not affect StockIQ but will affect how your team manages access.
      • An important note is that although once the SSO configuration is complete authentication will be completely handled by your IDP, authorization, is still handled within StockIQ. This means that you will need to still create StockIQ user accounts within the StockIQ application, and you will need to administer roles and permissions from within StockIQ as well.
      • If you allow everyone - you will want to enable federation broker mode, as suggested by Okta
      • If you limit access to selected groups - you will need to specify the groups at creation. You may need to pause application creation to go and create a StockIQ user group in your Okta admin dashboard
  5. Click 'Save'

Review the Application

In this step we review the Okta application integration that was created in the previous step, and ensure that it is properly configured.

Some key notes before beginning:

  • Copy the Client ID for the Okta application as we will need that later
  • Note that you can change the application configuration to suit your company's authentication policies such as requiring MFA, without affecting StockIQ integration

Process

  1. In the General tab, review the following
    • Client Credentials
      • Client ID - this is automatically generated but you should note it for later, simply copy it off to a text file for convenience. Note that this is not considered a secret value but you should still take care to protect it.
      • Ensure Proof Key for Code Exchange (PKCE) is required - this should be required because you indicated you were creating a SPA application
    • General Settings
      • Grant type - Authorization Code
      • Advanced > Other grants -  Implicit (hybrid) is enabled and 'Allow ID Token' is enabled
    • User Consent - while not required, it is a good idea to ensure that this is enabled so that your users are aware they are allowing StockIQ to read some of their identity claims, and which ones.
    • Login
      • Sign-in redirect URIs - has your correct StockIQ instance listed
        • note that you can have more than one redirect URI here if you wish to use this same application to authenticate against a sandbox environment if you have one.
        • Some IT teams may take issue with allowing an Okta application registration to authenticate to more than one application so check with your IT team before proceeding
  2. In the Sign On tab
    • Sign on methods - ensure it is only OpenID Connect
    • OpenID Connect ID Token
      • Issuer - Okta URL
      • Group claim filter - none (recall that roles and permissions are handled within StockIQ)
    • User authentication
      • Here you can select which authentication policy you want the app integration to follow; username and password, MFA, etc.
      • The choice does not affect integration with StockIQ but may be decided by your IT team in order to meet your security policies.
  3. In the Assignments tab
    • If you are limiting authentication via this app integration to specific users or groups in your Okta organization, ensure that they are correctly configured herein
    • Note that it is often times preferred to control by group then to directly specify users but that is a decision for your IT team

Verify Authorization Server

In this step we verify that the application integration we created and verified in the previous two steps can be used to authenticate a given user.

Some key notes before beginning:

  • Authorization servers are the main engines within Okta for minting authorization tokens
  • It is entirely possible to use the default authorization server, but your IT team may have a preference to create a new authorization server for the StockIQ app integration
  • Depending on whether you go with the default auth server or a new one you will need to be critically aware of your authorization and issuer endpoints. In most StockIQ documentation it is assumed you used the default authorization server.

Process

  1. In the Okta admin dashboard navigate to Security > API
  2. Select the authorization server you wish to use OR add an authorization server
  3. In the tab Access Policies, ensure that you have at least one access policy that applies to the application integration we created in the previous two steps.
    • We just created the app integration, so unless there is an access policy that is assigned to all clients odds are we need to create a new one
  4. In the Token Preview tab we can test that the access policy configured in the previous tab will correctly return the scopes we need.
    • Search for the StockIQ client we created previously
    • Select the Implicit (hybrid) grant type
    • Select a user to evaluate (note that if you have specified assignment restrictions you need to find a user that is assigned to the StockIQ client)
    • Select id_token for the response type
    • In the scopes field we need to include these three scopes; openid, email, profile
      • Note that you have to hit 'enter' after entering each scope
    • Click 'Preview Token'
    • Verify that you see the user's email address in the token response
  5. In the same Token Preview tab, we need to also verify that the same app registration and authorization server can also request an authorization code.
    • Search for the StockIQ client we created previously
    • Select the Authorization Code grant type
    • Select a user to evaluate (note that you should use the same user from the previous step)
    • In the scopes field we need to include these three scopes; openid, email, profile
      • Note that you have to hit 'enter' after entering each scope
    • Click 'Preview Token'
    • Verify that you see the user's email address in the token response
    • At this point you can also copy off the issuer 'iss' value as we will need this when we go to register the SSO configuration in StockIQ
  6. Assuming we correctly verified that we can get the access token for the given application integration we can now configure StockIQ. Before we go ensure you have the Issuer, you can either get this from:
    • the validation token we got in Token Preview, as the 'iss' value
    • the settings tab, it is the URL in the issuer field

Possible Issues

If, for either Authorization Code or Implicit (ID token) grant types you receive an error, you will be unable to authenticate against this app registration/authorization server from within StockIQ. See the list below for common issues and how to remedy them.

  • The client is not authorized to use the provided grant type.
    • This is the standard response when your application registration is not configured to provide either the Authorization Code or the ID token. Return to the app registration and ensure that both Authorization Code and Allow ID Token with implicit grant type are selected
  • Policy evaluation failed for this request, please check the policy configurations.
    • This indicates that you do not have an Access Policy that the application is valid for configured on the authorization server. Go to the Access Policies tab and review your access policies and ensure that you have an access policy that the StockIQ app registration satisfies.
    • NOTE: It is highly recommended that if you do not have an access policy that satisfies the StockIQ app integration that you create a new policy that explicitly targets your StockIQ app integration. Modifying an existing access policy can cause security vulnerabilities or can possibly exclude an existing security integration that was previously working.
  • User is not assigned to the client application.
    • This indicates that the user you used to preview the token does not have a valid assignment to the app integration. Either the use needs to be added to a group or the user needs to be assigned directly to the app integration.
    • NOTE: It is beneficial to use groups when making assignments to app registrations. Review the Okta docs if you have questions.
    • NOTE: It is also possible that the user you selected should NOT have access to the StockIQ app integration, review before making any security changes.

Configure StockIQ

Now that we have an application integration correctly configured in Okta we can configure your StockIQ instance.

Some key notes before beginning:

  • You will need to be able to restart your hosted StockIQ instance, if you are hosted in the StockIQ cloud you can contact StockIQ support before beginning and they can help you restart the app.
  • You will need the following pieces of information from Okta
    • Authority - the URL of the authorization server that you want to use to authenticate the application
    • Issuer - the issuer ID of the authority, often times this is the same as the authority but you need to verify that in Okta
    • Client ID - the client ID of the application registration that was created for StockIQ in the Okta admin dashboard
  • Once you have enabled SSO you will be unable to authenticate via your existing username and password

Process

  1. Navigate to your instance
  2. In the navigation blade on the left go to Admin > System Configuration
  3. Select 'SSO Authentication Settings'
  4. In the SSO Settings window enter the following information:
    • Enabled - ensure that this is checked
    • Name - this value doesn't really mater but it may be easiest to make it match the name of the application integration you created in Okta
    • Authority - the authority endpoint for the authorization server you want to use to authenticate the application, you should already have this otherwise you can review previous steps
    • Issuer - this should be the same as the Authority URL however you should have already verified this in previous steps
    • Client ID - the client id is the ID of the application integration, you should already have this, otherwise you can review previous steps
  5. 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 Okta 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 Okta 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's assignment to the application
  • 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 Okta account.

 

Related articles