Targeting rules

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude
• Connect to Cursor

  Install MCP server on Cursor
• Connect to VS Code

  Install MCP server on VS Code

Targeting rules determine when specific token templates are applied. You can create conditional logic based on user attributes, token types, and other criteria to ensure the right template is used for each authentication scenario.

Overview

Targeting rules allow you to:

• Apply templates conditionally: Use different templates for different users, applications, or contexts
• Segment token behavior: Provide different token structures for various use cases
• Maintain flexibility: Change token behavior without code modifications
• Support multi-tenancy: Apply different templates per tenant or user group

Creating targeting rules

Accessing targeting configuration

1. Navigate to [ENVIRONMENT] → Security → Token management
2. Click on the Targeting tab
3. Click Add Rule to create a new targeting rule

Rule structure

Each targeting rule consists of:

• Attributes: The user or context property to evaluate
• Operators: How to compare the attribute value
• Values: The target values to match against
• Token types: Which token types this rule applies to

Available attributes

Targeting rules can be based on the following attributes (listed in order of appearance):

User attributes

Application attributes

Tenant attributes

Authorization attributes

Operators

Choose from the following operators to define your matching logic (listed in order of appearance):

List matching

String matching

Token types

Select which token types the targeting rule applies to. All three types are selected by default when the dropdown opens:

Available token types

Token type selection

• Default behavior: All token types are selected when creating a new rule
• Selective application: Uncheck token types to exclude them from the rule
• Multiple rules: Create separate rules for different token type combinations

Example targeting scenarios

Scenario 1: Admin users get extended tokens

Rule configuration:

• Attribute: Role ID
• Operator: Is in list
• Value: 2c3d4e5f-6a7b-8c9d-0e1f-2a3b4c5d6e7f
• Token types: User token, User personal token

Result: Admin users receive tokens with extended claims and longer expiration times.

Scenario 2: Mobile app gets minimal tokens

Rule configuration:

• Attribute: Application ID
• Operator: Is in list
• Value: a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d
• Token types: User token

Result: Mobile application users receive lightweight tokens with minimal claims for better performance.

Scenario 3: Specific tenant gets custom claims

Rule configuration:

• Attribute: Tenant ID
• Operator: Is in list
• Value: 9b8a7c6d-5e4f-3a2b-1c0d-e9f8a7b6c5d4
• Token types: All types

Result: Users from the enterprise tenant receive tokens with additional custom claims.

Scenario 4: External users get restricted tokens

Rule configuration:

• Attribute: User email
• Operator: Does not end with
• Value: @yourcompany.com
• Token types: User token, User personal token

Result: External users (not from your company domain) receive tokens with restricted claims.

Scenario 5: API-only users

Rule configuration:

• Attribute: Role ID
• Operator: Is in list
• Values: 3d4e5f6a-7b8c-9d0e-1f2a-3b4c5d6e7f8a, 4e5f6a7b-8c9d-0e1f-2a3b-4c5d6e7f8a9b, 5f6a7b8c-9d0e-1f2a-3b4c-5d6e7f8a9b0c
• Token types: Account (tenant) token

Result: Service accounts and API users receive specialized tokens for machine-to-machine communication.

Rule evaluation

Rule priority

• First match wins: Rules are evaluated in the order they appear
• Default fallback: If no rules match, the default template is used
• Rule ordering: Arrange rules from most specific to most general

Multiple rules

You can create multiple targeting rules for the same template:

1. Specific conditions first: Place more specific rules at the top
2. Broad conditions last: Use general rules as fallbacks
3. Non-overlapping logic: Ensure rules don't conflict with each other

Testing rules

Before deploying targeting rules:

1. Review logic: Ensure your conditions match intended users
2. Test scenarios: Verify rules work with sample data
3. Monitor results: Check that the correct templates are being applied

Best practices

Rule design

• Keep it simple: Start with basic rules and add complexity as needed
• Document logic: Clearly document why each rule exists
• Regular review: Periodically review and update targeting rules

Performance considerations

• Minimize rules: Fewer rules mean faster evaluation
• Efficient operators: Use list matching for specific values or string matching for patterns
• Attribute selection: Choose attributes that are readily available

Security implications

• Principle of least privilege: Ensure rules don't accidentally grant excessive access
• Sensitive data: Be careful with rules that might expose sensitive information
• Audit trail: Keep track of rule changes and their impact

Troubleshooting

Common issues

Rule not applying:

• Check rule order (first match wins)
• Verify attribute values match exactly
• Ensure token type is selected

Unexpected template usage:

• Review rule evaluation order
• Check for overlapping conditions
• Verify fallback behavior

Performance issues:

• Reduce number of rules
• Optimize operator selection
• Consider caching strategies

Debugging tips

1. Test with known values: Use specific user IDs or emails for testing
2. Check logs: Monitor authentication logs for rule evaluation
3. Gradual rollout: Test rules with small user groups first