Install Nodinite v7 - OpenID Connect (OIDC) and OAuth 2.0
This authentication method is recommended for cloud-based deployments or when you want to integrate with external identity providers. It supports modern authentication protocols and provides enhanced security features.
For details on registering Nodinite applications in Azure AD (Entra ID) and configuring permissions, see the Register Nodinite Applications in Azure AD (Entra ID) with OpenID guide.
Tip
New to OpenID Connect? Before diving into configuration details, review the OpenID Connect & OAuth2 Integration diagrams below to understand the authentication flow and required IDP setup.
Warning
Migrating from Windows / Kerberos to OpenID Connect? The Email Alarm Plugin cannot be used with OpenID Connect authentication. This plugin relies on Nodinite Users with email addresses populated from Active Directory — a mechanism that does not exist in OpenID Connect / OAuth 2.0 mode.
Before migrating, you must:
- Disable the Email Alarm Plugin from all Monitor Views that currently use it
- Remove the plugin entry from each affected Monitor View
- Replace it with the E-mail with options alarm plugin, which allows you to specify recipient addresses directly — independent of user profile data
Failure to do so will result in silent alarm failures after migration, as no Windows-based user records with email addresses will exist.
Example of the Authentication tab with OAuth 2.0 / OIDC selected.
If you select OAuth 2.0 / OIDC, you must provide the following settings:
For a visual overview of how these components work together, see OpenID Connect & OAuth2 Integration – Diagrams and Configuration.
OAuth General settings
In the General settings section, configure the core OAuth identity provider connection.
Tip
Using Azure AD (Entra ID)? See the complete step-by-step guide: Register Nodinite Applications in Azure AD (Entra ID) with OpenID for all values referenced below.
Example of the OAuth General settings section.
General.1 – Authentication Method
Mandatory. Default: OAuth
Select OAuth to enable OpenID Connect / OAuth 2.0 authentication.
General.2 – Discovery URL (.well-known)
Mandatory. Default: https://idp/.../.well-known/openid-configuration
The URL of the OpenID Connect discovery document provided by your identity provider. This document contains metadata about the identity provider, including endpoints, supported scopes, and other configuration details.
For Azure AD (Entra ID): https://login.microsoftonline.com/<tenant-id>/v2.0/.well-known/openid-configuration
General.3 – Default Services Account Name
Mandatory.
Enter the Default Services Account Name. You can override this in the Advanced tab.
General.4 – Installation Client ID
Mandatory.
The Application (client) ID for your installation/daemon client. This client authenticates without user interaction for automated installations, updates, and maintenance tasks.
For Azure AD (Entra ID): Application (client) ID from your NodiniteInstallationClient app registration. See Register Azure AD Apps section 3.1.
General.5 – Installation Client Scopes
Mandatory.
One or more scopes that define the permissions granted to the installation client. Press Enter after each scope to add it.
For Azure AD (Entra ID): api://<webApi-client-id>/.default — See Register Azure AD Apps section 3.2.
General.6 – Installation Client Claims
Mandatory.
Claims to include in tokens requested with the installation client credentials. At least one claim is required when using OAuth 2.0 mode. Enter a KEY and VALUE pair.
For Azure AD (Entra ID): KEY: http://schemas.microsoft.com/ws/2008/06/identity/claims/role, VALUE: AppRole_WebApi_all — See Register Azure AD Apps section 1.3.1.
OAuth Web Client settings
In the Web Client settings section, configure the interactive user-facing authentication.
Example of the OAuth Web Client settings section.
WebClient.1 – Require HTTPS Metadata
Default: Unchecked
When enabled, the application only accepts metadata from the discovery URL if it is served over HTTPS. This ensures metadata is transmitted securely.
For Azure AD (Entra ID): Leave unchecked for production. See Register Azure AD Apps for details.
WebClient.2 – Client ID
Mandatory. Default: nodinite-%ENVIRONMENTNAME%-webclient
The client identifier registered with your identity provider for the Web Client application.
For Azure AD (Entra ID): Application (client) ID from your webClient app registration. See Register Azure AD Apps section 2.1.
WebClient.3 – Callback Path
Default: /signin-oidc
The path where the identity provider redirects users after authentication. This must match the redirect URI registered with your identity provider.
WebClient.4 – Signed-Out Callback Path
Default: /signout-callback-oidc
The path where the identity provider redirects users after they have signed out. This should match the post-logout redirect URI registered with your identity provider.
WebClient.5 – Signed-Out Redirect URI
Mandatory. Default: https://nodinite.local:41000/
The URI where users are redirected after signing out. Must be a valid URI registered with your identity provider.
WebClient.6 – Access Denied Path
Default: /
The path where users are redirected if they are denied access to a resource. Can be a custom error page or a specific route in your application.
WebClient.7 – Scopes
Default: openid, profile, email, offline_access
The scopes the application requests from the identity provider. Press Enter after each scope to add it.
For Azure AD (Entra ID): You must also add your custom API scope in the format api://<webApi-client-id>/nodinite_webapi_all. See Register Azure AD Apps section 1.2.
WebClient.8 – Nodinite Claims
Mandatory.
Specify at least one Nodinite claim to ensure secure access when using OAuth 2.0 mode. Enter a KEY and VALUE pair. Claims prevent user lockout and define how the application identifies users and environments.
For Azure AD (Entra ID) — two supported approaches:
- Groups claim — KEY:
groups, VALUE: Azure AD group Object ID. See Register Azure AD Apps section 1.5. - App Roles claim — KEY:
http://schemas.microsoft.com/ws/2008/06/identity/claims/role, VALUE: comma-separated role values such asNodinite.Admin,Nodinite.User. See Register Azure AD Apps sections 1.3.2 and 1.5.
OAuth Web API settings
In the Web API settings section, configure the audience validation for the Nodinite Web API.
Example of the OAuth Web API settings section.
WebAPI.1 – Audiences
Default: nodinite-%ENVIRONMENTNAME%-webapi
A list of valid audiences that the Nodinite Web API will accept. Press Enter after each value to add it.
For Azure AD (Entra ID): Use the webApi Application (client) ID from Register Azure AD Apps section 1.1.
OAuth Log API settings
In the Log API settings section, configure optional token validation for the Nodinite Log API.
Example of the OAuth Log API settings section.
LogAPI.1 – Enable Authentication
Default: Unchecked
When checked, the Log API validates OAuth 2.0 bearer tokens on all incoming requests. Enable this to require callers to present a valid token.
LogAPI.2 – Audiences
Default: nodinite-%ENVIRONMENTNAME%-logapi
A list of valid audiences that the Nodinite Log API will accept. Press Enter after each value to add it. Leave empty if Enable Authentication is unchecked.
OpenID Connect & OAuth2 Integration – Diagrams and Configuration
Below are diagrams to help administrators of the Identity Provider (IDP) understand how Nodinite interacts with OpenID Connect and OAuth2, and what is required for proper configuration in the Nodinite Portal.
1. Authentication Flow Overview
This diagram shows the basic OpenID Connect authentication flow between the user, Nodinite Web Client, and the Identity Provider. The IDP must be configured to recognize Nodinite as a client and provide the necessary claims and scopes.
2. Required IDP Configuration for Nodinite
Administrators must register Nodinite applications in the IDP, configure redirect URIs, assign required scopes (e.g., openid, profile, email, offline_access), and ensure claims (such as tenant/environment context) are provided. Client secrets or certificates may be required for secure communication.
3. Claims and Scopes Mapping
The IDP must provide the requested scopes and claims to Nodinite. These are mapped in the Nodinite portal fields for each client (Web Client, Web API, Log API).
Understanding Token Lifecycle and Caching
Important
Token Caching and Policy Changes
Nodinite caches authentication tokens from your Identity Provider to improve performance. Administrators must understand token caching when working with Claims, Policies, and Roles.
How Token Caching Works
When a user authenticates:
- User logs in → Nodinite redirects to your Identity Provider (IDP)
- IDP authenticates → Returns ID token and access token with claims
- Nodinite caches token → Token stored in server memory and browser session
- Token lifetime → Typically 1 hour (configured by your IDP's token expiration policy)
- Token expires → User must re-authenticate to get new token with updated claims
Critical Implications
IDP Changes Don't Take Immediate Effect
If you modify claims in your Identity Provider (Azure AD, Okta, etc.):
Scenario: You add a new claim "Department=IT" to a user in Azure AD
Timeline:
T+0 min: Change made in Azure AD
T+0 min: User already has cached token (without Department claim)
T+5 min: User logs out and logs back in
T+5 min: Still uses cached session token (no new authentication)
T+60 min: Token expires
T+61 min: User logs in again - NEW token includes Department=IT ✓
Key points:
- Cached tokens persist for their full lifetime (typically 1 hour)
- Logging out and back in may not force re-authentication (session cookie persists)
- Browser cache clearing does not affect server-side token cache
- IDP changes only apply when a new token is issued
Impact on Policy Changes
This is especially dangerous when modifying Policies:
Danger scenario:
1. Administrator adds new Claim to existing Policy (requires Department=IT)
2. Policy now blocks all users without Department=IT claim
3. Administrator realizes mistake and updates IDP to send Department=IT
4. Users still locked out for 1+ hours (cached tokens don't have the claim)
5. Even logout/login may not help (session token cached)
Recovery options:
- ✅ Wait for token expiration - Typically 1 hour, safest option
- ✅ Force re-authentication - Clear server-side session cache (requires server restart or cache flush)
- ✅ Database fix - Remove problematic Claim from Policy directly in database
- ❌ Logout/login - May not work (session token cached)
- ❌ Browser cache - Doesn't affect server-side token cache
Best Practices for Administrators
- Test in non-production first — never test claim or policy changes with production admin accounts
- Document current IDP claims — know exactly what claims are provided before changing anything
- Back up the database — ability to rollback Policy changes if needed
- Notify users — changes take up to 1 hour to propagate due to token caching
- Schedule during low-usage windows — minimise impact
- Create new Policies instead of modifying existing ones
- Never modify the Administrators Policy without a tested backup plan
- Wait for token expiration before troubleshooting — allow 1+ hours
- Test with a fresh login — use incognito/private browsing to force new authentication
Token Configuration in Identity Providers
Azure AD (Entra ID)
Default token lifetimes:
- Access tokens: 1 hour (not configurable in most tenants)
- Refresh tokens: 90 days (configurable)
To view token lifetime: Azure Portal → App Registrations → Your app → Token configuration.
Troubleshooting Token Issues
Problem: User still locked out after IDP fix
- Logout completely from Nodinite
- Close all browser windows
- Open incognito/private browsing window and navigate to Nodinite
- Login with fresh authentication
If still locked out: token may still be cached server-side. Verify the IDP change was saved, check Policy configuration in the database, or restart the Nodinite Web Client service to clear server cache.
Problem: Policy change not affecting users
Diagnosis:
# Verify the Policy was saved correctly
# Check :Nodinite: database:
SELECT PolicyId, PolicyName, Claims
FROM NodiniteConfiguration.dbo.Policies
WHERE PolicyName = 'YourPolicyName'
- If Policy shows correct Claims but users still have old permissions: Token caching
- If Policy shows old Claims: Changes weren't saved
Emergency Access Recovery
If administrators are locked out:
-- Emergency: Temporarily remove problematic Claim from Policy
-- Connect to NodiniteConfiguration database
USE NodiniteConfiguration;
GO
-- Find the Policy
SELECT PolicyId, PolicyName, Claims
FROM dbo.Policies
WHERE PolicyName = 'Administrators';
GO
-- Backup before changing
SELECT * INTO dbo.Policies_BACKUP_20260123
FROM dbo.Policies
WHERE PolicyName = 'Administrators';
GO
-- Update Policy to remove problematic Claim
-- (This requires JSON manipulation - consult with :Nodinite: support)
Warning
Direct database changes bypass validation. Only perform emergency database fixes if:
- All administrators are locked out
- Token expiration wait (1+ hours) is not acceptable
- You have database backup
- You have consulted Nodinite support documentation
Related Topics
- What is a Policy? - Understanding Policy AND logic and Claim requirements
- Add or manage Policy - Policy management best practices
- What is a Claim? - Claim fundamentals and IDP integration
- Register Azure AD Apps - Configuring token lifetime and claims in Azure AD
Next Step
Install Nodinite v7
Updating Nodinite v7
Managing the Web API - Learn how to call the Web API with OAuth 2.0 authentication
Register Nodinite Applications in Azure AD (Entra ID) with OpenID
Related Topics
Uninstall Nodinite v7
Managing the Web API - Code samples for PowerShell, C#, Java, and Node.js with OAuth 2.0
Email Alarm Plugin - Cannot be used with OpenID Connect; remove from Monitor Views before migrating
E-mail with options - Recommended replacement alarm plugin for OpenID Connect environments