What is a Claim?

Unlock flexible, cross-platform authorization in Nodinite v7 by understanding Claims. This page explains how Claims provide the foundation for modern authorization when using OIDC/OAuth 2.0 authentication mode.

• ✅ Platform-independent authorization model
• ✅ Flexible key/value pairs for any permission structure
• ✅ Integration with external identity providers
• ✅ Foundation for Policy-based access control

Note

Claims are only available when Nodinite is configured for OIDC/OAuth 2.0 authentication mode (Install Nodinite v7 - OpenID). For Windows authentication mode, use Users and Windows AD Groups instead.

Get started now: Add or manage Claim user guide.

What is a Claim?

A Claim in Nodinite is a key/value pair that represents a specific permission, attribute, or characteristic used for authorization. Claims are the fundamental building blocks of the OIDC/OAuth 2.0 authorization model in Access Management.

Example Claims

The Claims management page in the Nodinite Web Client, where the 'Used In' column shows the Policy that uses each Claim.

Authorization Flow with Claims

Understanding how Claims fit into the authorization model:

1. Claims - Individual key/value pairs (e.g., department=finance)
2. Policies - Groups of related Claims (e.g., "Finance Access Policy"); a user must match all Claims in a Policy
3. Roles - Assigned Policies to grant permissions (e.g., "Finance User" role)
4. Users - Authenticated via identity provider, receive Claims in their token
5. Authorization - Nodinite matches user Claims with Policy requirements

Blue: the user signing in; yellow: the external identity provider; green: the Nodinite matching steps that end in granted access.

What a Role then grants is set in its permission sets: Log Views, Monitor Views, Repository Model, and C4 Diagram Sets.

Key Characteristics

Unique Key/Value Combinations

The combination of Key and Value must be unique across all Claims:

• ✅ Allowed: department=finance and department=hr (different values)
• ✅ Allowed: access_level=admin and region=admin (different keys)
• ❌ Not allowed: Two Claims with department=finance

Case Sensitivity

Claims are case-sensitive:

• Department=Finance ≠ department=finance
• ROLE=Admin ≠ role=admin

Tip

Use the exact spelling your identity provider puts in the token. For your own Claims, use consistent lowercase naming conventions for Keys to avoid confusion.

Source of Claims

Claims can originate from:

1. Identity Provider - Claims provided by your OIDC provider (Microsoft Entra ID, Okta, etc.)
2. Nodinite Configuration - Claims you define directly in Nodinite (in the Claims Overview, or in the Nodinite Claims block of the Portal Auth step at installation)
3. Hybrid - Combination of both sources

Claim Management

You can manage Nodinite Claims from the Administration section in the Nodinite Web Client (Claims Overview):

The Claims menu item in the Administration sidebar.

Available Operations

• Add new Claim - Create Claims inline
• Edit Claim - Modify Key, Value, or Description
• Delete Claim - Remove Claims (can be restored)
• Restore Claim - Recover deleted Claims (Include deleted)
• Filter Claims - Search by Key, Value, or Description
• View Usage - See which Policies use each Claim

Claims vs. Users/Groups

OIDC/OAuth 2.0 Mode (Claims)

Advantages of Claims

• Platform-independent (works with any identity provider)
• Flexible key/value structure
• Cloud-native and modern
• Supports external identity providers

When to Use Claims

• Cloud-based deployments
• Multi-platform environments
• Integration with Microsoft Entra ID, Okta, Auth0, etc.
• Need modern authentication protocols

Windows Authentication Mode (Users/Groups)

Advantages of Users and Groups

• Direct Active Directory integration
• Familiar Windows security model
• No additional configuration needed

When to Use Users and Groups

• On-premises deployments
• All users in Windows domain
• Traditional Windows-integrated security

Important

You cannot mix modes. Nodinite uses either Windows authentication (Users/Windows AD Groups) or OIDC/OAuth 2.0 (Claims/Policies), chosen in the Auth step at installation. To switch, see Migrate Authentication Method.

Best Practices

Naming Conventions

Use clear, consistent naming:

✅ Good Examples:
   department=finance
   access_level=admin
   region=europe
   environment=production

❌ Poor Examples:
   Dept=Fin
   LVL=1
   EU=yes

Descriptive Documentation

Always provide a Description for each Claim:

• Explains the purpose of the Claim
• Helps other administrators understand usage
• Documents business logic

Example: A Documented Claim

• Key: department
• Value: finance
• Description: "Member of the Finance Department - grants access to financial integrations and reporting"

Logical Grouping

Plan Claims that will be grouped into Policies. Use one value per key in each Policy; see The Conflicting Claims Problem.

Finance Access Policy

• department=finance
• access_level=readonly
• region=europe

Finance Admin Policy

• department=finance
• access_level=admin
• region=all

Review Before Deletion

Before deleting a Claim:

1. Check the "Used In" column - shows which Policies reference this Claim
2. Consider the impact on existing Policies
3. Deleted Claims remain visible in Policies (marked as deleted)
4. Can be restored if needed

Common Scenarios

More end-to-end examples are in Claims and Policies - Common Scenarios.

Department-Based Access

Claim 1: department=finance
Claim 2: department=operations
Claim 3: department=hr

Policy "Finance Access":
  * Contains: department=finance

Policy "Operations Access":
  * Contains: department=operations

Multi-Level Permissions

Claim 1: access_level=readonly
Claim 2: access_level=editor
Claim 3: access_level=admin

Policy "Read Access":
  * Contains: access_level=readonly

Policy "Full Access":
  * Contains: access_level=admin
  * Contains: department=it

Regional Authorization

Claim 1: region=europe
Claim 2: region=americas
Claim 3: region=asia

Policy "European Integration Access":
  * Contains: region=europe
  * Contains: access_level=editor

Integration with Identity Provider

When using external identity providers, the Key and Value of a Nodinite Claim must match the claim in the token exactly. The OpenID Field Mapping Quick Reference maps the installer fields to your identity provider.

Azure AD (Entra ID)

Azure AD includes claims in the JWT access token automatically. The token key name you must use in Nodinite depends on how you have configured Azure AD — App Roles or Security Groups. These are two different approaches and the token key names differ between them.

Tip

App Roles are the recommended approach for Nodinite. They produce compact, readable claim values and avoid the token-size issues that occur when users belong to many Security Groups. See Register Nodinite Applications in Azure AD for how to create the App Roles.

Approach 1: App Roles (Recommended)

When a user is assigned an App Role in Azure AD (e.g., Nodinite.Admin), Azure AD adds a roles claim to the token:

{
  "roles": ["Nodinite.Admin"]
}

To map this to Nodinite, create a Claim with:

The Key is always roles (lowercase, exactly as it appears in the token). The Value is the App Role value you defined when creating the App Role in the Azure AD App Registration.

Approach 2: Security Groups

When you configure Azure AD to include group membership in the token (optional token claim), Azure AD adds a groups claim containing the Group's Object ID (a GUID):

{
  "groups": ["a1b2c3d4-0000-0000-0000-111122223333"]
}

To map this to Nodinite, create a Claim with:

Important

The Value must be the Group Object ID (GUID), not the Group display name. Copy the Object ID from Microsoft Entra ID → Groups → [your group] → Overview.

End-to-End Example: App Roles → Claims → Policies → Roles

This table shows the complete chain from Azure AD to Nodinite access control:

For fine-grained access (e.g., Finance vs HR), keep the Azure AD App Roles coarse (doorman) and use additional Nodinite Claims to represent business-domain membership:

A user satisfies the Finance Full Access Policy only when their token contains both claims — they must be a Nodinite.User AND a member of the Finance group. This is the AND logic that Policies enforce.

See Register Nodinite Applications in Azure AD for how to create the App Roles, and What is a Policy? for how AND logic works in policies. If users don't get the expected access, see Entra ID Token Claims Validation.

Other OIDC Providers

Configure claim mapping in your identity provider:

• Okta custom claims
• Auth0 user metadata
• Custom OIDC provider attributes

The principle is the same — check what key name the provider uses in the JWT token, then create a Nodinite Claim with that exact key and the expected value.

Troubleshooting

More answers are in the Access Management Troubleshooting guide and in Troubleshooting OAuth 2.0 Validation Failures.

Cannot Create Duplicate Claim

Issue: Error when creating a Claim with an existing Key/Value combination

Solution: This Key/Value combination already exists. Either:

• Use the existing Claim in your Policy
• Choose a different Key or Value
• Check if the Claim was deleted (enable the "Include deleted" filter)

Claim Not Appearing for Users

Issue: User doesn't have expected permissions despite Claim configuration

What to Check

1. Is the Claim included in a Policy?
2. Is the Policy assigned to a Role?
3. Does the user match all Claims in that Policy?
4. Does the user's identity provider provide this Claim (Entra ID Token Claims Validation)?
5. Is the Claim key/value exact match (case-sensitive)?

Deleted Claim Still Visible in Policy

Issue: Deleted Claim appears in Policies with warning badge

This is expected behavior - Deleted Claims remain referenced in Policies to maintain audit trail.

How to Resolve

1. Edit the Policy to remove the deleted Claim
2. Add a replacement Claim if needed
3. Or restore the deleted Claim if still required

Security Considerations

Principle of Least Privilege

Create specific Claims for granular permissions:

✅ Specific:
   department=finance
   access_level=readonly
   view=invoices

❌ Too broad:
   access=all
   permission=everything

Regular Audits

• Review Claims periodically
• Remove unused Claims
• Update descriptions
• Verify Policy assignments
• Review changes in Log Audits

Claim Validation

When users authenticate:

• Nodinite validates Claim keys and values
• Case-sensitive matching
• Exact match required
• No partial matching

Quick Facts

• Claims are key/value pairs used for authorization
• Available only in OIDC/OAuth 2.0 mode
• Key/Value combination must be unique
• Claims are case-sensitive
• Claims are grouped into Policies
• Policies are assigned to Roles
• Can originate from identity provider or be defined in Nodinite
• Deleted Claims can be restored
• Always provide a Description for clarity

Next Steps

• Add or manage Claim
• What is a Policy?
• What is a Role?
• Install Nodinite v7 - OpenID Connect

Related Topics

Authorization Components

• Claims Overview - Manage all Claims
• Policies - Group Claims into Policies
• Policies Overview - Manage all Policies
• Roles - Assign Policies to Roles
• Roles Overview - Manage all Roles
• Claims and Policies - Common Scenarios - Implementation examples

Configuration

• Install Nodinite v7 - OpenID - Configure OIDC/OAuth 2.0
• Install Nodinite v7 - OpenID - EntraID - Azure AD setup
• OpenID Field Mapping Quick Reference - Map installer fields to your identity provider
• Auth step in the Portal - Authentication mode and Nodinite Claims
• Entra ID Token Claims Validation - Check the claims in the token
• Access Management - Overview of authorization

Windows Mode Alternative

• Users - Windows authentication mode
• Windows AD Groups - Windows authentication mode
• Migrate Authentication Method - Switch authentication mode