What is a Policy?

Master flexible authorization in Nodinite v7 by understanding Policies. This page explains how Policies group Claims together and provide the link between individual permissions and Roles.

✅ Group related Claims for easier management
✅ Reusable permission sets across multiple Roles
✅ Flexible authorization for complex scenarios
✅ Foundation for OIDC/OAuth 2.0 access control

Note

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

Important

Policy Configuration Dangers

Danger 1: Adding Claims to Existing Policies Can Lock You Out

Claims in a Policy have AND logic - users must match ALL Claims. Adding a Claim to an existing Policy:

• Makes the Policy MORE restrictive (harder to satisfy)
• Must EXACTLY match what your Identity Provider (IDP) provides
• Can lock out ALL users including admins if the Claim doesn't exist in your IDP

Danger 2: Empty Policies Grant Universal Access

A Policy with NO Claims is satisfied by EVERY authenticated user:

• If assigned to "Administrators" role → Everyone becomes admin!
• If assigned to "FinanceAccess" role → Everyone sees finance data!
• This is a critical security vulnerability
• Nodinite 7.2.0+ prevents saving policies without claims

Never:

• Add Claims to existing Policies without verifying they exist in your IDP
• Test Policy changes with your only admin account
• Create or save a Policy without at least one Claim
• Assign an empty Policy to any Role

See Understanding Claim Logic in Policies for critical details.

Get started now: Add or manage Policy user guide.

A Policy in Nodinite is a named collection of Claims that can be assigned to one or more Roles. Policies provide a way to group related permissions and attributes together for easier management and reusability.

Think of it this way:

• Claims = Individual permissions (key/value pairs)
• Policies = Groups of related Claims
• Roles = Job functions that receive Policies

Example of a Policy showing grouped Claims in the Nodinite Web Client.

Authorization Flow with Policies

Understanding how Policies fit into the authorization model:

1. Claims - Individual key/value pairs (e.g., department=finance, access_level=admin)
2. Policies - Groups of Claims (e.g., "Finance Admin Policy" contains both Claims above)
3. Roles - Assigned Policies to grant permissions (e.g., "Finance Manager" role)
4. Users - Authenticated via identity provider, receive Claims
5. Authorization - Nodinite matches user Claims with Policy requirements in assigned Roles

Key Characteristics

Named Collections

Each Policy has:

• Name (Required) - Unique identifier for the Policy
• Description (Optional) - Explains the Policy's purpose
• Claims - One or more Claims grouped together

Reusability

Policies can be assigned to multiple Roles:

• Create once, use many times
• Consistent permissions across Roles
• Easier maintenance and updates

Flexibility

Policies support complex authorization scenarios:

• Combine Claims from different categories
• Mix department, access level, and regional Claims
• Create fine-grained or broad permission sets

Policy Structure

Warning

A Policy MUST contain at least one Claim (Nodinite 7.2.0+ enforces this).

Empty policies grant universal access - see Empty Policy Detection for details.

Example: Finance Admin Policy

Name: Finance Admin Policy
Description: Full administrative access to finance integrations and reporting

Claims in this Policy:

This Policy groups three Claims together, creating a complete permission set for finance administrators.

Example: Regional Read-Only Policy

Name: Europe Read-Only Access
Description: Read-only access to European integration monitoring

Claims in this Policy:

This Policy combines regional and permission-level Claims.

Policy Management

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

Example of the Policies menu item in the Administration sidebar.

Available Operations

• Add new Policy - Create Policies
• Edit Policy - Modify Name, Description, or Claims
• Delete Policy - Remove Policies (can be restored)
• Restore Policy - Recover deleted Policies
• Filter Policies - Search by Name or Description
• Manage Claims - Add/remove Claims from the Policy

Policy Detail Page

When creating or editing a Policy, you work with three main sections:

1. General Information

• Name - The Policy name (required, must be unique)
• Description - Optional description of the Policy's purpose

2. Claims Management Tabs

The Policy detail page includes three tabs for managing Claims:

New/Edit Tab:

• Create new Claims or edit existing ones
• "Add and Use" option to create and assign in one step
• Convenient for creating Claims specific to this Policy

All Tab:

• Browse all available Claims in the system
• Use checkboxes to add Claims to this Policy
• Search and filter to find specific Claims
• Shows deleted Claims when "Include Deleted" is enabled

Selected Tab:

• View all Claims currently assigned to this Policy
• Use checkboxes to remove Claims from this Policy
• Shows warning badges for deleted Claims
• Search within selected Claims

The three tabs for managing Claims within a Policy.

Policies vs. Users/Groups

OIDC/OAuth 2.0 Mode (Policies)

How it works:

• Define Claims (key/value pairs)
• Group Claims into Policies
• Assign Policies to Roles
• Users receive access based on their Claims matching Policy requirements

Advantages:

• Platform-independent
• Flexible and extensible
• Works with any identity provider
• Modern cloud-native approach

Use when:

• Cloud-based deployments
• Multi-platform environments
• External identity providers (Azure AD, Okta, etc.)
• Need modern authentication protocols

Windows Authentication Mode (Users/Groups)

How it works:

• Assign Users directly to Roles
• Or assign Windows AD Groups to Roles
• Windows handles authentication and authorization

Advantages:

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

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.

Policy Assignment to Roles

Once created, Policies are assigned to Roles:

In the Role Detail Page

When viewing or editing a Role in OIDC/OAuth 2.0 mode, you'll see a Policies card showing:

The Policies card in a Role showing assigned Policies.

• Policy count - Number of Policies assigned
• Policy names - Clickable links to Policy details
• Policy descriptions - Quick reference
• Warning badges - For deleted Policies

Note

In the current version, Policy assignment to Roles is configured through backend or API. The Policies card in Roles is read-only for viewing.

Best Practices

Naming Conventions

Use clear, descriptive names that explain the Policy's purpose:

✅ Good Names:
   Finance Admin Policy
   Europe Read-Only Access
   Operations Full Access
   Developer Test Environment

❌ Poor Names:
   Policy1
   Fin_Pol
   ADMIN
   Test

Descriptive Documentation

Always provide a comprehensive Description:

✅ Good Description:
   "Full administrative access to finance integrations, including 
    invoice processing, payment systems, and financial reporting. 
    Grants read/write/delete permissions in production environment."

❌ Poor Description:
   "Finance policy"
   "Admin access"
   ""

Logical Grouping

Group related Claims together:

Department-Based Policy:

Policy: "Finance Department Access"
Claims:
  - department=finance
  - environment=production
  - access_level=editor

Functional Policy:

Policy: "Read-Only Monitoring"
Claims:
  - access_level=readonly
  - feature=monitoring
  - feature=logging

Regional Policy:

Policy: "European Operations"
Claims:
  - region=europe
  - department=operations
  - access_level=admin

Reusability

Design Policies to be reusable across multiple Roles:

Policy: "Production Environment Access"
  - environment=production
  - compliance=validated

Assigned to Roles:
  - Finance Manager (with other finance Policies)
  - Operations Lead (with other operations Policies)
  - Senior Developer (with other developer Policies)

Review Deleted Claims

If a Policy contains deleted Claims: Edit → Remove deleted Claims from "Selected" tab → Add replacements or restore.

Understanding Claim Logic in Policies

[!DANGER] CRITICAL: Modifying Policies Can Lock Out All Users (Including Admins)

Why Policy modification is dangerous:

1. AND Logic: ALL Claims in a Policy must match. Adding one Claim makes access MORE restrictive
2. IDP Dependency: Claims must exist in your Identity Provider (Azure AD, Okta, etc.) with exact key/value match
3. Immediate Effect: Changes apply instantly to all users assigned to Roles using this Policy
4. Admin Lockout Risk: If you modify the Administrators Policy incorrectly, you lock yourself out
5. Token Caching: Even if you fix the IDP, cached tokens can persist for 1+ hours - lockout continues!

Real-world disaster scenario:

You have Policy "Administrators" with:
  - Group=Admin

You add "MFAVerified=true" thinking it adds security:
  - Group=Admin (AND)
  - MFAVerified=true (AND)

Problem: Your IDP doesn't send "MFAVerified" claim
Result: NO users match (Group=Admin AND MFAVerified=true)
Impact: Complete admin lockout - requires database fix! ❌

You fix the IDP to send MFAVerified claim:
  - Tokens are cached in Nodinite for 1+ hours
  - Logout/login doesn't help (session token cached)
  - Clearing browser cache doesn't help (server-side token cache)
  - You're still locked out until token expires! ❌

Understanding Token Caching:

Nodinite caches tokens from your IDP (typically 1 hour):

• IDP changes won't take effect until token expires
• Logout/login and browser cache clearing don't help (server-side cache)
• You're locked out for the full token lifetime
• Need database-level access to recover immediately

See Install Nodinite v7 - OpenID for complete token lifecycle details.

Safe practices:

• ✅ Create NEW Policies instead of modifying existing ones
• ✅ Document all Claims your IDP provides before creating Policies
• ✅ Test with non-admin test accounts first
• ✅ Have emergency database access to rollback if needed
• ✅ Wait for token expiration (1+ hours) after IDP changes before troubleshooting
• ✅ Never modify the built-in "Administrators" Policy without a tested backup plan
• ❌ Never add Claims "just to see what happens"
• ❌ Never test Policy changes using your only admin account
• ❌ Don't assume logging out will immediately refresh your token

AND Logic Within a Policy

Critical Rule: All Claims within a single Policy use AND logic. Users must match ALL Claims in the Policy to satisfy it.

Key Insights:

• OR between Policies - User needs to match ANY ONE of the Policies assigned to the Role
• AND within Policies - User must match ALL Claims within a single Policy
• If user satisfies AdminInSweden Policy (has Country=Sweden AND Group=Admin), they get Admin role ✓
• If user satisfies AdminInNorway Policy (has Country=Norway AND Group=Admin), they get Admin role ✓
• If user satisfies AdminInDenmark Policy (has Group=AdminInDenmark), they get Admin role ✓

Example:

Policy: "AdminInSweden"
Claims:
  - Country=Sweden (AND)
  - Group=Admin   (AND)

Result: Users must have BOTH Claims to match this Policy:

• ✅ User has Country=Sweden AND Group=Admin → Access granted
• ❌ User has only Country=Sweden → Access denied
• ❌ User has only Group=Admin → Access denied

OR Logic Between Policies

To achieve OR logic, create separate Policies and assign both to the same Role:

Example:

Policy: "AdminInDenmark"
Claims:
  - AdminInDenmark=true

Policy: "AdminInSweden"
Claims:
  - AdminInSweden=true

Policy: "AdminInNorway"
Claims:
  - AdminInNorway=true

Role: "Nordic Administrator"
Policies:
  - AdminInDenmark (OR)
  - AdminInSweden (OR)
  - AdminInNorway (OR)

Result: Users with ANY of these Claims get the "Nordic Administrator" role:

• ✅ User has AdminInDenmark=true → Access granted
• ✅ User has AdminInSweden=true → Access granted
• ✅ User has AdminInNorway=true → Access granted
• ✅ User has all three Claims → Access granted

The Conflicting Claims Problem

Important

Never add multiple Claims with the same Key but different Values to a single Policy. This creates an impossible-to-satisfy condition.

❌ Invalid Policy Configuration:

Policy: "Nordic Admin" (INVALID!)
Claims:
  - Country=Denmark (AND)
  - Country=Sweden  (AND)
  - Country=Norway  (AND)

Why this fails:

1. Policy requires ALL Claims (AND logic)
2. User can only have one value per claim key from their identity provider
3. User cannot have Country=Denmark AND Country=Sweden simultaneously
4. No user can ever satisfy this Policy ❌
5. Everyone is blocked from access ❌

Visual Representation:

User's Claims from IDP:
  AdminInDenmark: true
  Group: Admin

Policy "Conflicting Example" requires:
  AdminInDenmark: true  (AND)  ← User has this ✓
  AdminInDenmark: false (AND)  ← User doesn't have this ✗

Result: Policy NOT satisfied → Access DENIED

Correct Pattern: Separate Policies for OR Logic

✅ Valid Configuration:

Policy: "DenmarkAccess"
Claims:
  - Country=Denmark

Policy: "SwedenAccess"
Claims:
  - Country=Sweden

Policy: "NorwayAccess"
Claims:
  - Country=Norway

Role: "Nordic Administrator"
Policies:
  - DenmarkAccess
  - SwedenAccess
  - NorwayAccess

Result: Users from any Nordic country get access:

• User with Country=Denmark → Matches "DenmarkAccess" Policy ✓
• User with Country=Sweden → Matches "SwedenAccess" Policy ✓
• User with Country=Norway → Matches "NorwayAccess" Policy ✓

Validation Rules

Nodinite enforces these validation rules when managing Policies:

Empty Policy Detection

[!DANGER] Empty Policies = Universal Access (Blocked in 7.2.0+)

A Policy with zero Claims grants access to ALL authenticated users.

Enforced validation (7.2.0+):

Nodinite prevents saving a Policy without at least one Claim:

❌ Cannot save Policy

A Policy must contain at least one Claim.

An empty Policy is satisfied by ALL authenticated users, meaning:
• Anyone who logs in will match this Policy
• If assigned to a Role, EVERYONE gets that Role  
• This creates a critical security vulnerability

Solutions:
• Add at least one Claim to this Policy
• Delete this Policy if not needed

Why this validation is critical:

• ❌ Without validation: Admin accidentally saves empty "Administrators" policy → everyone becomes admin
• ✅ With validation (7.2.0+): System blocks the save, forces admin to add explicit Claims
• ✅ Security: Ensures all Policies have explicit, documented access requirements
• ✅ Clarity: Empty policy intent is ambiguous; explicit Claims are clear

What would happen without this protection:

Policy: "ProductionAccess" (no claims) - NOT ALLOWED IN 7.2.0+
User authentication: Success
Policy evaluation:
  - No claims to check
  - Policy satisfied: ✓ (no conditions to fail)
  - User matches policy
  
Result: Every user would match this Policy ❌

Conflicting Claims Detection

When adding a Claim to a Policy, the system checks:

• ✅ Allowed: Different claim keys

  Country=Sweden (AND) Group=Admin ✓
  

• ❌ Not Allowed: Same key, different values

  Country=Sweden (AND) Country=Norway ✗
  

Error Message:

Cannot add claim 'Country=Norway' to Policy

The Policy already contains a claim with key 'Country':
  Current value: Sweden
  Value you're trying to add: Norway

A user cannot have two different values for the same claim key, 
so this Policy would be impossible to satisfy.

Solutions:
• Remove 'Country=Sweden' first, then add 'Country=Norway'
• Create a separate Policy for 'Country=Norway'
• Assign both Policies to the same Role for OR logic

Complex Scenarios

✅ Valid - Multiple Keys, Different Values:

Policy: "Finance Manager Sweden"
Claims:
  - Department=Finance     ← Different key
  - Country=Sweden         ← Different key
  - AccessLevel=Admin      ← Different key
  - Environment=Production ← Different key

All different keys → Valid ✓

❌ Invalid - Same Key, Different Values:

Policy: "Multi-Environment" (INVALID!)
Claims:
  - Environment=Production (AND)
  - Environment=Test       (AND)

Same key with different values → Invalid ✗

✅ Valid - Same Key, Same Value (Redundant but Harmless):

Policy: "Redundant Example"
Claims:
  - Country=Sweden
  - Country=Sweden  ← Duplicate, but same value

Same key with same value → Valid but redundant (system may deduplicate)

Common Scenarios

Scenario 1: Department-Based Access Control

Policy: "Finance Department Access"
Claims: department=finance, access_level=editor

Policy: "Finance Admin Access"  
Claims: department=finance, access_level=admin

Policy: "Operations Department Access"
Claims: department=operations, access_level=editor

Scenario 2: Multi-Permission Policies

Policy: "European Finance Manager"
Claims:
  - department=finance, region=europe
  - access_level=admin, environment=production, feature=reporting

Scenario 3: Environment Separation

Policy: "Development Environment"
Claims: environment=development, environment=test

Policy: "Production Environment"
Claims: environment=production, compliance=validated

Integration with Claims

Creating Claims within Policies:

1. "New/Edit" tab → Enter Key, Value, Description → "Add and Use" creates and adds to Policy

Adding Existing Claims:

1. "All" tab → Browse/search → Check boxes → Added to "Selected" tab

Removing Claims:

1. "Selected" tab → Uncheck boxes → "Save"

Troubleshooting

Cannot Create Policy - "Name already exists"

Issue: Error when creating a Policy

Solution: Policy names must be unique. Either:

• Choose a different name
• Check if the Policy was deleted (restore it instead)
• Edit the existing Policy if it serves the same purpose

Policy Shows Deleted Claims

Issue: Policy contains Claims with warning badges

Explanation: The Claims have been deleted but remain referenced in the Policy for audit purposes.

Solution:

1. Edit the Policy
2. Go to the "Selected" tab
3. Uncheck the deleted Claims
4. Add replacement Claims from the "All" tab
5. Or restore the deleted Claims if still needed

Cannot See Policy in Role

Issue: Created Policy not visible in Role editor

Solution: Policy assignment via backend/API only. Contact admin or refresh page to clear cache.

Cannot Save Policy Without Claims (7.2.0+)

Issue: Error when trying to save a Policy without Claims

Error Message:

❌ Cannot save Policy

A Policy must contain at least one Claim.

Solution: This validation prevents security vulnerabilities. Add at least one Claim:

1. Stay on the Policy detail page
2. Use the "All" tab to add existing Claims
3. Or use the "New/Edit" tab to create and add Claims
4. Save the Policy (will succeed once Claims are added)

Why this error occurs:

An empty Policy would be satisfied by ALL authenticated users, granting the assigned Role to everyone. This validation (added in 7.2.0) prevents this security risk.

Security Considerations

Principle of Least Privilege - Create specific Policies, not overly broad ones.

Regular Audits - Review quarterly: remove unused, update descriptions, verify Claims, check Role assignments.

Claim Validation - Ensure Claims are: valid (not deleted), relevant, documented, following naming conventions.

Quick Facts

• Policies are named collections of Claims
• Available only in OIDC/OAuth 2.0 mode
• Policy names must be unique
• Policies can be assigned to multiple Roles
• Policies must contain at least one Claim (enforced in 7.2.0+)
• Deleted Policies can be restored
• Three tabs for managing Claims: New/Edit, All, Selected
• Always provide a Description for clarity
• Reusable across multiple Roles

Next Step

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

Related Topics

Policies:

Policies Overview - Manage all Policies
Add or manage Policy - Policy management guide

Claims:

What is a Claim? - Understanding Claims
Claims Overview - Manage all Claims
Add or manage Claim - Claim management guide

Roles:

What is a Role? - Understanding Roles
Roles Overview - Manage all Roles

Configuration:

Access Management - Authorization overview
Install Nodinite v7 - OpenID - Configure OIDC/OAuth 2.0
Install Nodinite v7 - OpenID - EntraID - Azure AD setup

Windows Mode Alternative:

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