Single sign-on (SSO) is an authentication method that enables users to sign-in using the same credentials they have for their work account. Users can request to enable SSO on their ioTORQ system by emailing support@iotorq.com. Once SSO is enabled on their ioTORQ system, they can integrate their identity provider with ioTORQ EMIS.
Supported SSO Protocol
SSO on ioTORQ EMIS is based on the OIDC protocol using OAuth 2.0.
Supported Identity Providers
ioTORQ EMIS supports Azure AD as the identity provider for SSO.
Setting-up SSO
Setting-up SSO on your ioTORQ system is a 2-step process:
- Enabling SSO in ioTORQ EMIS (by request)
- Configuring SSO in Azure AD (by an Azure AD admin in your company)
Enabling SSO in ioTORQ EMIS
Currently, configuring SSO is by request. When emailing support@iotorq.com to enable SSO, the following information has to be provided:
- SSO Policy: Optional or Mandatory
- Azure AD Tenant ID
Optional vs Mandatory
When SSO is optional, users are given two options for authenticating: (a) signing-in with Microsoft (b) signing-in using ioTORQ EMIS' username and password.
When SSO is mandatory, the user is asked for their work email address. This should be the same email address found in the identity provider of the user's employer.
We recommend starting with making SSO optional. Once SSO has the desired configuration in the chosen identity provider (see section "Configuring SSO in Azure AD") and has been tested (see section "Testing SSO in your ioTORQ EMIS portal"), you can then request to make SSO mandatory by emailing support@iotorq.com.
Azure AD Tenant ID
When requesting to enable SSO, you need to provide your company's Azure AD Tenant ID. This can be found in the Azure Portal > Azure Active Directory > Overview:
ioTORQ EMIS needs the tenant ID to allow your Azure AD tenant to be integrated with our multi-tenant application. This also help verify that the user who successfully authenticated through the Microsoft Login page belongs to your Azure AD tenant.
Adding ioTORQ EMIS as an Enterprise Application in Azure AD
Depending on your Azure AD policies, you may or may not need an Azure AD Administrator to be an EMIS User before your employees can use SSO.
Adding ioTORQ EMIS without an Azure AD Administrator
If your Azure AD tenant policy does not require an Azure AD Administrator to add an enterprise application, your employees can start signing in using their Microsoft credentials.
On the Microsoft login page, your employees have to allow ioTORQ EMIS to read their basic profile by clicking "Accept".
At the first successful authentication, ioTORQ EMIS will be added as an Enterprise Application in your Azure AD tenant:
Adding ioTORQ EMIS requiring an Azure AD Administrator
If your Azure AD tenant policy requires that only an Azure AD Administrator grants consent to applications, then your Azure AD Administrator has to be a user in EMIS (See "Creating Users" section in "User Management"). Once the Azure AD administrator has been added as an EMIS user, the Azure AD administrator has to do the initial SSO authentication.
Check-off "Consent on behalf of your organization" to grant consent for the whole organization. If you do not have this checked off and you later decide that you want to grant admin consent, see "Granting Admin Consent" section.
Granting Admin Consent
For end-users to be able to use single sign-on, an Azure AD administrator needs to grant admin consent. To grant admin consent, in Azure AD go to Enterprise Applications, then select ioTORQ EMIS.
This assumes you've already added ioTORQ EMIS as an enterprise application in your Azure AD tenant. If not, see the section “Adding ioTORQ EMIS as an Enterprise Application”
From the “ioTORQ EMIS Enterprise Application” page, go to Security > Permissions; and click “Grant admin consent for <tenant>”
This will open a new window where you are shown a consent box and prompted to accept permissions requested by ioTORQ EMIS to "Sign in and read user profile"
Once you click `Accept`, you will be taken back to the Azure Portal with a message, "Admin consent was successfully granted"
Permissions Required for Consent
All the permissions required by ioTORQ EMIS are necessary for single sign-on authentication. They are to ensure that the person attempting to access ioTORQ EMIS is truly who they claim to be and necessary for ioTORQ EMIS to verify whether they have the appropriate authorization to access certain parts of the system.
Limiting Access to Specific Users and Groups
You can allow only specific users and groups from your Azure AD tenant to have access to ioTORQ EMIS by using the "Assignment required?" option in Azure AD. To enable this option, in Azure AD go to Enterprise Applications, then select ioTORQ EMIS.
This assumes you've already added ioTORQ EMIS as an enterprise application in your Azure AD tenant. If not, see the section “Adding ioTORQ EMIS as an Enterprise Application”
From the “ioTORQ EMIS Enterprise Application” page, go to Manage > Properties; and set “Assignment required?” to “Yes”
Adding and Removing Users
Once “Assignment required?” is set to “Yes”, access to ioTORQ EMIS will be limited to what's specified under “Users and groups”,
You can add or remove a user/group by using the buttons highlighted red. To remove a user, you first have to select the users/groups to remove. For more info, see Azure's official documentation.
Summary
In summary, the steps to setup SSO on your ioTORQ EMIS portal are the following:
- Enable SSO in ioTORQ EMIS
- Email support@iotorq.com and provide necessary information
- Setup SSO in Azure AD
- Add ioTORQ EMIS enterprise application in Azure AD, either through an initial SSO authentication peformed by an employee who uses EMIS or an Azure AD administator.
- Grant admin consent for ioTORQ EMIS
- (Optional but highly recommended) Limit access by setting "Assignment required?" to "Yes"
- (If "Assignment required?" is set to "Yes") Specify users and groups that will have access to ioTORQ EMIS.
Testing SSO in your ioTORQ EMIS portal
Pre-requisites
- SSO has to be enabled in ioTORQ EMIS and properly configured in Azure AD (refer to the section "Setting-up SSO")
- An existing ioTORQ EMIS user
Testing optional SSO
If you requested SSO to be optional, you use single sign-on by clicking "Sign in with Microsoft"
This will start the authentication process in Microsoft. If you are not logged in to your work account, you will be directed to the Microsoft Login page,
If you are already logged in to your work account in Microsoft or upon successful authentication, you will be redirected to the ioTORQ EMIS Portal.
Testing mandatory SSO
If you requested SSO to be mandatory, provide your work account's email address in ioTORQ EMIS' login page and click "Sign in with Microsoft",
This will start the authentication process in Microsoft. If you are not logged in to your work account, you will be directed to the Microsoft Login page with the email address already provided,
If you are already logged in to your work account in Microsoft or upon successful authentication, you will be redirected to the ioTORQ EMIS Portal.
Troubleshooting
When end users use SSO to authentication and SSO is not configured properly, they might encounter the following error messages:
“The signed in user '<email>' is blocked because they are not a direct member of a group with access,...”
This happens when an Azure AD Administrator has set "Assignment required?" to "Yes" but did not add the user to a group that has ioTORQ EMIS access or did not directly assign the user under ioTORQ EMIS “Users & groups.” To resolve this, see the section, “Limiting Access to Specific Users and Groups” > “Adding and Removing Users.”
“<email> does not have an active account in ioTORQ EMIS.”
This happens when the user successfully authenticates through the login page of their employer's identity provider (e.g. the Microsoft Login page), however, they do not have an account in ioTORQ EMIS. To add the user in ioTORQ EMIS, contact your ioTORQ EMIS portal's administrator. Once the user is created, they will be able to access ioTORQ EMIS.
“Account in <tenant>'s identity provider (<identity provider>) does not have an associated email address.”
This happens when the user does not have an email set in the identity provider. For example, in the screenshot below is the profile of a user without an email address,
To resolve this error, add an email address to the email field by clicking “Edit Properties” on the top-left (highlighted in red).
“To login to EMIS using your Microsoft account, you have to consent to permissions requested by EMIS.”
This happens when the end-user does not click `accept` and cancels on the consent box provided by Microsoft. To resolve this, sign in with Microsoft and click `Accept` on the consent box displayed:
Frequently Asked Questions
Does ioTORQ EMIS support auto-provisioning and deprovisioning (SCIM)?
ioTORQ EMIS currently does not support auto-provisioning or de-provisioning.
How do I give an employee access to ioTORQ EMIS?
Giving an employee access to ioTORQ EMIS is a 1-step or 2-step process, depending on how you configured the ioTORQ EMIS application in Azure AD:
- Ensure that the employee has an account created in ioTORQ EMIS
- (Applicable only if "Assignment required?" is set to "Yes") Ensure the user is included under
ioTORQ EMIS' "Users and groups" in Azure AD.- See section "Limiting Access to Specific Users and Groups" for more info.
How do I remove access to ioTORQ EMIS from an (ex-)employee?
The quickest way to remove someone access to ioTORQ EMIS is by doing the following:
- Making SSO mandatory
- Email support@iotorq.com to make SSO mandatory on your ioTORQ EMIS system
- Enabling the "Assignment required" option in Azure AD
- See section "Limiting Access to Specific Users and Groups" for more info.
Once those two conditions are satisfied, you can remove access by going to the ioTORQ EMIS' "Users & groups" page in Azure AD,
Additional Support
If you have other questions and need additional support, email support@iotorq.com.