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.

Example of the Authentication tab with OAuth 2.0 / OIDC selected.

If you select OAuth 2.0 / OIDC, you must provide the following settings:

• General settings
• Web Client settings
• Web API settings
• Log API settings

OAuth General settings

In the General settings section, you must provide the following information:

Tip

Using Azure AD (Entra ID)? See the complete step-by-step guide: Register Nodinite Applications in Azure AD (Entra ID) with OpenID. That guide provides detailed instructions for creating the three required app registrations (webApi, webClient, NodiniteInstallationClient) and capturing all the values needed for these fields.

Example of the OAuth General settings section.

OAuth Web Client settings

In the Web Client settings section, you must provide the following information:

Example of the OAuth Web Client settings section.

OAuth Web API settings

In the Web API settings section, you must provide the following information:

• Audiences - A list of valid audiences that the Nodinite Web API will accept. This should include the client IDs of any applications that will be accessing the Web API. Example: nodinite-%ENVIRONMENTNAME%-webapi.

Example of the OAuth Web API settings section.

OAuth Log API settings

In the Log API settings section, you must provide the following information:

• Audiences - A list of valid audiences that the Nodinite Log API will accept. This should include the client IDs of any applications that will be accessing the Nodinite Log API. Example: nodinite-%ENVIRONMENTNAME%-logapi.

Example of the OAuth Log API settings section.

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:

1. User logs in → Nodinite redirects to your Identity Provider (IDP)
2. IDP authenticates → Returns ID token and access token with claims
3. Nodinite caches token → Token stored in server memory and browser session
4. Token lifetime → Typically 1 hour (configured by your IDP's token expiration policy)
5. 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

Before Making Changes

1. Test in non-production environment first
2. Document current IDP claims - Know exactly what claims are currently provided
3. Create test accounts - Never test with production admin accounts
4. Have database backup - Ability to rollback Policy changes if needed

During Deployment

1. Notify users - Inform users they may need to wait up to 1 hour for changes to take effect
2. Schedule during low-usage windows - Minimize impact
3. Create new Policies - Instead of modifying existing Policies
4. Never modify Administrators Policy - Without tested backup plan

After Changes

1. Wait for token expiration - Allow 1+ hours before troubleshooting
2. Test with fresh login - Use incognito/private browsing to force new authentication
3. Monitor access logs - Verify users can authenticate after token refresh
4. Plan for token lifetime - Understand changes won't be instant

Token Configuration in Identity Providers

Azure AD (Entra ID)

Default token lifetimes:

• Access tokens: 1 hour (not configurable in most tenants)
• ID tokens: 1 hour (not configurable in most tenants)
• Refresh tokens: 90 days (configurable)

To view token lifetime:

1. Azure Portal → App Registrations → Your app → Token configuration
2. Note: Microsoft has deprecated custom token lifetime policies for most tenants

Other Identity Providers

Consult your IDP documentation:

• Okta: Access token lifetime configurable per authorization server (default 1 hour)
• Auth0: Token lifetime configurable in application settings (default 10 hours for access tokens)
• Google: Access tokens expire after 1 hour (fixed)

Troubleshooting Token Issues

Problem: User still locked out after IDP fix

Diagnosis:

# Check if issue is token caching
# Have user try these steps:

1. Logout completely from Nodinite
2. Close all browser windows
3. Open incognito/private browsing window
4. Navigate to Nodinite URL
5. Login with fresh authentication

If still locked out:

• Token may still be cached server-side
• Verify IDP change was actually saved
• Check Policy configuration in database
• Consider restarting 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