82 lines
No EOL
6.2 KiB
Text
Executable file
82 lines
No EOL
6.2 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
|
|
|
|
Per OAuth2 terminology, 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 carried in a security token, typically sent as a bearer token along with every request to the server. Web applications that rely on a session to
|
|
authenticate their users usually store that information in the user's session and retrieve it from there on every request.
|
|
|
|
In Keycloak, any *confidential* client application may act as a resource server. This client's 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 which may represent a single resource 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 different resource named _Alice's Banking Account_, which represents a single resource owned by a single customer, which may have its own set of authorization policies.
|
|
|
|
=== Scope
|
|
|
|
A resource's scope is 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:
|
|
|
|
A permission associates the object being protected with the policies that must be evaluated in order to decide whether or not access should be granted.
|
|
|
|
* *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, e.g., "write", "view", etc
|
|
*** *Z* represents a protected resource, e.g., "/accounts".
|
|
|
|
{{book.project.name}} provides a rich platform for building a range of permission strategies ranging from simple to very complex, rule-based dynamic 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 in your security requirements
|
|
* Make changes at runtime -- applications only care about the resources and scopes being protected 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 specify the object being protected
|
|
but the conditions that must be satisfied to get access to a given object (e.g., resource, scope, or both).
|
|
Policies are strongly related to the different _access control mechanisms_ that you can use to actually protect your resources.
|
|
With policies, you can implement strategies for 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, the policies implementation in {{book.project.name}} {{book.project.module}} follows the *divide-and-conquer* technique.
|
|
That is, you can create individual policies, reuse them on different permissions, and build more complex policies by combining individual policies.
|
|
|
|
=== Policy Provider
|
|
|
|
Policy providers are implementations of specific policy types. {{book.project.name}} provides some built-in policies, backed by their corresponding
|
|
policy providers, and you are free to create your own policy types to support your specific requirements.
|
|
|
|
{{book.project.name}} provides a *SPI* (Service Provider Interface) that you can use to plug in your own policy provider implementations.
|
|
|
|
[[_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[OAuth2's User-Managed Access (UMA) Profile] 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 a the policies that must be applied to a request for authorization data (requesting party token or RPT).
|
|
|
|
In UMA, permission tickets are crucial to support *person-to-person sharing* and also *person-to-organization sharing*. Using permission tickets for *authorization workflows* enables a range of scenarios from simple to complex,
|
|
where resource owners and resource servers have complete control over their resources based on fine-grained policies that govern the access to these resources.
|
|
|
|
During the UMA flow, permission 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 make a request for a requesting party token (RPT) (a final token holding authorization data) by sending the ticket back to the authorization server.
|
|
|
|
For more details, see link:../service/authorization/authorization-api.html[Authorization API] and the https://docs.kantarainitiative.org/uma/rec-uma-core.html[UMA] specification. |