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 (Install Nodinite v7 - OpenID). For Windows authentication mode, use Users and Windows AD Groups instead.

[!IMPORTANT] Policy Configuration Dangers

• Adding Claims to an existing Policy can lock you out. Claims in a Policy use AND logic; a Claim your Identity Provider (IDP) doesn't send means no user, admins included, matches the Policy.
• Empty Policies grant universal access. A Policy with no Claims is satisfied by every authenticated user; assigned to "Administrators", everyone becomes admin. Nodinite 7.2.0+ prevents saving policies without claims.

Never add Claims without verifying them in your IDP, never test with your only admin account, and never assign an empty Policy to a 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, and whose permission sets (Log Views, Monitor Views, Repository Model, C4 Diagram Sets) decide what users see

The 'Country Administrator' Policy groups three Claims; the Roles card on the right assigns it to Roles.

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

Green: Claims and the users who carry them; blue: Policies; yellow: Roles. The example shows two Claims grouped into one Policy assigned to one Role.

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

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

This Policy combines regional and permission-level Claims.

Policy Management

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

The Policies menu item in the Administration sidebar.

Available Operations

• Add new Policy - Create Policies
• Edit Policy - Modify Name, Description, Claims, or Roles
• Delete Policy - Remove Policies (can be restored)
• Restore Policy - Recover deleted Policies (Include deleted)
• 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:

• General information - Name (required, unique) and Description
• Claims card - three tabs: New creates a Claim ("Add and Use" adds it in one step), All lists every Claim with checkboxes, Selected shows the Claims in this Policy with warning badges for deleted ones
• Roles card - checkboxes that assign the Policy to Roles

The All tab of the Claims card; checked Claims are part of the Policy.

The step-by-step procedure is in Add or manage Policy.

Policies vs. Users/Groups

OIDC/OAuth 2.0 Mode (Policies)

How Policies Work

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

Advantages of Policies

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

When to Use Policies

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

Windows Authentication Mode (Users/Groups)

How Users and Groups Work

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

Advantages of Users and Groups

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

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/Groups) or OIDC/OAuth 2.0 (Claims/Policies), chosen in the Auth step at installation. To switch, see Migrate Authentication Method.

Policy Assignment to Roles

Once created, Policies are assigned to Roles, in the Roles card of the Policy (Add or manage Policy). The Role's Policies card (Add or manage Role) lists the assigned Policies but doesn't change them.

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 on a Role, with the count of assigned Policies in the header.

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

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, with one value per key (see The Conflicting Claims Problem).

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

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

Important

CRITICAL: Modifying Policies Can Lock Out All Users (Including Admins)

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 (Microsoft Entra ID, Okta, etc.) with exact key/value match (Entra ID Token Claims Validation)
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 don't take effect until the token expires; logout/login and clearing the browser cache don't help (server-side cache), so recovering immediately needs database-level access. 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

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.

Yellow: the Role (OR between its Policies); blue: the Policies; teal boxes: the Claims of each Policy, in green, joined by AND.

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

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: Nordic Administrator

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

Important

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 ✗
  

Conflicting Claims 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 but Redundant: Same Key, Same Value

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

More end-to-end examples are in Claims and Policies - 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

One value per key, so development and test get separate Policies (OR logic on the Role):

Policy: "Development Environment"
Claims: environment=development

Policy: "Test Environment"
Claims: environment=test

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

Troubleshooting

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

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.

Steps to Clean Up Deleted Claims

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: Check the Policy's Roles card and make sure the Role is checked and the Policy saved. Verify that the Policy isn't deleted, then refresh the page.

Cannot Save Policy Without Claims (7.2.0+)

Issue: Error when trying to save a Policy without Claims (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" tab to create and add Claims ("Add and Use")
4. Save the Policy (will succeed once Claims are added)

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, and review changes in Log Audits.

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, All, Selected
• Always provide a Description for clarity

Next Steps

• 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 and Policies - Common Scenarios - Implementation examples

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
• Add or manage Role - See the Policies assigned to a Role

Configuration

• Access Management - Authorization overview
• Install Nodinite v7 - OpenID - Configure OIDC/OAuth 2.0
• Install Nodinite v7 - OpenID - EntraID - Azure AD setup
• Entra ID Token Claims Validation - Check the claims in the token

Windows Mode Alternative

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