1What Claim-Role Mapping does
Automated collection membership at federated login
When a user logs into EmpowerNow through a federated IdP (Entra ID, Okta, ADFS, etc.), the IdP sends a set of claims in the token — attributes like department, groups, jobTitle, or custom claims. Claim-Role Mapping rules evaluate these claims and automatically place the user in the matching EmpowerNow collections.
Without CRM, every federated user would arrive with no collection memberships and therefore no application access. CRM eliminates the need to manually assign every user after their first login.
Entra ID sends claim department = "Engineering". A CRM rule says: if department equals "Engineering", add to collection "Engineers". On login, the user is automatically placed in the Engineers collection — which has application roles attached — and can immediately access the right tools.
What makes up a CRM rule
| Component | What it is |
|---|---|
| Name | Human-readable label for the rule. Appears in the rules list and audit logs. |
| IdP Provider | Which identity provider this rule applies to. Rules are scoped per IdP, so an Entra rule won't fire for an Okta login. |
| Conditions | One or more claim-value tests. All conditions must match (AND logic). Each condition has a claim key, operator, and value. |
| Target Collections | The EmpowerNow collections the user is placed in when all conditions match. |
| Priority | Numeric priority. Lower number = higher priority. When multiple rules match, they all apply, but priority determines evaluation order. |
| Status | Active (fires on login), Draft (won't fire), Disabled (paused), Archived (retired). |
| Validity | Optional valid-from and expires-at dates. A rule outside its validity window acts as Disabled. |
Available claim operators
| Operator | Matches when… |
|---|---|
| equals | Claim value exactly equals the specified value (case-insensitive) |
| not equals | Claim value does not equal the specified value |
| contains | Claim value contains the substring |
| starts with | Claim value begins with the prefix |
| ends with | Claim value ends with the suffix |
| is in list | Claim value is one of a comma-separated list of values |
| exists | The claim is present in the token (any value) |
| not exists | The claim is absent from the token |
2Open the editor
Administration → Identity → Claim-Role Mapping
Navigate to /identity-core/claim-role-mapping. The editor loads in two panes: the left pane shows the IdP selector and existing rules list; the right pane is the rule builder (appears when you create or edit a rule).
3Create a rule
Select an IdP and click + Create Rule
In the left pane, click the card for the IdP you want to create a rule for. Once selected (highlighted in blue), click the + Create Rule button that appears below the rules list. The right pane switches to the rule builder.
Fill in the rule builder
| Field | Required | Notes |
|---|---|---|
| Rule Name | Yes | Descriptive name that appears in the rules list and audit logs. Suggested format: Source → Target. |
| Description | No | Operator notes explaining the business purpose of the rule. |
| Conditions | Yes (min 1) | Each condition tests one claim. Multiple conditions use AND logic — all must match. |
| Target Collections | Yes (min 1) | The collections the user is added to when the rule matches. Multiple collections can be selected. |
| Priority | No | Default 100. Use lower numbers (e.g. 10) for rules that should be evaluated first. |
| Status | No | Start as Draft to test before activating. Switch to Active when ready to fire on real logins. |
New rules default to Draft status, which means they are saved but do not fire during login. Test with the simulation tool (Task 4) before changing status to Active.
4Simulate & test a rule
The rule builder simulates automatically as you type
While building or editing a rule, the simulation panel on the right side of the rule builder updates in real time. As you add conditions and values, EmpowerNow runs a simulation against sample claim data and shows which collections the rule would match.
The simulation panel shows:
- Matched collections — collections that would receive the user if the rule fired now
- Condition evaluation — which conditions passed or failed for the test data
- Warnings — if a referenced collection no longer exists or has no members
To verify a rule will work for an actual user, enter the claim values that the IdP would send for that user. The simulation shows exactly which collections would be assigned.
Troubleshooting a rule that doesn't match
| Symptom | Likely cause | Fix |
|---|---|---|
| Rule is Active but user didn't get collection | Claim key casing mismatch or IdP sends different key name | Check the actual claim name in IdP token inspector; claim keys are case-sensitive |
| Rule matches in simulation but not on real login | Rule is scoped to wrong IdP | Verify the rule is under the correct IdP in the left pane |
| Rule fires but user gets wrong collections | Multiple rules are matching and a higher-priority rule overrides | Review all active rules for this IdP; check for overlapping conditions |
| Rule status is Active but never fires | Validity date has expired | Check the expires-at field on the rule |
5Edit & toggle rules
Click a rule card to open it in the rule builder
In the left pane, click any rule card. The right pane loads the rule's current values. Make your changes and click 💾 Save Rule. Changes take effect immediately on the next login for affected users.
Toggle a rule without deleting it
Each rule card in the list has an ⏸ Disable button (for active rules) or a ▶ Enable button (for disabled rules). Clicking it flips the rule's status between active and disabled immediately, with no confirmation dialog.
If you are updating a rule's conditions and want to prevent it from firing during the edit window, disable it first, make your changes, simulate, and then re-enable it. Users who log in while the rule is disabled will not receive the associated collections.
6Delete a rule
Click 🗑 Delete on the rule card
Each rule card has a 🗑 Delete button. Clicking it opens a confirmation dialog naming the rule. Click Delete Permanently to confirm.
Deleting a CRM rule removes the rule definition only. Users who were already placed in collections by this rule remain in those collections — their membership is not automatically revoked. If you need to remove those users from the collection, do so separately in the Collections admin.
If you might need the rule again (e.g. a seasonal or project-based rule), consider setting its status to Archived rather than deleting it. Archived rules are preserved for audit purposes and can be re-activated.