Resources, scopes, permissions and policies in keycloak
I know I'm 2+ years late but I figure I'd share what I know and hopefully alleviate some pain for future readers. Full transparency- I am by no means a Keycloak/OAuth/OIDC expert and what I know is mostly from reading the docs, books, good ol' YouTube and playing around with the tool.
This post will be comprised of two parts:
- I'll attempt to answer all your questions to the best of my ability
- I'll show you all how you can play around with policies/scopes/permissions in Keycloak without needing to deploy a separate app in order to better understand some of the core concepts in this thread. Do note though that this is mostly meant to get you all started. I'm using
Keycloak 8.0.0
.
Part I
Some terminology before we get started:
- In Keycloak, you can create 2 types of permissions: Resource-Based and Scope-Based.
- Simply put, for
Resource-Based
permissions, you apply it directly to your resource - For
Scoped-Based
permission, you apply it to your scope(s) or scope(s) and resource.
is it best practice to create just one "view" scope, and use it across multiple resources (account, transaction, etc)? Or should I create a "viewAccount" scope, a "viewTransaction" scope, etc?
Scopes represent a set of rights at a protected resource. In your case, you have 2 resources: account
and transaction
, so I would lean towards the second approach.
In the long run, having a global view
scope associated with all your resources (e.g. account
, transaction
, customer
, settlement
...) makes authorization difficult to both manage and adapt to security requirement changes.
Here are a few examples that you can check out to get a feel for design
- Slack API
- Box API
- Stripe
Do note though - I am not claiming that you shouldn't share scopes across resources. Matter of fact, Keycloak
allows this for resources with the same type
. You could for instance need both viewAccount
and viewTransaction
scope to read a transaction under a given account (after all you might need access to the account to view transactions). Your requirements and standards will heavily influence your design.
For each practical combination of resource and scope, is it usual practice to create a permission?
Apologies, I don't fully understand the question so I'll be a bit broad. In order to grant/deny access to a resource
, you need to:
- Define your policies
- Define your permissions
- Apply your policies to your permissions
- Associate your permissions to a
scope
orresource
(or both)
for policy enforcement to take effect. See Authorization Process.
How you go about setting all this up is entirely up to you. You could for instance:
Define individual policies, and tie each policy under the appropriate permission.
Better yet, define individual policies, then group all your related policies under an
aggregated
policy (a policy of policies) and then associate that aggregated policy with thescope-based
permission. You could have thatscoped-based
permission apply to both the resource and all its associated scope.Or, you could further break apart your permissions by leveraging the two separate types. You could create permissions solely for your resources via the
resource-based
permission type, and separately associate other permissions solely with a scope via thescope-based
permission type.
You have options.
If there are multiple permissions matching a given resource/scope, what does Keycloak do?
This depends on
- The resource server's
Decision Strategy
- Each permission's
Decision Strategy
- Each policy's
Logic
value.
The Logic
value is similar with Java's !
operator. It can either be Positive
or Negative
. When the Logic
is Positive
, the policy's final evaluation remains unchanged. When its Negative
, the final result is negated (e.g. if a policy evaluates to false and its Logic
is Negative
, then it will be true
). To keep things simple, let's assume that the Logic
is always set to Positive
.
The Decision Strategy
is what we really want to tackle. The Decision Strategy
can either be Unanimous
or Affirmative
. From the docs,
Decision Strategy
This configurations changes how the policy evaluation engine decides whether or not a resource or scope should be granted based on the outcome from all evaluated permissions. Affirmative means that at least one permission must evaluate to a positive decision in order grant access to a resource and its scopes. Unanimous means that all permissions must evaluate to a positive decision in order for the final decision to be also positive. As an example, if two permissions for a same resource or scope are in conflict (one of them is granting access and the other is denying access), the permission to the resource or scope will be granted if the chosen strategy is Affirmative. Otherwise, a single deny from any permission will also deny access to the resource or scope.
Let's use an example to better understand the above. Suppose you have a resource with 2 permissions and someone is trying to access that resource (remember, the Logic
is Positive
for all policies). Now:
Permission One
has aDecision Strategy
set toAffirmative
. It also has 3 policies where they each evaluate to:true
false
false
Since one of the policies is set to true
, Permission One
is set to true
(Affirmative - only 1 needs to be true
).
Permission Two
has aDecision Strategy
set toUnanimous
with 2 policies:true
false
In this case Permission Two
is false
since one policy is false (Unanimous - they all need to be true
).
- Now comes the final evaluation. If the resource server's
Decision Strategy
is set toAffirmative
, access to that resource would be granted becausePermission One
istrue
. If on the other hand, the resource server'sDecision Strategy
is set toUnanimous
, access would be denied.
See:
- Resource Server Settings
- Managing Permissions
We'll keep revisiting this. I explain how to set the resource sever's Decision Strategy
in Part II.
so for example I could have permission to access "accounts" and permission for "view" scope, so therefore I would have permission to view accounts?
The short answer is yes. Now, let's expand on this a bit :)
If you have the following scenario:
- Resource server's
Decision Strategy
set toUnanimous
orAffirmative
- Permission to access the
account/{id}
resource istrue
- Permission to access the
view
scope istrue
You will be granted access to view the account.
true
+true
is equal totrue
under theAffirmative
orUnanimous
Decision Strategy
.
Now if you have this
- Resource server's
Decision Strategy
set toAffirmative
- Permission to access the
account/{id}
resource istrue
- Permission to access the
view
scope isfalse
You will also be granted access to view the account.
true
+false
istrue
under theAffirmative
strategy.
The point here is that access to a given resource also depends on your setup so be careful as you may not want the second scenario.
But am I right that this means I need a policy for each of the legacy groups that a user could belong to?
I'm not sure how Keycloak behaved 2 years ago, but you can specify a Group-Based policy and simply add all your groups under that policy. You certainly do not need to create one policy per group.
For example, if I have a "helpdesk" role, then I need a "helpdesk membership" policy, which I could then add to the "viewAccount" permission. Is this correct?
Pretty much. There are many ways you can set this up. For instance, you can:
- Create your resource (e.g.
/account/{id}
) and associate it with theaccount:view
scope. - create a Role-Based Policy and add the
helpdesk
role under that policy - Create a
Scope-Based
permission calledviewAccount
and tie it withscope
,resource
andpolicy
We'll set up something similar in Part II.
Part II
Keycloak has a neat little tool which allows you test all your policies. Better yet, you actually do not need to spin up another application server and deploy a separate app for this to work.
Here's the scenario that we'll set up:
- We'll create a new realm called
stackoverflow-demo
- We'll create a
bank-api
client under that realm - We will define a resource called
/account/{id}
for that client - The
account/{id}
will have theaccount:view
scope - We'll create a user called
bob
under the new realm - We'll also create three roles:
bank_teller
,account_owner
anduser
- We will not associate
bob
with any roles. This is not needed right now.
- We will not associate
- We'll set up the following two
Role-Based
policies:bank_teller
andaccount_owner
have access to the/account/{id}
resourceaccount_owner
has access to theaccount:view
scopeuser
does not have access to the resource or scope
- We'll play around with the
Evaluate
tool to see how access can be granted or denied.
Do forgive me, this example is unrealistic but I'm not familiar with the banking sector :)
Keycloak setup
Download and run Keycloak
cd tmp
wget https://downloads.jboss.org/keycloak/8.0.0/keycloak-8.0.0.zip
unzip keycloak-8.0.0.zip
cd keycloak-8.0.0/bin
./standalone.sh
Create initial admin user
- Go to
http://localhost:8080/auth
- Click on the
Administration Console
link - Create the admin user and login
Visit Getting Started for more information. For our purposes, the above is enough.
Setting up the stage
Create a new realm
- Hover your mouse around the
master
realm and click on theAdd Realm
button. - Enter
stackoverflow-demo
as the name. - Click on
Create
. - The top left should now say
stackoverflow-demo
instead of themaster
realm.
See Creating a New Realm
Create a new user
- Click on the
Users
link on the left - Click on the
Add User
button - Enter the
username
(e.g.bob
) - Ensure that
User Enabled
is turned on - Click
Save
See Creating a New User
Create new roles
- Click on the
Roles
link - Click on
Add Role
- Add the following roles:
bank_teller
,account_owner
anduser
Again, do not associate your user with the roles. For our purposes, this is not needed.
See Roles
Create a client
- Click on the
Clients
link - Click on
Create
- Enter
bank-api
for theClient ID
- For the
Root URL
enterhttp://127.0.0.1:8080/bank-api
- Click on
Save
- Ensure that
Client Protocol
isopenid-connect
- Change the
Access Type
toconfidential
- Change
Authorization Enabled
toOn
- Scroll down and hit
Save
. A newAuthorization
tab should appear at the top. - Click on the
Authorization
tab and thenSettings
- Ensure that the
Decision Strategy
is set toUnanimous
- This is the resource server's
Decision Strategy
- This is the resource server's
See:
- Creating a Client Application
- Enabling Authorization Services
Create Custom Scopes
- Click on the
Authorization
tab - Click on
Authorization Scopes
>Create
to bring upAdd Scope
page - Enter
account:view
in the name and hit enter.
Create "View Account Resource"
- Click on
Authorization
link above - Click on
Resources
- Click on
Create
- Enter
View Account Resource
for both theName
andDisplay name
- Enter
account/{id}
for theURI
- Enter
account:view
in theScopes
textbox - Click
Save
See Creating Resources
Create your policies
- Again under the
Authorization
tab, click onPolicies
- Select
Role
from the theCreate Policy
dropdown - In the
Name
section, typeOnly Bank Teller and Account Owner Policy
- Under
Realm Roles
select both thebank_teller
andaccount_owner
role - Ensure that
Logic
is set toPositive
- Click
Save
- Click on the
Policies
link - Select
Role
again from theCreate Policy
dropdown. - This time use
Only Account Owner Policy
for theName
- Under
Realm Roles
selectaccount_owner
- Ensure that
Logic
is set toPositive
- Click
Save
- Click on the
Policies
link at the top, you should now see your newly created policies.
See Role-Based Policy
Do note that Keycloak has much more powerful policies. See Managing Policies
Create Resource-Based Permission
- Again under the
Authorization
tab, click onPermissions
- Select
Resource-Based
- Type
View Account Resource Permission
for theName
- Under
Resources
typeView Account Resource Permission
- Under
Apply Policy
selectOnly Bank Teller and Account Owner Policy
- Ensure that the
Decision Strategy
is set toUnanimous
- Click
Save
See Create Resource-Based Permissions
Phew...
Evaluating the Resource-Based permission
- Again under the
Authorization
tab, selectEvaluate
- Under
User
enterbob
- Under
Roles
selectuser
- This is where we will associate our user with our created roles.
- Under
Resources
selectView Account Resource
and clickAdd
- Click on Evaluate.
- Expand the
View Account Resource with scopes [account:view]
to see the results and you should seeDENY
.
- This makes sense because we only allow two roles access to that resource via the
Only Bank Teller and Account Owner Policy
. Let's test this to make sure this is true! - Click on the
Back
link right above the evaluation result - Change bob's role to
account_owner
and click onEvaluate
. You should now see the result asPERMIT
. Same deal if you go back and change the role tobank_teller
See Evaluating and Testing Policies
Create Scope-Based Permission
- Go back to the
Permissions
section - Select
Scope-Based
this time under theCreate Permission
dropdown. - Under
Name
, enterView Account Scope Permission
- Under
Scopes
, enteraccount:view
- Under
Apply Policy
, enterOnly Account Owner Policy
- Ensure that the
Decision Strategy
is set toUnanimous
- Click
Save
See Creating Scope-Based Permissions
Second test run
Evaluating our new changes
- Go back to the
Authorization
section - Click on
Evaluate
- User should be
bob
- Roles should be
bank_teller
- Resources should be
View Account Resource
and clickAdd
- Click on
Evaluate
and we should getDENY
.- Again this should come as no surprise as the
bank_teller
has access to theresource
but not thescope
. Here one permission evaluates to true, and the other to false. Given that the resource server'sDecision Strategy
is set toUnanimous
, the final decision isDENY
.
- Again this should come as no surprise as the
- Click on
Settings
under theAuthorization
tab, and change theDecision Strategy
toAffirmative
and go back to steps 1-6 again. This time, the final result should bePERMIT
(one permission is true, so final decision is true). - For the sake of completeness, turn the resource server's
Decision Strategy
back toUnanimous
. Again, go back to steps 1 through 6 but this time, set the role asaccount_owner
. This time, the final result is againPERMIT
which makes sense, given that theaccount_owner
has access to both theresource
andscope
.
Neat :) Hope this helps.
i know i am bit late to the party but let me try to explain as much as i can.
in keycloak we have terms like :
Resource : object which users will be accessing or performing the action on
Auth scopes : Actions that users can perform on the specific object
Policies : Policy
Permission : Mapping actually occur here
If you don't want to follow manual way you can export this JSON and all the users, resources, permissions will be auto-set bu keycloak
JSON configuration file
Now let's see a scenario where :
Now we have few resources like :
- Account
- Bot
- Report
We want to implement the scenario where only specific user can performe specific actions.
Setting up the Keycloak
Create a new realm
- Click on the Add Realm button.
- Enter test-v1 as the name.
- Click on Create.
Create new roles
- Click on the Roles
- Click on Add Role
- Create the roles "admin", "agent" & "super_admin"
Create a client
- Click on the Clients tab
- Enter app-client in Client ID textbox
- Click on Save
- Select and choose client again to configure other settings
- Verify the client Protocol is openid-connect
- Set Access Type to confidential
- Set Authorization Enabled to On
- Click on Save button at last.
- A new Authorization tab will appear at the top.
- Select on the Authorization tab and then Settings
Check that the Decision Strategy is set to Unanimous. This is the resource server strategy
Create Custom Auth Scopes
Go the Authorization tab Select Authorization Scopes > and click on Create Enter scopes:create & scopes:view in the text and save values.
Create Resource
- Go to Resources tab now > and click on Create
- Enter one by one and create the following resources res:account & res:bot & res:report
- For all resource in scope text select both scopes that we created early scopes:create & scopes:view
- Click Save
Create policies
- Again inside the Authorization tab, select on Policies
- Click on the Create Policy dropdown and select the Role
- In the Name textbox, Admin
- In Realm Roles select role Admin
- Check Logic is set to Positive
- Click Save, Do it same for "Agent" & "Super_admin"
- Again inside the Authorization tab, select on Policies
- Click on the Create Policy dropdown and select the Aggregated
- In the Name textbox, Admin or Super_admin or Agent
- In Realm Roles select role Admin & Super_admin & Agent
- Check Logic is set to Affirmative
- Click Save
Create permission
- Again inside the Authorization tab, select on Permission
- Click on the Create Permissions dropdown and select the Scope-Based
- In the Name textbox, account-create
- In resource box, select the "resource res:account"
- In scopes select, scopes:create
- Apply policy Admin
- We have to set permission same way for all the resources as per requirement
Create user
- Inside the user tab create one test user We will not assign any roles, scopes, or group to it for testing
Let's Evaluate
- Again inside the Authorization tab, select on Evaluate
- Select the client we created, app-client
- In user select the created user, test
- In roles select the created user, admin
- Resource value, res:account
- Click on Add button
- Click on Evaluate button
You will see grant is permitted as Admin role has access to do operations create and view on resource account.
Let's Evaluate Again
- Again inside the Authorization tab, select on Evaluate
- Select the client we created, app-client
- In user select the created user, test
- In roles select the created user, admin
- Resource value, res:report
- Scopes value, scopes:create
- Click on Add button
- Click on Evaluate button
You will see grant is Deny as only Super_Admin role has access to do operations create on resource report.
I was looking to enforce authorization via pure HTTP methods, without using the adapter as Lua did not have an adapter. Hope this answer helps people looking for non-adapter based method.
If you are looking for the adapter the quick start guide is the best place to start. Especially the spring boot authz example.
For pure HTTP based implementation:
Step 1:
Define the policies and permission in the Keycloak Admin UI
Step 2
Have an internal mapping of which HTTP paths belong to which resources and the required scopes for each path. This can be also saved in the configuration file. When a particular route is invoked, call the Keycloak token endpoint to validate the claims of the access token.
{
"policy-enforcer": {
"user-managed-access" : {},
"enforcement-mode" : "ENFORCING"
"paths": [
{
"path" : "/someUri/*",
"methods" : [
{
"method": "GET",
"scopes" : ["urn:app.com:scopes:view"]
},
{
"method": "POST",
"scopes" : ["urn:app.com:scopes:create"]
}
]
}
]
}
}
If you are using an adapter and does not specify the path or resource, the adapter will internally search for the paths and resources from Keycloak.
Step 3:
Use the token endpoint to get or evaluate the permissions. You can use response_mode
parameter to either obtain the final decision (whether to provide access) or retrieve the entire permissions.
curl -X POST \
http://${host}:${port}/auth/realms/${realm}/protocol/openid-connect/token \
-H "Authorization: Bearer ${access_token}" \
--data "grant_type=urn:ietf:params:oauth:grant-type:uma-ticket" \
--data "permission=Resource A#Scope A"
If the authorization request does not map to any permission, a 403
HTTP status code is returned instead.