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

Example Claims:

Example of the Claims management page showing various claims in the Nodinite Web Client.

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")
3. Roles - Assigned Policies to grant permissions (e.g., "Finance User" role)
4. Users - Authenticated via identity provider, receive Claims
5. Authorization - Nodinite matches user Claims with Policy requirements

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 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 (Azure AD, Okta, etc.)
2. Nodinite Configuration - Claims you define directly in Nodinite
3. Hybrid - Combination of both sources

Claim Management

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

Example of 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
• 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:

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

Use when:

• Cloud-based deployments
• Multi-platform environments
• Integration with Azure AD, Okta, Auth0, etc.
• Need modern authentication protocols

Windows Authentication Mode (Users/Groups)

Advantages:

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

Use when:

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

Important

You cannot mix modes. Nodinite uses either Windows authentication (Users/Groups) or OIDC/OAuth 2.0 (Claims/Policies), configured during installation.

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:

• 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:

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

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:

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.

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

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 "Show Deleted" filter)

Claim Not Appearing for Users

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

Check:

1. Is the Claim included in a Policy?
2. Is the Policy assigned to a Role?
3. Is the user assigned to that Role?
4. Does the user's identity provider provide this Claim?
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.

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

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 Step

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

Configuration:

Install Nodinite v7 - OpenID - Configure OIDC/OAuth 2.0
Install Nodinite v7 - OpenID - EntraID - Azure AD setup
Access Management - Overview of authorization

Windows Mode Alternative:

Users - Windows authentication mode
Windows AD Groups - Windows authentication mode