Register Nodinite Applications in Azure AD (Entra ID) with OpenID

Empower your organization with secure, modern authentication and authorization using Microsoft Entra ID (Azure AD) and Nodinite. This guide registers the webApi, webClient, and NodiniteInstallationClient applications that a Nodinite v7 Environment in OAuth2 mode needs, before you fill in the Portal Step 2: Auth.

• ✅ Register the Azure AD applications for Nodinite integration
• ✅ Enable secure OpenID Connect sign-in to the Web Client
• ✅ Grant delegated and application permissions with admin consent
• ✅ Authorize users with App Roles that map to Nodinite Claims
• ✅ Capture all essential IDs and secrets for the installation

Each value you capture here goes into a field described in Install Nodinite v7 – OpenID Connect (OIDC) and OAuth 2.0; the OpenID Field Mapping Quick Reference lists them all on one page. For the supported flows and standards alignment (Authorization Code + PKCE, no implicit grant, no ROPC, exact redirect URI matching), see the OAuth Security and Compliance Reference.

Tip

Troubleshooting Installation Errors? If the CLI pre-flight check reports Error [10.3] or [10.4], see Troubleshooting OAuth 2.0 Validation Failures.

Understanding the App Registrations

The three purple app registrations are required: the webApi protects the Nodinite Web API, the webClient signs users in to the Web Client, and the NodiniteInstallationClient lets the installer CLI work unattended. The teal registrations are optional: logApi when you protect the Log API, and the MCP API when you use the MCP Endpoint with OAuth. Blue marks the users and groups you assign to app roles.

What You Will Create

App Roles keep tokens small, even for users in hundreds of groups, and work on every Entra ID tier without premium licensing.

Tip

Keep a secure note open to capture: Tenant (Directory) ID, each Application (client) ID, each Secret Value (shown only once), and the API Application ID URI.

Prerequisites

Before you begin, ensure you have:

• A Microsoft Entra ID tenant, where Nodinite users already have accounts.
• Entra ID administrator access: permissions to register applications and to grant tenant-wide admin consent.
• The Web Client URL: the host name from Step 4: Servers → Core host Configuration and the Web Client port from Core platform services, for the redirect URI.
• A secure location to store credentials, such as a password manager.

1. Create the API Application – webApi

1.1 Register the Application

1. Azure Portal: Microsoft Entra ID > App registrations > + New registration.
2. Name: webApi
3. Supported account types: Accounts in this organizational directory only (Single tenant).
4. Redirect URI: (leave blank)
5. Click Register.
6. In Overview, copy Application (client) ID and Directory (tenant) ID.

The Azure Portal displays the registered webApi application overview.

Tip

The Directory (tenant) ID goes into the Discovery URL, and the webApi Application (client) ID into the Web API Audiences.

1.2 Set Application ID URI & Add Scope

The Application ID URI uniquely identifies your API in your organization. Client applications use this URI to request tokens for your API.

1. Left menu: Expose an API.
2. If prompted, click Set for Application ID URI (accept the default api://<webApi-client-id>). Copy this value—you'll need it later.
3. Under Scopes defined by this API, click + Add a scope.
   • Scope name: nodinite_webapi_all
   • Who can consent: Admins only
   • Admin consent display name: Full access to Nodinite WebAPI
   • Admin consent description: Full access to Nodinite WebAPI
   • State: Enabled
   • Click Add scope.

You add a scope to the webApi application for delegated permissions.

Important

In the Portal: Add this scope to the Web Client Scopes as api://<webApi-client-id>/nodinite_webapi_all, for example api://d731e991-1234-5678-90ab-cdef12345678/nodinite_webapi_all.

1.3 Add App Roles (User and Application Permissions)

App Roles are the recommended approach for application authorization in Entra ID. They provide scalable, token-efficient role-based access control (RBAC) without the token size limitations of group claims.

1.3.1 Create App Role for Installation Client (Application Permission)

1. Left menu: App roles > + Create app role:
   • Display name: AppRole_WebApi_all
   • Allowed member types: Applications (this is for service-to-service authentication)
   • Value: AppRole_WebApi_all
   • Description: Application permission for Nodinite installation and background services
   • State: Enabled
2. Click Apply / Create.

You create an app role for application-to-application (service) authentication.

Tip

In the Portal: Use this value in the Installation Client Claims: KEY http://schemas.microsoft.com/ws/2008/06/identity/claims/role, VALUE AppRole_WebApi_all.

1.3.2 Create App Roles for Users (Delegated Permissions)

Create roles for different user permission levels in Nodinite. Add as many roles as needed for your organization's access control requirements.

1. Left menu: App roles > + Create app role:
   • Display name: Nodinite.Admin
   • Allowed member types: Users/Groups (this is for user authentication)
   • Value: Nodinite.Admin
   • Description: Full administrative access to all Nodinite features
   • State: Enabled
2. Click Apply / Create.
3. Repeat to create additional user roles:
   • Nodinite.User: Display name and Value Nodinite.User, Allowed member types Users/Groups, Description Standard user access to Nodinite monitoring and logging features, State Enabled.
   • Nodinite.ReadOnly (optional): Display name and Value Nodinite.ReadOnly, Allowed member types Users/Groups, Description Read-only access to Nodinite dashboards and reports, State Enabled.

You create app roles for user authorization with different permission levels.

Tip

Customize roles to match your organization's needs, for example Nodinite.Admin for IT administrators, Nodinite.User for integration developers, Nodinite.ReadOnly for business stakeholders, and Nodinite.Support for help desk users. An app role grants no Nodinite permission by itself: after installation you add it as a Nodinite Claim, combine Claims into Policies, and assign the Policies to Roles.

Important

In the Portal: Use these app role values in the Nodinite Claims block (the last OAuth block, after MCP Server): KEY http://schemas.microsoft.com/ws/2008/06/identity/claims/role, and one entry per role value, such as Nodinite.Admin. At least one of them must be in the token of the first administrator.

1.5 Assign Users and Groups to App Roles

After creating app roles, assign users or Entra ID groups to them. This determines which users can access Nodinite and which claims their tokens carry.

Warning

Assign yourself before proceeding. The account you will use to sign in to Nodinite for the first time must be assigned to the Nodinite.Admin role now, directly or through a group you're a member of. Otherwise the token has no matching claim, Nodinite denies the sign-in even though Entra ID authentication succeeds, and you're locked out with no way to recover from inside Nodinite.

Tip

Best Practice: Assign Entra ID groups to app roles instead of individual users, and manage membership in the group.

Option 1: Assign via Enterprise Applications (Recommended)

1. In Azure Portal, navigate to Microsoft Entra ID > Enterprise applications.

2. Search for and select webApi (you may need to change the filter to "All applications").

3. Left menu: Users and groups > + Add user/group.

   
   You initiate the process to add user/group assignments to app roles.

4. Click None Selected under Users and groups.

5. Select an Entra ID group (e.g., "Nodinite Admins") that contains your own account, or select your own user account directly.

   
   You search for and select users or groups to assign to the application.

6. Click Select.

7. Click None Selected under Select a role.

8. Select the Nodinite.Admin app role.

   
   You select the specific app role to assign to the selected users or groups.

9. Click Select > Assign.

10. Repeat for additional groups/users with different roles (e.g., assign "Nodinite Users" group to Nodinite.User role).

The Users and groups view shows all role assignments for the webApi application.

Option 2: Assign via App Registration (Alternative)

1. Navigate to Microsoft Entra ID > App registrations > select webApi.
2. Go to Overview and click the link under Managed application in local directory (this opens the Enterprise Application).
3. Follow steps 3-10 from Option 1 above.

Note

Role assignments appear in the user's access token as the roles claim. The token stays small because only the role values (e.g., Nodinite.Admin) are included, not all group memberships. A user without any app role assignment authenticates at Entra ID but is denied by Nodinite; there is no default access.

1.6 Set Access Token Version to 2

Nodinite validates version 2 access tokens, which carry the plain client ID as audience (aud) and the claims Nodinite reads.

1. Left menu: Manifest.
2. Locate "requestedAccessTokenVersion": 2. If missing or different, set it to 2.
3. Click Save.

You configure the manifest with requestedAccessTokenVersion set to 2.

Tip

✅ webApi configuration is complete. Its Application (client) ID is the Web API Audiences value.

1.7 MCP Server values used by the installer

The Portal Step 2: Auth has an MCP Server block, with the Portal defaults api://mcp (MCP Server Audiences) and api://mcp/.default (Web Client MCP Server Scope). With Entra ID, these values come from a separate MCP API app registration with delegated mcp:* scopes; create it as described in MCP Endpoint External Access when you plan to use the MCP Endpoint or the AI Assistant. Then enter:

• MCP Server Audiences: the MCP API Application (client) ID and api://<mcp-api-app-id>
• Web Client MCP Server Scope: api://<mcp-api-app-id>/.default

Also grant the webClient admin-consented delegated permissions for the MCP API, or the AI Assistant shows no tools. See MCP Server settings.

2. Create the Interactive Client – webClient

2.1 Register webClient

1. App registrations > + New registration.
2. Name: webClient
3. Supported account types: Single tenant.
4. Redirect URI (Platform Web): the HTTPS URL of your Nodinite Web Client, followed by /signin-oidc, for example https://nodinite.contoso.com:<port>/signin-oidc. Use the host name and Web Client port set in the Portal Step 4: Servers; OAuth2 requires HTTPS.
5. Click Register.
6. Copy the Application (client) ID. You will need this value when configuring Nodinite.

The Azure Portal displays the registered webClient application overview.

Tip

In the Portal: This is the Web Client Client ID.

2.2 Configure Authentication

The Authorization Code + PKCE flow provides superior security compared to legacy implicit grant flows.

1. Left menu: Authentication.
2. Confirm the redirect URI is listed.
3. Leave Implicit grant checkboxes unchecked (modern auth uses Authorization Code + PKCE for enhanced security).
4. Ensure Allow public client flows is No (unless specifically required for mobile/desktop scenarios).
5. Click Save if you made any changes.

You configure authentication settings for the webClient application.

Tip

In the Portal: The redirect URI path must match the Web Client Callback Path (default /signin-oidc). Keep Require HTTPS Metadata checked in the same group; the Entra ID discovery URL is always HTTPS.

2.3 Add API Permissions (Delegated)

1. Left menu: API permissions > + Add a permission.
2. Choose My APIs > select webApi.
3. Choose Delegated permissions and tick nodinite_webapi_all.
4. Click Add permissions.
5. Click Grant admin consent for [Your Tenant Name] and confirm. The status should change to Granted. This authorizes the webClient to access the webApi on behalf of your users.

You configure API permissions for delegated access to webApi.

Important

In the Portal: This delegated permission is the custom scope api://<webApi-client-id>/nodinite_webapi_all in the Web Client Scopes, next to the defaults openid, profile, email, and offline_access.

2.4 Create Client Secret (Confidential Web App)

1. Left menu: Certificates & secrets > + New client secret.
2. Add a description and expiry per policy.
3. Click Add.
4. Copy the Value immediately (you cannot view it again); store securely.

You create a client secret for the webClient application.

Warning

Store this secret value securely! Entra ID displays it only once. It isn't entered in the Portal: the CLI asks for it when you run the package in Step 7, or you pass it with --oauth2-webclient-secret. Before it expires, create a new secret and rerun the update.

3. Create the Installation / Daemon Client – NodiniteInstallationClient

3.1 Register

1. App registrations > + New registration.
2. Name: NodiniteInstallationClient
3. Supported account types: Single tenant.
4. Redirect URI: leave blank.
5. Register.
6. Copy Application (client) ID.

The Azure Portal displays the registered NodiniteInstallationClient application overview.

Tip

In the Portal: This is the Installation Client Client ID.

3.2 Add Application Permission

Application permissions enable service-to-service authentication without user interaction, for automated deployments and background tasks.

1. Left menu: API permissions > + Add a permission.
2. My APIs > select webApi.
3. Choose Application permissions (not Delegated).
4. Tick AppRole_WebApi_all.
5. Click Add permissions.
6. Click Grant admin consent and confirm. The status should change to Granted. This authorizes the installation client to act independently without requiring a signed-in user.

You configure API permissions for the NodiniteInstallationClient application.

Important

In the Portal: This application permission corresponds to two fields in the Installation Client group:

1. Installation Client Scopes: api://<webApi-client-id>/.default (the .default scope requests all application permissions granted to this client)
2. Installation Client Claims: KEY http://schemas.microsoft.com/ws/2008/06/identity/claims/role, VALUE AppRole_WebApi_all (the app role value from section 1.3.1)

3.3 Create Client Secret

1. Left menu: Certificates & secrets > + New client secret.
2. Add description + expiry.
3. Click Add and copy the Value immediately; store securely.

You create a client secret for the NodiniteInstallationClient application.

Warning

Store this secret value securely! Entra ID displays it only once. The CLI asks for it in Step 7, or you pass it with --oauth2-agentinstall-secret. An expired secret fails the next update with Error [10.3].

• ✅ NodiniteInstallationClient configuration is complete. The installer can now run unattended installations, updates, and maintenance tasks, also from CI/CD pipelines.

What You've Accomplished

You have registered the Entra ID applications that form the security foundation of your Nodinite Environment:

• Centralized identity – users sign in with their Entra ID accounts, including MFA and Conditional Access policies.
• Granular access control – delegated and application permissions give users and services only what they need.
• Scalable authorization – App Roles keep tokens small regardless of group membership and need no premium license.
• Automation – a dedicated installation client for unattended installs and updates.

Quick Reference: What Goes Where

Warning

Before you open the Portal wizard: Confirm that your account (or a group containing your account) is assigned to the Nodinite.Admin app role (§ 1.5). Without it, the installation completes but you can't sign in.

Use the OpenID Field Mapping Quick Reference to complete each installation field.

Important

Nodinite Claims — pick one approach for users:

• App Roles (KEY http://schemas.microsoft.com/ws/2008/06/identity/claims/role, VALUE a role value such as Nodinite.Admin) — recommended; token size stays small regardless of group count.
• Groups (KEY groups, VALUE an Entra ID group Object ID) — needs the groups claim in the token configuration; users in many groups may hit token size limits.

The Installation Client Claims always use the App Roles claim (AppRole_WebApi_all), whichever approach you choose for users. See What is a Claim? for the token-to-Claim mapping.

Next Steps

• Install Nodinite v7 – OpenID Connect and OAuth 2.0 – enter the captured values in the Portal
• OpenID Field Mapping Quick Reference
• Step 2: Auth
• Protect the Log API with OAuth 2.0 and Entra ID (optional)
• MCP Endpoint External Access (optional)

Related Topics

• Install Nodinite v7
• Updating Nodinite v7
• Migrate Authentication Method
• OAuth Security and Compliance Reference
• Call the Web API with OAuth 2.0 Client Credentials
• What is a Claim?
• What is a Policy?
• Troubleshooting OAuth 2.0 Validation Failures
• Fix: Token Claims Validation Failed for InstallationClient (Error 10.4)