83 lines
2.8 KiB
Text
Executable file
83 lines
2.8 KiB
Text
Executable file
== Evaluation API
|
|
|
|
When writing rule-based policies such as when you are using Javascript or JBoss Drools, Keycloak provides an *Evaluation API* from where you
|
|
can obtain useful information.
|
|
|
|
This API consists of a few interfaces that provides you access to information such as:
|
|
|
|
* Information about the identity asking for a permission. Here you can obtain the identity identifier (eg.: username) or any other claim/attribute about it.
|
|
* Information about the runtime environment and any other attribute associated with the execution context.
|
|
|
|
The main interface is *org.keycloak.authorization.policy.evaluation.Evaluation*, which defines the following contract:
|
|
|
|
```java
|
|
public interface Evaluation {
|
|
|
|
/**
|
|
* Returns the {@link ResourcePermission} to be evaluated.
|
|
*
|
|
* @return the permission to be evaluated
|
|
*/
|
|
ResourcePermission getPermission();
|
|
|
|
/**
|
|
* Returns the {@link EvaluationContext}. Which provides access to the whole evaluation runtime context.
|
|
*
|
|
* @return the evaluation context
|
|
*/
|
|
EvaluationContext getContext();
|
|
|
|
/**
|
|
* Grants the requested permission to the caller.
|
|
*/
|
|
void grant();
|
|
|
|
/**
|
|
* Denies the requested permission.
|
|
*/
|
|
void deny();
|
|
}
|
|
```
|
|
|
|
For full instructions on using the Evaluation API refer to JavaDocs.
|
|
|
|
=== The Evaluation Context
|
|
|
|
The evaluation context provides useful information to policies during their evaluation.
|
|
|
|
```java
|
|
public interface EvaluationContext {
|
|
|
|
/**
|
|
* Returns the {@link Identity} that represents an entity (person or non-person) to which the permissions must be granted, or not.
|
|
*
|
|
* @return the identity to which the permissions must be granted, or not
|
|
*/
|
|
Identity getIdentity();
|
|
|
|
/**
|
|
* Returns all attributes within the current execution and runtime environment.
|
|
*
|
|
* @return the attributes within the current execution and runtime environment
|
|
*/
|
|
Attributes getAttributes();
|
|
}
|
|
```
|
|
|
|
From this interface, policies can obtain:
|
|
|
|
* The authenticated *Identity*
|
|
* Information about the execution context and runtime environment
|
|
|
|
Before evaluating policies, {{book.project.name}} builds an *EvaluationContext* based on:
|
|
|
|
* All claims obtained from the OAuth2 Access Token that was sent along with the authorization request
|
|
+
|
|
In this case, the *Identity* object provides the same claims as define by the access token. For instance, if you are using a _Protocol Mapper_ to include custom claim
|
|
to a oAuth2 Access Token you can also access this claim from a policy and use it to build your conditions
|
|
+
|
|
* Some built-in environment attributes such as:
|
|
+
|
|
** kc.authz.context.time.date_time, holding the current time
|
|
** kc.authz.context.client.network.ip_address, holding the IP address of the client requesting permissions
|
|
** kc.authz.context.client.network.host, holding the host name of the client requesting permissions
|