- 12 minutes to read

Claims and Policies - Troubleshooting Guide

Comprehensive troubleshooting guide for Claims and Policies in Nodinite v7 using OIDC/OAuth 2.0 authentication.

✅ Common issues and solutions
✅ Error message explanations
✅ Diagnostic steps
✅ Best practices for prevention

Note

This guide is for OIDC/OAuth 2.0 mode only. For Windows authentication troubleshooting, see Users and Windows AD Groups.

Claims Issues

Cannot Create Claim - "Key/Value Already Exists"

Error Message: "A claim with this Key/Value combination already exists."

Cause: The exact Key/Value combination is already in use (or was deleted and still exists).

Solutions:

  1. Check active Claims:

    • Navigate to Administration → Claims
    • Search for the Key and Value
    • If found, use the existing Claim instead

  2. Check deleted Claims:

    • Enable "Include Deleted" filter
    • Look for the Claim marked as deleted
    • Restore it instead of creating new

  3. Choose different Key or Value:

    • If you need a different Claim, modify either the Key or Value
    • Example: Instead of department=finance, use team=finance-operations

Prevention:

  • Use consistent naming conventions
  • Document your Claims structure
  • Check existing Claims before creating new ones

Claim Not Appearing in Policy Editor

Issue: Created a Claim but don't see it in the Policy editor's "All" tab.

Diagnostic Steps:

  1. Verify Claim was saved:

    • Go to Administration → Claims
    • Search for your Claim
    • Check "Created" timestamp

  2. Refresh the page:

    • Close the Policy editor
    • Refresh browser (F5 or Ctrl+R)
    • Reopen the Policy

  3. Check if Claim was deleted:

    • In the Policy editor, enable "Include Deleted" on All tab
    • Look for the Claim with a "Deleted" badge

  4. Clear browser cache:

    • Clear browser cache and cookies
    • Log out and log back in
    • Try again

Solutions:

  • If Claim exists but still not visible, contact support
  • If Claim was deleted, restore it
  • If Claim wasn't saved, recreate it

Cannot Delete Claim Used in Policies

Issue: Want to delete a Claim but it's used in multiple Policies.

Explanation: This is expected behavior. You can delete Claims even when they're in use.

What Happens:

  1. Claim is marked as deleted
  2. Claim remains visible in Policies (with warning badge)
  3. Audit trail is preserved
  4. Claim can be restored

Solutions:

Option 1: Delete anyway (recommended for deprecation)

1. Delete the Claim
2. It will show with warning badge in Policies
3. Edit each Policy to remove the deleted Claim
4. Add replacement Claim if needed

Option 2: Replace before deleting

1. Create new replacement Claim
2. Edit each Policy using the old Claim
3. Add new Claim to Policy
4. Remove old Claim from Policy
5. Delete old Claim once no longer used

Prevention:

  • Check "Used In" column before deleting
  • Plan replacement Claims
  • Communicate with team before deletion

User Has Claim But No Access

Issue: User authenticates with correct Claims from identity provider but doesn't get expected access.

Diagnostic Steps:

  1. Verify Claim exists in Nodinite:

    • Go to Administration → Claims
    • Search for the exact Key and Value
    • Claim must match exactly (case-sensitive)

  2. Check if Claim is in a Policy:

    • Go to Administration → Claims
    • Find the Claim
    • Check "Used In" column for Policies

  3. Verify Policy is assigned to Role:

    • Go to Administration → Roles
    • Open the Role the user should have
    • Check Policies card for the required Policy

  4. Verify user has the correct Claim from identity provider:

    • Check user's authentication token
    • Verify Claim Key and Value match exactly
    • Check for typos or case differences

Common Causes:

Problem Solution
Case mismatch Department=Finance ≠ department=finance - Fix casing
Claim not in Nodinite Create the Claim in Nodinite
Claim not in Policy Add Claim to appropriate Policy
Policy not in Role Assign Policy to Role
User doesn't have Claim Check identity provider configuration

Prevention:

  • Use lowercase for all Claims
  • Document exact Claim values
  • Test with pilot users before rollout

Policy Issues

Cannot Create Policy - "Name Already Exists"

Error Message: "A policy with this name already exists."

Solutions:

  1. Choose a unique name:

    • Policy names must be unique
    • Try a more descriptive name
    • Example: Instead of "Finance Policy", use "Finance Admin Policy" or "Finance User Policy"

  2. Check for deleted Policies:

    • Enable "Include Deleted" filter
    • Look for a deleted Policy with that name
    • Restore it instead of creating new

  3. Rename or edit existing Policy:

    • If the existing Policy serves the same purpose, edit it instead
    • Add/remove Claims as needed

Prevention:

  • Use descriptive, unique names
  • Follow naming convention: [Department] [Access Level] Policy
  • Document your Policy structure

Policy Shows Deleted Claims

Issue: Policy displays Claims with warning badges.

Explanation: This is expected behavior when Claims in the Policy have been deleted.

Impact:

  • Policy still functions
  • Users with deleted Claims won't match the Policy
  • Warning badge indicates maintenance needed

Solutions:

  1. Remove deleted Claims:

    1. Edit the Policy
2. Go to "Selected" tab
3. Uncheck the deleted Claims (marked with warning)
4. Save the Policy

  2. Replace with active Claims:

    1. Edit the Policy
2. Remove deleted Claims from "Selected" tab
3. Go to "All" tab
4. Add replacement Claims
5. Save the Policy

  3. Restore deleted Claims:

    1. Go to Administration → Claims
2. Enable "Include Deleted"
3. Find and restore the deleted Claims
4. Warning badges disappear from Policy

Prevention:

  • Review Claims before deleting
  • Plan replacement Claims
  • Audit Policies quarterly

Cannot See Policy in Role

Issue: Created a Policy but don't see it in Role editor.

Explanation: In the current version, Policy assignment to Roles is managed through backend configuration or API.

What You'll See:

  • Role detail page shows a Policies card (read-only)
  • Displays Policies already assigned to the Role
  • Cannot add/remove Policies through the UI

Solutions:

  1. Contact system administrator:

    • Policy assignment is backend operation
    • Administrator can assign Policies to Roles
    • Provide Policy name and Role name

  2. Use API:

    • If you have API access, assign Policy programmatically
    • See Web API documentation

  3. Verify Policy exists:

    • Ensure Policy was saved successfully
    • Check it's not deleted
    • Verify it has at least one Claim

Prevention:

  • Plan Policy assignments during initial setup
  • Document which Policies should be assigned to which Roles
  • Coordinate with system administrator

Policy Contains No Claims

Issue: Created a Policy but forgot to add Claims.

Impact:

  • Policy exists but does nothing
  • Users won't match an empty Policy
  • No access granted

Solutions:

  1. Add Claims to the Policy:

    1. Edit the Policy
2. Go to "All" tab
3. Check Claims to add
4. Or use "New/Edit" tab to create new Claims
5. Save the Policy

  2. Delete if no longer needed:

    1. If Policy was created by mistake
2. Delete the Policy
3. Can be restored later if needed

Prevention:

  • Always add Claims before saving new Policy
  • Use "New/Edit" tab with "Add and Use" button for quick Claim creation
  • Review Policy after creation

Authentication and Authorization Issues

User Cannot Log In - "Access Denied"

Issue: User can authenticate with identity provider but gets "Access Denied" in Nodinite.

Diagnostic Steps:

  1. Verify user has required Claims:

    • Check user's authentication token
    • Verify Claims are being sent by identity provider
    • Check Claim format matches Nodinite configuration

  2. Check if Claims exist in Nodinite:

    • Go to Administration → Claims
    • Verify all user Claims exist
    • Check case sensitivity

  3. Verify Claims are in Policies:

    • Check if user's Claims are part of any Policy
    • User needs at least one matching Policy

  4. Check Policy assignment to Roles:

  5. Verify Nodinite configuration:

    • Check OpenID configuration in Nodinite Portal
    • Verify Discovery URL is correct
    • Check Client ID and Scopes

Common Causes:

Problem Solution
No Claims from IDP Fix identity provider configuration
Claims don't exist in Nodinite Create matching Claims
Claims not in any Policy Add Claims to Policy
Policy not assigned to Role Assign Policy to Role
OpenID misconfiguration Review Install Nodinite v7 - OpenID

User Has Wrong Permissions

Issue: User can log in but has incorrect access level (too much or too little).

Diagnostic Steps:

  1. Check user's Claims from identity provider:

    • Verify what Claims the user actually receives
    • Check authentication token or user profile

  2. Find matching Policies:

    • Go to Administration → Claims
    • For each of user's Claims, check "Used In" column
    • List all Policies user matches

  3. Check Role assignments:

    • Go to Administration → Roles
    • Check which Roles have those Policies
    • User gets permissions from all matching Roles

  4. Review permission sets:

Solutions:

Too much access:

1. Remove overly broad Claims from user (in IDP)
2. Or remove Claim from Policy
3. Or remove Policy from Role
4. Or adjust Role permission sets

Too little access:

1. Add required Claims to user (in IDP)
2. Or create Policy with user's Claims
3. Or assign Policy to Role
4. Or adjust Role permission sets

Identity Provider Integration Issues

Claims Not Appearing from Azure AD

Issue: User authenticates but Claims from Azure AD don't appear in Nodinite.

Diagnostic Steps:

  1. Check OpenID configuration:

    • Go to Nodinite Portal → Environment → Authentication
    • Verify Discovery URL: https://login.microsoftonline.com/{tenant}/v2.0/.well-known/openid-configuration
    • Check Client ID matches Azure AD app registration

  2. Verify Azure AD app registration:

    • Check app registration has correct scopes
    • Verify API permissions are granted
    • Check token configuration includes required claims

  3. Check claim mapping:

    • In Azure AD, verify custom claims are configured
    • Check group claims are enabled if using groups
    • Verify claim names match Nodinite configuration

  4. Test authentication token:

    • Use jwt.ms to decode token
    • Verify Claims appear in token
    • Check Claim names and values

Solutions:

  1. Fix Azure AD app registration:

  2. Update Nodinite configuration:

    • Update Claims mapping in Nodinite Portal
    • Verify expected Claim keys
    • Test with pilot user

Prevention:

Claims Have Wrong Values

Issue: Claims appear but with unexpected values.

Examples:

  • Expecting department=finance but getting department=Finance
  • Expecting role=admin but getting http://schemas.microsoft.com/ws/2008/06/identity/claims/role=admin

Causes:

  1. Case mismatch:

    • Identity provider sends Finance (capitalized)
    • Nodinite expects finance (lowercase)

  2. Claim namespace:

    • Azure AD includes full namespace in claim key
    • Nodinite configured with short key name

  3. Claim transformation:

    • Identity provider transforms claim values
    • Different format than expected

Solutions:

Option 1: Update Nodinite Claims (easier)

1. Create Claims matching actual IDP values
2. Example: department=Finance (capitalized)
3. Adjust Policies to use new Claims

Option 2: Configure IDP claim transformation

1. In Azure AD/IDP, configure claim transformation
2. Map claims to expected format
3. Example: Transform "Finance" → "finance"

Option 3: Use claim mapping in Nodinite

1. In Nodinite Portal, configure claim mapping
2. Map IDP claim key to Nodinite claim key
3. Example: Map full namespace to short name

Prevention:

  • Use lowercase for all claim values
  • Document exact claim format from IDP
  • Test claim values before creating Policies

Performance and UI Issues

Claims/Policies Page Loads Slowly

Issue: Claims or Policies management page takes long time to load.

Causes:

  • Large number of Claims (1000+)
  • Large number of Policies
  • Many Policies with many Claims each

Solutions:

  1. Use search filter:

    • Filter Claims/Policies by text
    • Reduces displayed items
    • Faster rendering

  2. Clean up unused items:

    • Delete unused Claims
    • Delete unused Policies
    • Keep only active, necessary items

  3. Optimize browser:

    • Clear browser cache
    • Disable browser extensions
    • Use modern browser (Chrome, Edge, Firefox)

  4. Review Claims structure:

    • Consider consolidating similar Claims
    • Reduce total number if possible

Prevention:

  • Regular cleanup of unused Claims/Policies
  • Plan Claim structure before creating many
  • Archive deleted items periodically

Browser Session Expired

Issue: "Session expired" error when managing Claims/Policies.

Cause: Authentication token expired during long editing session.

Solutions:

  1. Refresh the page:

    • Press F5 or Ctrl+R
    • Re-authenticate if prompted
    • Resume work

  2. Save work frequently:

    • Don't leave edit pages open too long
    • Save Claims/Policies before taking breaks

  3. Increase session timeout:

    • Contact administrator to increase token lifetime
    • In Nodinite Portal authentication settings

Prevention:

  • Save changes frequently
  • Don't leave edit pages open for hours
  • Refresh page before starting long tasks

Best Practices for Prevention

Design Phase

  1. Plan Claims structure:

    • Document all required Claims before creating
    • Use consistent naming convention
    • Group Claims logically

  2. Design Policies:

    • Map business requirements to Policies
    • Plan for reusability
    • Keep Policies focused

  3. Test with pilot users:

    • Create test Claims and Policies
    • Test with small group first
    • Verify access before full rollout

Implementation Phase

  1. Create Claims systematically:

    • Use lowercase consistently
    • Add descriptions always
    • Document as you go

  2. Build Policies incrementally:

    • Start with simple Policies
    • Test each Policy
    • Add complexity gradually

  3. Verify at each step:

    • Check Claims appear in Policies
    • Verify Policies assigned to Roles
    • Test user access

Maintenance Phase

  1. Regular audits:

    • Review Claims quarterly
    • Check Policies for deleted Claims
    • Remove unused items

  2. Monitor access:

    • Use Log Audits to track changes
    • Review access patterns
    • Identify unused Claims/Policies

  3. Update documentation:

    • Keep Claim descriptions current
    • Document Policy purposes
    • Maintain architecture diagrams

Getting Help

Diagnostic Information to Collect

When reporting issues, include:

  1. Environment information:

    • Nodinite version
    • Authentication mode (OIDC/OAuth 2.0)
    • Identity provider (Azure AD, Okta, etc.)

  2. Claim details:

    • Claim Key and Value
    • Expected behavior
    • Actual behavior

  3. User information:

    • User's Claims from identity provider
    • Expected access
    • Actual access level

  4. Error messages:

    • Full error text
    • Browser console errors
    • Network errors (F12 → Network tab)

  5. Steps to reproduce:

    • Detailed steps
    • Expected result
    • Actual result

Support Resources

Next Step

Claims and Policies - Common Scenarios - Implementation examples
Add or manage Claim - Create Claims
Add or manage Policy - Create Policies

Claims - Understanding Claims
Policies - Understanding Policies
Roles - Understanding Roles
Access Management
Install Nodinite v7 - OpenID