83 lines
No EOL
6 KiB
Text
Executable file
83 lines
No EOL
6 KiB
Text
Executable file
== Terminology
|
|
|
|
Before going further, it is important to understand some terms and concepts introduced by {{book.project.name}} {{book.project.module}}.
|
|
|
|
==== Resource Server
|
|
|
|
If you are familiar with OAuth2, a Resource Server is the server hosting the protected resources and capable of accepting and responding to protected resource requests.
|
|
|
|
Resource servers usually rely on some kind of information to decide whether access to a protected resource should be granted or not. For RESTful-based resource servers,
|
|
that information is usually obtained from a security token, usually sent as a bearer token on every single request to the server. For web applications that rely on a session to
|
|
authenticate their users, that information is usually stored into user's session and retrieved from there on every single request.
|
|
|
|
In Keycloak, any *confidential* client application may act as a resource server. Whose resources and their respective scopes are
|
|
protected and ruled by a set of authorization policies.
|
|
|
|
==== Resource
|
|
|
|
A resource is part of the assets of an application and the organization. It can be a set of one or more endpoints, a classic web resource such as an HTML page, and so on.
|
|
In authorization policy terminology, a resource is the _object_ being protected.
|
|
|
|
Every single resource has a unique identifier, where a resource may also be used to represent a single
|
|
or a set of resources. For instance, you may want to manage a _Banking Account Resource_ that represents and defines a set of authorization policies for all banking accounts.
|
|
But you may also have a _Alice Banking Account_, which represents a single resource owned by a single customer, which may have its own set of authorization policies.
|
|
|
|
==== Scope
|
|
|
|
A bounded extent of access that is possible to perform on a resource. In authorization policy
|
|
terminology, a scope is one of the potentially many _verbs_ that can logically apply to a resource.
|
|
|
|
It usually indicates what can be done with a given resource. Example of scopes are _view_,
|
|
_edit_, _delete_, etc. However, it may also be related with some information provided by a resource. In this case, you
|
|
may have a _Project_ resource and a _cost_ scope, where _cost_ scope may be used to define specific policies
|
|
and permissions for those trying to access project's cost.
|
|
|
|
==== Permission
|
|
|
|
Consider this simple and very common permission:
|
|
|
|
* *X* CAN DO *Y* ON RESOURCE *Z*
|
|
** where ...
|
|
*** *X* represents one or more Users, Roles, Groups or a combination of them. You can also use claims and context here ...
|
|
*** *Y* represents an action to be performed. Eg.: write, view, etc
|
|
*** *Z* represents a protected resource.
|
|
|
|
A permission associates the object being protected and the policies that must be evaluated in order to decide whether access should be granted or not.
|
|
|
|
{{book.project.name}} provides a rich platform for building from the most simple to the more complex permissions. It provides great flexibility and helps to:
|
|
|
|
* Reduce code refactoring and permission management costs
|
|
* Support a more flexible security model, helping you to easily adapt to changes to your security requirements
|
|
* Make changes at runtime given that applications only care about the resources and scopes being protect and not how they are actually protected
|
|
|
|
==== Policy
|
|
|
|
A policy defines the conditions that must be satisfied to grant access to an object. Different than permissions, you don't really specify the object being protected
|
|
but the conditions that must be satisfied to get access to a given object (eg.: resource, scope or both).
|
|
Policies are strongly related with the different _access control mechanism_ that you can use to actually protect your resources.
|
|
Within a policy you can use ABAC, RBAC, Context-based Access Control or any combination of these.
|
|
|
|
Keycloak leverages the concept of policies and how you define them by providing the concept of *Aggregated Policies*, where you can build a "policy of policies" and still control the behavior of the evaluation.
|
|
Instead of writing a single and huge policy with all conditions that must be satisfied to get access to a given resource, policies in Keycloak follows the *divide-and-conquer* technique,
|
|
so you can create individual policies, reuse them on different permissions and build more complex policies by combining them into a single one.
|
|
|
|
==== Policy Provider
|
|
|
|
Policy providers are responsible to support a specific policy type. Although {{book.project.name}} provides some built-in policies, backed by their corresponding
|
|
policy providers, nothing stops you to create your own policy types in order to better support your requirements or a specific use case.
|
|
|
|
{{book.project.name}} provides a *SPI* (Service Provider Interface) that you can use to plug your own policy providers.
|
|
|
|
[[_permission_ticket]]
|
|
==== Permission Ticket
|
|
|
|
A Permission Ticket is a special type of token defined by the https://docs.kantarainitiative.org/uma/rec-uma-core.html[UMA] specification that provides an opaque structure whose form is determined by the authorization server. This
|
|
structure represents the resources and/or scopes being requested by a client as well the policies that must be applied to a request for authorization data (RPT).
|
|
|
|
In UMA, permission tickets are crucial to support *person-to-person sharing* and also *person-to-organization sharing*, introducing the possbility to cover from the most simple to the most complex
|
|
*authorization workflows*, where resource owners and resource servers may have complete control over their resources based on fine-grained policies that govern the access to these resources.
|
|
|
|
During the UMA flow, permissions tickets are issued by the authorization server to a resource server, which in turn returns it back to the client trying to access a protected resource. Once the client
|
|
receives the ticket, it can request for a RPT (a final token holding authorization data) by sending the ticket back to the authorization server.
|
|
|
|
For more details, take a look at link:../service/authorization/authorization-api.html[Authorization API] and https://docs.kantarainitiative.org/uma/rec-uma-core.html[UMA] specification. |