Install Nodinite v7 - OpenID Connect (OIDC) and OAuth 2.0

Use OpenID Connect (OIDC) and OAuth 2.0 when your users should sign in through an external identity provider, such as Microsoft Entra ID, with its MFA and Conditional Access policies, instead of Windows Authentication. You choose the mode for the whole Environment in the Portal Step 2: Auth; the Steps pages are the master for the install flow. This page is the field-by-field reference for the OAuth2 part of that step.

• Register the applications in your identity provider first. For Microsoft Entra ID, follow Register Nodinite Applications in Azure AD (Entra ID) with OpenID.
• Map each captured value to its Portal field with the OpenID Field Mapping Quick Reference.
• OAuth2 requires HTTPS: configure the TLS certificate in Step 4: Servers → Core host Configuration.
• For the supported flows and standards alignment (Authorization Code + PKCE, no implicit grant, no ROPC, OAuth 2.1 draft, RFC 9700), see the OAuth Security and Compliance Reference.

Warning

Switching an existing Environment from Windows Authentication? The Email Alarm Plugin can't be used with OpenID Connect, because it reads e-mail addresses from Active Directory Users. Replace it with E-mail with options in every Monitor View before you switch, or alarms fail silently. Follow Migrate Authentication Method for the full sequence.

Tip

Blocked by Error [10.3] or [10.4] during the CLI pre-flight check? See Troubleshooting OAuth 2.0 Validation Failures.

Understanding the OpenID Connect Architecture

In OAuth2 mode, every Nodinite Core Service that accepts calls validates an OAuth 2.0 bearer token, and each client gets its token from the identity provider. Each Portal field below configures one of these relationships.

Purple nodes are the three required app registrations, teal nodes the optional ones, and blue nodes the Nodinite Web Client, Web API, Log API, and MCP Server Core Services. Solid arrows are token-carrying calls; dotted arrows show which Portal field takes the app registration's values. The Log API registration is described in Protect the Log API with OAuth 2.0 and Entra ID, and the MCP API registration in MCP Endpoint External Access.

User Sign-in Flow

The Web Client signs the user in, and the Web API validates the token and grants access by matching its claims to Nodinite Claims, Policies, and Roles. A user whose token carries no matching claim is denied, even when the sign-in itself succeeds.

Portal Sections and Who Uses Them

The client secrets aren't entered in the Portal; see Client Secrets. The Service account defaults section of the same step applies to both auth modes; see General.3.

OAuth2 settings

In the Portal's Auth step, select OAuth2 under Auth Mode. The OAuth2 settings section then holds the Discovery URL, the Installation Client group, and the Web Client group, in that order.

Tip

Using Microsoft Entra ID? Each field below names the value from Register Nodinite Applications in Azure AD (Entra ID) with OpenID.

The OAuth2 settings section in the current Portal, with the Installation Client and Web Client groups and the default Web Client values.

General.1 – Authentication Method

Mandatory.

Select OAuth2 in the Auth Mode section of the Auth step. The Portal then shows the OAuth2 settings section. The choice applies to the whole Environment; to change it later, see Migrate Authentication Method.

General.2 – Discovery URL

Mandatory. No default.

The OpenID Connect discovery document (.well-known/openid-configuration) of your identity provider. It holds the identity provider's metadata: endpoints, supported scopes, and signing keys. Enter it first, so the metadata resolves before you continue with the client values. The servers must reach the identity provider over outbound HTTPS; see Network and Firewall Overview.

For Azure AD (Entra ID): https://login.microsoftonline.com/<tenant-id>/v2.0/.well-known/openid-configuration, with the Directory (tenant) ID GUID.

General.3 – Service Account Defaults

Mandatory.

The former Default Services Account Name field is no longer part of the OAuth2 settings. The account the Windows services run as is set in the separate Service account defaults section of the Auth step, above Secret Management Certificate Configuration. That section is the same for Windows auth and OAuth2 (domain or workgroup, Domain Name, Account Name, gMSA), and you can override the account per service on the Servers step. See Service Account Defaults and gMSA accounts. On Windows Server, the account also needs the Logon as a Service right.

Example of the Auth step in OAuth2 mode, where Service account defaults and Secret Management precede the OAuth2 settings section.

General.4 – Installation Client: Client ID

Mandatory.

The Application (client) ID of the installation client in your identity provider; for Microsoft Entra ID this is a GUID. The installer CLI authenticates as this client, without user interaction, for installations, updates, and maintenance tasks.

For Azure AD (Entra ID): Application (client) ID of the NodiniteInstallationClient app registration, see section 3.1.

General.5 – Installation Client Scopes

Mandatory.

The scopes requested by the installation client. Enter each scope separately, click Add, and keep the values in the order you want them displayed.

For Azure AD (Entra ID): api://<webApi-client-id>/.default, see section 3.2.

General.6 – Installation Client Claims

Mandatory.

KEY=VALUE claims that the installation client's token must carry; the CLI pre-flight check validates them (Error [10.4] when they're missing). Click + Add, enter the KEY and VALUE of each pair, and keep the entries in the order you want them displayed.

For Azure AD (Entra ID): KEY: http://schemas.microsoft.com/ws/2008/06/identity/claims/role, VALUE: AppRole_WebApi_all, see section 1.3.1.

OAuth2 settings: Web Client

The Web Client group of the OAuth2 settings section configures the interactive sign-in to the Web Client.

Example of the Web Client group, with Require HTTPS Metadata at the top right and the default callback paths and scopes.

WebClient.1 – Require HTTPS Metadata

Required: Checked

OAuth2 requires HTTPS. This setting makes Nodinite fetch the discovery document over HTTPS only; keep it checked. The installer rejects non-HTTPS discovery URLs, so the identity provider must publish its discovery document over HTTPS. The checkbox is in the top-right corner of the Web Client group.

For Azure AD (Entra ID): The Entra ID discovery URL is always HTTPS; keep the checkbox checked.

WebClient.2 – Client ID

Mandatory. Default: webclient

The Application (client) ID of the Web Client in your identity provider. For Microsoft Entra ID this is a GUID, so replace the default value.

For Azure AD (Entra ID): Application (client) ID of the webClient app registration, see section 2.1.

WebClient.3 – Callback Path

Default: /signin-oidc

The path the identity provider redirects back to after sign-in. Together with the Web Client's host name and port (set in Step 4: Servers), it must exactly match the redirect URI registered with your identity provider, for example https://nodinite.contoso.com:<port>/signin-oidc.

WebClient.4 – Signed-Out Callback Path

Default: /signout-callback-oidc

The path the identity provider returns to after sign-out. It should match the post-logout redirect URI registered with your identity provider.

WebClient.5 – Signed-Out Redirect URI

No default.

Where the user lands after sign-out completes, for example /.

WebClient.6 – Access Denied Path

Default: /

The page shown when a signed-in user is denied access. It can be a custom error page or a specific route in the application.

WebClient.7 – Scopes

Default scopes: openid, profile, email, offline_access

The OAuth2 scopes the Web Client requests at sign-in. Enter each additional scope separately, click Add, and keep the values in the order shown here; remove a value with its ×.

For Azure AD (Entra ID): Also add the delegated Web API scope api://<webApi-client-id>/nodinite_webapi_all, see section 1.2.

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

The audiences (aud claim values) the Nodinite Web API accepts. Enter each audience separately, click Add, and keep the values in the order you want them displayed. Scripts and systems that call the Web API request tokens for this audience; see Call the Web API with OAuth 2.0 Client Credentials.

For Azure AD (Entra ID): The webApi Application (client) ID from section 1.1. Version 2 tokens (section 1.6) carry the plain client ID as audience.

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, so every logging client must present a valid token.

LogAPI.2 – Audiences

Default: nodinite-%ENVIRONMENTNAME%-logapi

The audiences the Log API accepts. Enter each audience separately, click Add, and keep the values in the order you want them displayed. Leave empty if Enable Authentication is unchecked.

For Azure AD (Entra ID): The Log API has its own app registration (logApi, Application ID URI api://<logapi-client-id>, requestedAccessTokenVersion 2). Enter its plain Application (client) ID here, not the api:// URI; clients request tokens with the scope api://<logapi-client-id>/.default. See Protect the Log API with OAuth 2.0 and Entra ID.

MCP Server settings

In the MCP Server settings section, configure the token values for the MCP Server, the Core Service behind the MCP Endpoint, and for the Web Client AI Assistant that calls it.

Example of the MCP Server settings, where you set the audiences the MCP Server accepts and the scope the Web Client requests.

MCPServer.1 – Audiences

Default: api://mcp

The audiences the MCP Server accepts in OAuth 2.0 tokens. Enter each audience separately, click Add, and keep the values in the order you want them displayed.

For Azure AD (Entra ID): Replace the default with the values of the MCP API app registration: both its Application (client) ID and api://<mcp-api-app-id>. See MCP Endpoint External Access.

MCPServer.2 – Web Client MCP Server Scope

Default: api://mcp/.default

The OAuth 2.0 scope the Web Client requests when it calls the MCP Server. Enter each scope separately, click Add, and keep the values in the order shown here.

For Azure AD (Entra ID): api://<mcp-api-app-id>/.default. The webClient app registration also needs admin-consented delegated permissions for the MCP API, or the AI Assistant shows no tools.

Nodinite Claims

The final OAuth block on the Auth step is Nodinite Claims, after the MCP Server settings. It's a separate block, not part of the Web Client group.

WebClient.8 – Nodinite Claims

Mandatory.

Specify at least one Nodinite claim, so that someone can sign in after the installation. Click Add, then enter the KEY and VALUE of each pair, one pair per value; KEY and VALUE are case-sensitive. The installer stores these pairs as Claims; afterwards you grant access in the Web Client by combining Claims into Policies and assigning the Policies to Roles.

Warning

Make sure the token of the first administrator carries at least one of these claims. Otherwise the sign-in succeeds at the identity provider, but Nodinite denies access and you're locked out.

Supported Approaches for Azure AD (Entra ID)

• App Roles claim (recommended) — KEY: http://schemas.microsoft.com/ws/2008/06/identity/claims/role, VALUE: an app role value such as Nodinite.Admin. See sections 1.3.2 and 1.5.
• Groups claim — KEY: groups, VALUE: an Entra ID group Object ID (GUID), which requires the groups claim in the token configuration. See Claims and Entra ID.

Client Secrets

The Portal doesn't store the client secrets of the webClient and NodiniteInstallationClient app registrations. When you run the generated package in Step 7, the CLI prompts for them, or you pass them with --oauth2-webclient-secret and --oauth2-agentinstall-secret. Keep the secrets in an approved secret-management solution, and plan their rotation before they expire; an expired installation client secret fails the next update with Error [10.3].

Operational Security Notes

• 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.
• Use support channels for emergency access scenarios instead of direct database edits.

Next Steps

• Register Nodinite Applications in Azure AD (Entra ID) with OpenID
• OpenID Field Mapping Quick Reference
• Step 2: Auth
• Install Nodinite v7
• Updating Nodinite v7

Related Topics

• OAuth Security and Compliance Reference
• Migrate Authentication Method
• Troubleshooting OAuth 2.0 Validation Failures
• OAuth 2.0 Troubleshooting
• Call the Web API with OAuth 2.0 Client Credentials
• Protect the Log API with OAuth 2.0 and Entra ID
• MCP Endpoint External Access
• What is a Claim?
• What is a Policy?
• E-mail with options
• Uninstall Nodinite v7