Skip to content
Tutorials Center
My learning

Topics

Lesson 24 of 37 ยท Authorization Services

Policies, Permissions and Decision Strategies

Learn Keycloak policy types (role, user, group, time, regex, aggregate), permission types, logic Positive and Negative, and the Unanimous, Affirmative, Consensus strategies.

The previous lesson introduced resources, scopes, policies, and permissions. This lesson digs into the policy types you will actually create, how several policies combine inside one permission, and the settings that flip a decision: logic and decision strategy. Small details here decide whether your rules deny too much or, worse, allow too much.

The product cannot run on this site. The code is a JavaScript stand-in implementing the same combination rules, so you can try each strategy with your own inputs.

Policy types

On the Policies tab choose Create policy and pick a type. The built-in ones:

  • Role: the caller must have one or more realm or client roles. Each role can be marked required.
  • User: a list of specific users.
  • Group: members of groups; optionally include child groups.
  • Client: calls from certain clients.
  • Time: valid between dates and clock times (for example hours 9 to 17, month, day of month).
  • Regex: matches a claim value to a regular expression, such as an email domain.
  • Aggregate: bundles other policies into one so you can reuse a composite rule.
  • Client scope: the token includes a given client scope.
  • JavaScript: arbitrary script. Scripts must be deployed as providers, are disabled by default in recent versions and discouraged. Prefer the types above or a custom Java policy provider.

Every policy has a Logic setting:

  • Positive (default): the policy grants when its condition is true.
  • Negative: the result is inverted, so the policy grants when the condition is false. Use it for exclusions such as "everyone except contractors".

Permission types

  • Resource-based permission: protects a specific resource or all resources of a type. It does not name scopes, so it answers "may the caller touch the resource at all?".
  • Scope-based permission: protects chosen scopes, optionally of a single resource or resource type. It answers "may the caller do edit on this resource?".

A permission lists one or more policies and sets a Decision strategy.

Decision strategies

When a permission has several policies, the decision strategy says how their results combine:

Strategy Grants when
Unanimous every policy grants (default)
Affirmative at least one policy grants
Consensus more policies grant than deny

The same setting exists on the resource server itself, where it combines the results of different permissions that apply to one request. Unanimous at the server level means every applicable permission must grant, which is the safe default.

JS Stand-in: logic and decision strategies

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Read the output carefully: the caller satisfies two policies (editor and corp mail), fails three (finance, office hours, not-a-contractor). Unanimous denies, Affirmative grants, and Consensus (2 grants vs 3 denies) denies.

Combining permissions at the server

Several permissions can match one request, for example a resource-based permission for the resource and a scope-based one for edit. The resource server decision strategy (Authorization > Settings) combines them. In most systems keep Unanimous: a broad "everyone can view" permission must not accidentally override a narrow "only the owner can delete" rule.

Another important setting is Policy enforcement mode:

  • Enforcing (default): requests with no matching permission are denied.
  • Permissive: requests with no matching permission are allowed.
  • Disabled: policies are not evaluated at all.

Permissive is occasionally useful while migrating, but forgetting it is a classic hole.

Walking through a worked design

Imagine an invoicing app:

  • Resource type invoice with scopes view, edit, approve.
  • Policies: finance-group (group), manager-role (role), office-hours (time), not-contractor (group with logic Negative).
  • Permissions:
    • view-invoices: scope view, policies finance-group, manager-role, strategy Affirmative.
    • edit-invoices: scope edit, policies finance-group, not-contractor, strategy Unanimous.
    • approve-invoices: scope approve, policies manager-role, office-hours, strategy Unanimous.

Keep names descriptive: they appear in logs and in Evaluate results. Prefer a few well-named reusable policies over many one-off ones.

JS Stand-in: a decision table for the invoicing design

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Debugging checklist

  1. Use the Evaluate tab with the real user and roles; read which permission denied.
  2. Remember the default: no matching permission means deny in Enforcing mode.
  3. Check that the resource has the right type and scopes, because type-based permissions apply only to resources of that type.
  4. Check Negative logic: a policy that looks like "contractors" may be inverted.
  5. Confirm the user actually has the role in the token or realm, including composite and client roles.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. A permission lists three policies. Two grant, one denies. Which strategy grants?

    Affirmative needs one grant, Consensus needs more grants than denies (2 vs 1); Unanimous needs all.
  2. 2. What does Negative logic on a policy do?

    A Negative policy grants when its condition is false, which is how you express exclusions.
  3. 3. What happens in Enforcing mode when no permission matches a request?

    Enforcing mode denies anything not covered by a granting permission.
  4. 4. Which type of permission names specific actions such as edit?

    Scope-based permissions attach policies to scopes of resources.

Summary

  • Policy types: role, user, group, client, time, regex, aggregate, client scope; logic Positive or Negative.
  • Resource-based permissions guard resources; scope-based permissions guard actions.
  • Unanimous, Affirmative, and Consensus decide how policies combine.
  • Keep the server in Enforcing mode with Unanimous strategy unless you have a reason.
  • Debug with the Evaluate tab.

Next: RPTs and Policy Enforcement