Prerequisites
Ensure you have all of the following before you start:
Administrator access to your Microsoft Entra tenant.
Administrator access to your NowGo account.
A configured NowGo subdomain.
Target users or groups identified for end-to-end testing.
Matching NowGo accounts created or checked before testing:
Dashboard users must use the same email address as the OIDC email claim.
Drivers must use the same driver email address as the OIDC email claim.
Account-level access enabled in NowGo:
Dashboard users need Account is active enabled in Settings -> User accounts.
Drivers need Account enabled enabled in Resourcing -> Drivers.
Guide outcomes
Connected NowGo to Microsoft Entra using an OIDC integration.
Entered the NowGo callback URI in Microsoft Entra.
Saved Microsoft Entra OIDC credentials and OAuth2 Base URL in NowGo.
Assigned and prepared users.
Assigned target users or groups to the Microsoft Entra OIDC application.
Confirmed matching Dashboard user or Driver email values and account-level access in NowGo.
Verified the integration.
Aligned OIDC identity claims with corresponding NowGo user values.
Completed an end-to-end SSO test with an assigned user.
‼ Important: OIDC SSO controls authentication only. It confirms who the user is, but it does not grant product access in NowGo. When SCIM is not used, users rely on account-level enablement. A user can authenticate successfully but still have limited or no useful access if their Dashboard user or Driver account is missing, inactive, expired, or not matched.
NowGo callback URI
When configuring Microsoft Entra for OIDC SSO, provide a redirect URI supplied by NowGo. Microsoft Entra sends the authentication code to this URI after a user signs in. Find this value displayed on the SSO Subdomain Settings page.
The expected format is
<https://<your-subdomain>>.onpremonition.com/iam/sign-in/oauth2/continue>
For example, if your chosen subdomain is customer, your redirect URI is
<https://customer.onpremonition.com/iam/sign-in/oauth2/continue>
‼ Important: Enter this exact callback URI in your Entra application's sign-in redirect URIs. Using the wrong URI results in sign-in errors.
Configuring Microsoft Entra
This section describes how to create the SSO app registration in Microsoft Entra.
In the Microsoft Entra admin center, navigate to Identity, Applications, and then App registrations.
Click New registration.
Type a descriptive name, such as NowGo SSO Integration, in the Name field.
Under the Supported account types heading, select the appropriate directory option for your organization.
Under the Redirect URI heading, select Web from the dropdown menu, and paste your NowGo callback URI.
Click Register.
In the app's left menu, navigate to Certificates & secrets, and then click New client secret.
Add a description, choose an expiry, and click Add.
Copy the Value of the client secret immediately, because it is hidden after you leave the page.
Copying credentials to NowGo
This section describes how to transfer your new Microsoft Entra app credentials into your NowGo settings.
From the Microsoft Entra app's Overview page, copy the Application (client) ID.
From the same page, copy your Directory (tenant) ID.
In NowGo, navigate to Settings, select Accounts & Security, and click SSO Credentials.
Type a descriptive name in the Label field (for example, Entra OIDC).
Paste the Microsoft Entra Application (client) ID in the Client ID field.
Paste the Microsoft Entra client secret value in the Client secret field.
Type your Microsoft Entra base URL in the OAuth2 Base URL field using this exact format:
<https://login.microsoftonline.com/<<your-tenant-id>>/v2.0/>
Make sure this URL ends with a trailing slash (/).
(Optional) Check the Require reauthentication checkbox to force a credential prompt on each sign-in attempt.
Click Save changes.
‼ Important: NowGo uses the OAuth2 Base URL to construct requests to the OAuth2 server. The URL entered in NowGo must end with a trailing slash (/).
Assign and validate users
This section describes how to assign users to your Microsoft Entra OIDC application and verify that Microsoft Entra sends the correct identity values to NowGo.
Assigning users in Microsoft Entra
In the Microsoft Entra admin center, navigate to Enterprise applications and select the NowGo app you created.
Navigate to Users and groups, and then click Add user/group.
Select and assign the users or groups who need to use this Microsoft Entra OIDC application.
Confirm those users have matching Dashboard user emails or Driver emails in NowGo.
Confirm account-level access is enabled where needed:
Dashboard users need Account is active enabled in Settings -> User accounts.
Drivers need Account enabled enabled in Resourcing -> Drivers.
Confirm those users have the expected OIDC email and preferred_username values.
Verifying OIDC claims in Microsoft Entra
In the Microsoft Entra admin center, navigate to Identity, Applications, and then App registrations.
Select your NowGo application.
Under the Manage menu, select Token configuration.
Review the configured claims to ensure email and preferred_username are included.
If they are missing, click Add optional claim.
Select ID for the token type.
Select the email and preferred_username claims, and click Add.
During testing, confirm the email claim contains the same email address as the user's Dashboard user email or Driver email in NowGo.
Confirm the preferred_username claim uses that same email value where possible.
‼ Important: Configure OIDC preferred_username to use the user's email address where possible. A non-email preferred_username can make later support or repair harder, and sign-in may fail if OIDC email and preferred_username point to different existing IAM users.
Verifying the integration
This section describes how to test your completed SSO workflow.
Choose a target user assigned to the Microsoft Entra OIDC application.
Confirm the target user's OIDC email and preferred_username values match their email address.
Confirm that user has a matching Dashboard user or Driver account in NowGo.
Confirm account-level access is enabled in NowGo:
Dashboard users: Account is active in Settings -> User accounts.
Drivers: Account enabled in Resourcing -> Drivers.
Log out of NowGo.
On the sign-in page, click Sign On with SSO.
Type your NowGo org subdomain.
Complete the sign-in flow in Microsoft Entra.
Confirm you return to NowGo and access the expected dashboard or app area.
Expected negative outcomes
These outcomes are expected and indicate authorisation configuration issues rather than OIDC protocol failures. Successful SSO can still lead to limited or no useful product access when account-level access is missing or incomplete.
User authenticates but cannot sign in to the NowGo mobile app: The user authenticates successfully, but the matching Driver account is not enabled, is expired, or was not matched by driver email.
User authenticates and signs in to NowGo Dashboard, but sees only an Account Settings page: The user authenticates successfully, but the matching Dashboard user is not active or does not have the required dashboard permissions.
IAM state caveats
Authorisation outcomes are determined by two separate control types. Because these controls are independent, users can authenticate successfully but still see different access outcomes depending on the combination.
Account-level enablement (manual account status):
Dashboard users: Account is active in Settings -> User accounts.
Driver users: Account enabled in Resourcing -> Drivers.
IAM-group authorisation (SCIM/IAM policy):
Dashboard access: Users in group can access dashboard.
Driver app access: Users in group can access app.
Account toggle | IAM group access toggle | What admins see | Likely user experience | What to check next |
ON | ON | User account is active and IAM group grants access. | Sign in works as expected. | If access fails, check the Troubleshooting reference tables. |
ON | OFF | User account is enabled but access is not managed by IAM groups. | Sign in works as expected for manually managed users. | This is the expected state when SCIM is not used. Check account-level Dashboard or Driver settings. |
OFF | ON | IAM groups grant access, but individual users show as disabled. | Sign in may work only where IAM group access is intentionally managing authorisation. | This is usually a SCIM/IAM-managed state. For no-SCIM users, enable the Dashboard user or Driver account manually. |
OFF | OFF | User account is inactive and IAM group does not grant access. | User is treated as deactivated. | Re-enable the account-level Dashboard user or Driver account to restore access. |
For no-SCIM integrations, changing IAM group access toggles should not be the primary fix for manually managed users. Check account-level enablement first: Account is active for Dashboard users and Account enabled for Drivers.
Troubleshooting
Use these user-visible phases to diagnose SSO issues:
After clicking sign in, but before reaching Microsoft Entra.
After signing in with Microsoft Entra.
Post-redirect outcome.
Mobile app troubleshooting
Phase | What the user sees | Most likely cause | What admin should check |
1 | Invalid Subdomain alert | Unknown subdomain, or org lacks an IAM identity provider. | Confirm the subdomain is correct and SSO credentials exist in NowGo. |
1 | App does not proceed to IdP | Invalid redirect setup generated at sign-in start. | Confirm callback values are configured consistently for the tenant. |
2 | Invalid Login Details alert | App did not receive an authorisation code on redirect. | Verify Entra app assignment and check the redirect URI format. |
2 | Single Sign-on failed alert | Failed code exchange or expired authorisation code. | Retry logging in; verify no proxy layer is modifying query parameters. |
2 | Generic auth failure alert | OAuth2 credential mismatch between NowGo and Entra. | Re-check NowGo SSO values and verify the OAuth2 Base URL ends with a slash. |
3 | Sign in fails with account message | Driver account is not eligible for app access. | Check that the Driver account is enabled, not expired, and matches the OIDC email claim. |
3 | Signed in but limited access | Authentication succeeded; authorisation is missing. | Confirm the Driver account is enabled in Resourcing -> Drivers. |
3 | Redirects to unexpected flow | Callback destination mismatch. | Reconcile all redirect values across subdomain and Entra settings. |
Web app troubleshooting
Phase | What the user sees | Most likely cause | What admin should check |
1 | Invalid subdomain alert | Subdomain contains invalid characters. | Re-enter only the org subdomain value (no protocol or full domain). |
1 | Does not reach IdP sign-in | Unknown subdomain, or org lacks SSO configuration. | Confirm the subdomain exists and SSO credentials are saved in NowGo. |
2 | Returns to sign-in page | Dashboard callback did not include authorisation code. | Verify Entra sign-in redirect URI points to the correct tenant subdomain. |
2 | Connection trouble alert | Network failure during sign-in completion. | Check browser connectivity and confirm NowGo API is reachable. |
2 | Authentication failed alert | OIDC authorisation code flow failed. | Retry logging in; re-check Client ID, Client secret, and OAuth2 Base URL. |
2 | Account deactivated alert | User lacks an active IAM user in NowGo. | Confirm the user exists in NowGo and account-level access has been enabled. |
3 | Signed in but limited access | Authentication succeeded; authorisation is missing. | Confirm Dashboard user status and permissions in Settings -> User accounts. |
3 | Redirects to unexpected flow | Callback destination mismatch. | Reconcile NowGo subdomain settings and Entra callback values. |
Final checklist
Before going live, confirm the guide has helped you reach and verify this end state:
Microsoft Entra app is configured as an OIDC Web application with Authorization Code flow.
Redirect URI is entered exactly and matches the NowGo callback format.
NowGo SSO credentials are saved with a valid Microsoft Entra OAuth2 Base URL.
Microsoft Entra OAuth2 Base URL ends with a trailing slash (/).
Target users or groups are assigned to the Microsoft Entra OIDC application.
OIDC email claim contains the user's email address.
OIDC preferred_username claim is mapped to the same email value where possible.
Target Dashboard users and Drivers exist in NowGo before first SSO testing.
Dashboard users have Account is active enabled where dashboard access is required.
Drivers have Account enabled enabled where mobile app access is required.
At least one end-to-end test succeeds with a real assigned user.