- 8 minutes to read

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.

For security posture, standards mapping, and OAuth 2.1 draft alignment, see OAuth Security and Compliance Reference.

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. Failure to do so will result in silent alarm failures after migration.

Before migrating, you must:

Warning

Troubleshooting Installation Validation Errors? If you encounter Error [10.3] (client credentials validation) or Error [10.4] (token claims validation) during pre-flight checks, consult the comprehensive troubleshooting guide: Troubleshooting OAuth 2.0 Validation Failures. It includes root cause analysis, common mistakes, quick-reference checklists, and debugging tips.

Authentication Tab with OAuth option
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 Security and Standards Alignment

Nodinite authenticates and authorizes users with OAuth 2.0 and OpenID Connect 1.0 against Microsoft Entra ID. The implementation aligns with OAuth 2.1 draft security requirements and RFC 9700 (OAuth 2.0 Security Best Current Practice).

Requirement Nodinite
Authorization Code flow with PKCE Required
Implicit grant (response_type=token) Not used
Resource Owner Password Credentials (ROPC) Not used
Redirect URI matching Exact match required
Bearer token transmission Authorization header only
Refresh token rotation Enabled

Use the dedicated OAuth Security and Compliance Reference for the complete standards matrix and compliance context.

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.

Authentication Tab with OAuth General settings
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.

Authentication Tab with OAuth Web Client settings
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 as Nodinite.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.

Authentication Tab with OAuth Web API settings
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.

Authentication Tab with OAuth Log API settings
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

sequenceDiagram participant User participant WebClient as Nodinite Web Client participant IDP as Identity Provider User->>WebClient: Accesses application WebClient->>IDP: Redirects for authentication (OIDC) IDP->>User: Prompts for login (if not already authenticated) User->>IDP: Provides credentials IDP->>WebClient: Returns ID token and claims via redirect URI WebClient->>User: Grants access based on claims/scopes

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

graph TD subgraph IDP[Identity Provider] A[Register Nodinite Web Client] B[Register Nodinite Web API] C[Register Nodinite Log API] D[Configure Redirect URIs] E[Configure Scopes] F[Configure Claims] G[Assign Client Secrets] end A --> D A --> E A --> F A --> G B --> E B --> F B --> G C --> E C --> F C --> G style A fill:#FFD700 style B fill:#FFD700 style C fill:#FFD700 style D fill:#FFD700 style E fill:#FFD700 style F fill:#FFD700 style G fill:#FFD700

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

flowchart LR subgraph IDP S[Scopes] C[Claims] end S -->|"openid, profile, email, offline_access"| N[Nodinite Portal] C -->|"tenant, environment, roles"| N style S fill:#87CEEB style C fill:#87CEEB style N fill:#90EE90

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).

Operational Security Notes

Keep operational troubleshooting secure by sharing only what administrators need for safe configuration.

  • Validate claim and role changes in non-production first
  • Plan identity-provider authorization changes during maintenance windows
  • Use app roles for scalable authorization in larger tenants
  • Store client secrets in approved secret-management solutions
  • Use support channels for emergency access scenarios instead of direct database edits

For standards details and security rationale, see OAuth Security and Compliance Reference.

Next Step