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][Policies] 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][Policies] editor
   • Refresh browser (F5 or Ctrl+R)
   • Reopen the [Policy][Policies]

3. Check if Claim was deleted:

   • In the [Policy][Policies] 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][Policies]

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][Policies]
Policy not in Role	Assign [Policy][Policies] to [Role][Roles]
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][Policies] with that name
   • Restore it instead of creating new

3. Rename or edit existing Policy:

   • If the existing [Policy][Policies] 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][Policies] displays Claims with warning badges.

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

Impact:

• [Policy][Policies] still functions
• Users with deleted Claims won't match the [Policy][Policies]
• 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][Policies] but don't see it in [Role][Roles] editor.

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

What You'll See:

• [Role][Roles] detail page shows a Policies card (read-only)
• Displays [Policies][] already assigned to the [Role][Roles]
• 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][Policies] name and [Role][Roles] name

2. Use API:

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

3. Verify Policy exists:

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

Prevention:

• Plan [Policy][Policies] 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][Policies] but forgot to add Claims.

Impact:

• [Policy][Policies] exists but does nothing
• Users won't match an empty [Policy][Policies]
• 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][Policies]
• Use "New/Edit" tab with "Add and Use" button for quick Claim creation
• Review [Policy][Policies] after creation

---

Policy Contains Conflicting Claims (Blocks Everyone)

Issue: Created a Policy with multiple Claims that have the same key but different values, and now no users can access the system.

Symptoms:

• Users authenticate successfully but get "Access Denied"
• Policy appears valid but matches zero users
• Test users with correct departments/regions still blocked

Example of the Problem:

Policy: "Multi-Country Access"
Claims:
  * Country=Sweden (AND)
  * Country=Norway (AND)
```text
**Why This Fails:**

1. Policies use **AND** logic - users must match **ALL** Claims

2. Users can only have **one value** per claim key from their identity provider

3. A user cannot have `Country=Sweden` AND `Country=Norway` simultaneously

4. **No user can ever satisfy this Policy** → Everyone blocked ❌

**Diagnostic Steps:**

1. **Review Policy Claims:**

   ```text
   1. Go to Administration → Policies
   2. Open the suspicious Policy
   3. Go to "Selected" tab
   4. Look for Claims with the same Key but different Values

2. Check Claim Keys:

   Example - Look for conflicts like this:
   ❌ Country=Sweden
   ❌ Country=Norway      ← Same key "Country"
   ❌ Country=Denmark     ← Same key "Country"
   
   ✓ Country=Sweden
   ✓ Group=Admin         ← Different key "Group"
   ✓ AccessLevel=Editor  ← Different key "AccessLevel"
   

3. Test with User Claims:

   User's actual Claims from IDP:
     Country: Sweden
     Group: Admin
   
   Policy requires (AND logic):
     Country=Sweden ✓
     Country=Norway ✗  ← User doesn't have this
   
   Result: Policy NOT satisfied → Access DENIED
   

Solutions:

Option 1: Remove Conflicting Claims (Quick Fix)

1. Edit the Policy

2. Go to "Selected" tab

3. Keep only ONE claim per key

4. Remove the others (e.g., keep Country=Sweden, remove Norway/Denmark)

5. Save the Policy

```text
#### Option 2: Create Separate Policies for OR Logic (Recommended)

```text
1. Create individual Policies:

   Policy: "SwedenAccess"
     * Country=Sweden

   Policy: "NorwayAccess"
     * Country=Norway

   Policy: "DenmarkAccess"
     * Country=Denmark

2. Assign ALL policies to the same Role:

   Role: "Nordic Administrator"
   Policies:
     * SwedenAccess  (OR)
     * NorwayAccess  (OR)
     * DenmarkAccess (OR)

3. Result: Users from ANY Nordic country get access ✓

```text
#### Option 3: Use Wildcard or Different Claim Structure

```text
Instead of:
  Country=Sweden (AND) Country=Norway

Consider:
  Region=Nordic       ← Single claim
  
Or configure IDP to send:
  Country=Sweden
  Region=Nordic       ← Both claims, use Region in Policy
```text
**Prevention:**

* Only add Claims with **unique keys** to a Policy
* For OR logic, create **separate Policies** assigned to same Role
* Review Policy logic: AND within Policy, OR between Policies
* Test Policies with actual user Claims before rollout

**Documentation:**

See [Understanding Claim Logic in Policies][What is a Policy] for detailed explanation of AND/OR logic.

---

## 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][Policies]
   * User needs at least one matching [Policy][Policies]

4. **Check Policy assignment to Roles:**
   * Verify [Policies][] are assigned to [Roles][]
   * Check [Role][Roles] has permission to access :Nodinite:

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][Policies]|  
|Policy not assigned to Role|Assign [Policy][Policies] to [Role][Roles]|  
|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:**
   * For each [Role][Roles], check permission sets
   * Check [Log Views][], [Monitor Views][], [Repository Model][]
   * Permissions are cumulative

**Solutions:**

**Too much access:**

```text

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

```text
**Too little access:**

```text

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

```text

---

## 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](https://jwt.ms)<sup></sup> to decode token
   * Verify Claims appear in token
   * Check Claim names and values

**Solutions:**

1. **Fix Azure AD app registration:**
   * See [Install Nodinite v7 - OpenID - EntraID][]
   * Configure app roles and claims
   * Grant admin consent for permissions

2. **Update Nodinite configuration:**
   * Update Claims mapping in Nodinite Portal
   * Verify expected Claim keys
   * Test with pilot user

**Prevention:**

* Follow [Install Nodinite v7 - OpenID - EntraID][] guide exactly
* Document all custom claims
* Test with pilot users before rollout

---

### 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)

```text

1. Create Claims matching actual IDP values

2. Example: department=Finance (capitalized)

3. Adjust Policies to use new Claims

```text
#### Option 2: Configure IDP claim transformation

```text

1. In Azure AD/IDP, configure claim transformation

2. Map claims to expected format

3. Example: Transform "Finance" → "finance"

```text
#### Option 3: Use claim mapping in Nodinite

```text

1. In Nodinite Portal, configure claim mapping

2. Map IDP claim key to Nodinite claim key

3. Example: Map full namespace to short name

```text
**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

*  [Install Nodinite v7 - OpenID][] - Configuration guide
*  [Install Nodinite v7 - OpenID - EntraID][] - Azure AD setup
*  [What is a Claim?][Claims] - Claim documentation
*  [What is a Policy?][Policies] - Policy documentation
*  [What is a Role?][Roles] - Role documentation

---

##  Next Step

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

##  Related Topics

 [Claims][] - Understanding Claims  
 [Policies][] - Understanding Policies  
 [Roles][] - Understanding Roles  
 [Access Management][]  
 [Install Nodinite v7 - OpenID][]  
 [Understanding Claim Logic][What is a Policy] - AND/OR logic explained

[Access Management]:https://bitbucket.org/imdevelopers/products-documentation/src/v2/Integration%20Manager/Documentation/Administration/3.%20Access%20Management/Overview.md
[Add or manage Claim]:https://bitbucket.org/imdevelopers/products-documentation/src/v2/Integration%20Manager/Documentation/Administration/3.%20Access%20Management/4.%20Claims/Features/Add%20or%20manage%20Claim.md
[Add or manage Policy]:https://bitbucket.org/imdevelopers/products-documentation/src/v2/Integration%20Manager/Documentation/Administration/3.%20Access%20Management/5.%20Policies/Features/Add%20or%20manage%20Policy.md
[Claims and Policies - Common Scenarios]:https://bitbucket.org/imdevelopers/products-documentation/src/v2/Integration%20Manager/Documentation/Administration/3.%20Access%20Management/Getting%20Started/Common%20Scenarios.md
[Claims]:https://bitbucket.org/imdevelopers/products-documentation/src/v2/Integration%20Manager/Documentation/Administration/3.%20Access%20Management/4.%20Claims/Features/What%20is%20a%20Claim.md
[Install Nodinite v7 - OpenID - EntraID]:https://bitbucket.org/imdevelopers/products-documentation/src/v2/Integration%20Manager/Documentation/Install%20and%20Update/Getting%20started/Version%207/Install%20Nodinite%20v7%20-%20OpenID%20-%20EntraID.md
[Install Nodinite v7 - OpenID]:https://bitbucket.org/imdevelopers/products-documentation/src/v2/Integration%20Manager/Documentation/Install%20and%20Update/Getting%20started/Version%207/Install%20Nodinite%20v7%20-%20OpenID.md
[Log Audits]:https://bitbucket.org/imdevelopers/products-documentation/src/v2/Integration%20Manager/Documentation/Administration/6.%20Tools/2.%20Log%20Audit%20Search.md
[Log Views]:https://bitbucket.org/imdevelopers/products-documentation/src/v2/Integration%20Manager/Documentation/Administration/1.%20Log%20Management/1.%20Log%20Views/Features/What%20is%20a%20Log%20View.md
[Monitor Views]:https://bitbucket.org/imdevelopers/products-documentation/src/v2/Integration%20Manager/Documentation/Administration/2.%20Monitor%20Management/1.%20Monitor%20Views/Features/What%20is%20a%20Monitor%20View.md
[Policies]:https://bitbucket.org/imdevelopers/products-documentation/src/v2/Integration%20Manager/Documentation/Administration/3.%20Access%20Management/5.%20Policies/Features/What%20is%20a%20Policy.md
[Repository Model]:https://bitbucket.org/imdevelopers/products-documentation/src/v2/Integration%20Manager/Documentation/Repository%20Model/Overview.md
[Roles]:https://bitbucket.org/imdevelopers/products-documentation/src/v2/Integration%20Manager/Documentation/Administration/3.%20Access%20Management/1.%20Roles/Features/What%20is%20a%20Role.md
[Users]:https://bitbucket.org/imdevelopers/products-documentation/src/v2/Integration%20Manager/Documentation/Administration/3.%20Access%20Management/2.%20Users/Features/What%20is%20a%20User.md
[Web API]:https://bitbucket.org/imdevelopers/products-documentation/src/v2/Integration%20Manager/Documentation/Core%20Services/Web%20API/Overview.md
[What is a Policy]:https://bitbucket.org/imdevelopers/products-documentation/src/v2/Integration%20Manager/Documentation/Administration/3.%20Access%20Management/5.%20Policies/Features/What%20is%20a%20Policy.md
[Windows AD Groups]:https://bitbucket.org/imdevelopers/products-documentation/src/v2/Integration%20Manager/Documentation/Administration/3.%20Access%20Management/3.%20Windows%20AD%20Groups/Features/What%20is%20a%20Windows%20AD%20Group.md