keycloak-scim/topics/overview/terminology.adoc

82 lines
6.2 KiB
Text
Raw Normal View History

== Terminology
2016-06-05 22:17:31 +00:00
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.
2016-06-02 00:35:46 +00:00
==== Resource
2016-06-05 22:17:31 +00:00
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.
2016-09-08 22:58:55 +00:00
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
2016-06-05 22:17:31 +00:00
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.
2016-06-05 22:17:31 +00:00
* *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:
2016-06-05 22:17:31 +00:00
* 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
2016-06-05 22:17:31 +00:00
==== 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.
2016-07-26 21:34:49 +00:00
[[_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).
2016-07-26 21:34:49 +00:00
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.
2016-07-26 21:34:49 +00:00
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.
2016-07-26 21:34:49 +00:00
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.