keycloak-scim/topics/policy/evaluation-api.adoc

== Evaluation API

When writing rule-based policies such as when you are using Javascript or JBoss Drools, {{book.project.name}} provides an *Evaluation API* from where you
can obtain useful information in order to decide whether a permission should be granted or not.

This API consists of a few interfaces that provides you access to information such as:

* The permission being requested
* The identity asking for a permission, from where you can obtain claims/attributes
* 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();
}
```
[NOTE]
For more details about the Evaluation API refer to http://www.keycloak.org/docs/javadocs/index.html[JavaDocs].

When processing an authorization request, {{book.project.name}} creates an `Evaluation` instance before evaluating any policy. This instance is then passed to each policy in order to obtain
a decision, which would be a *GRANT* or a *DENY*.

Policies take their decisions by invoking the `grant()` or `deny()` methods on an `Evaluation` instance. By default, the state of the `Evaluation` instance is denied, which means that your policies
need to explicitly invoke the `grant()` method if they want to tell the policy evaluation engine that the permission should be granted.

=== 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

The `Identity` is built based on the OAuth2 Access Token that was sent along with the authorization request, from where you have access to all claims
extracted from the original token. For instance, if you are using a _Protocol Mapper_ to include a custom claim to a oAuth2 Access Token you can also access this claim
from a policy and use it to build your conditions

The `EvaluationContext` also gives you access to attributes related with both execution and runtime environment. For now, there only a few built-in attributes.

.Execution and Runtime Attributes
|===
|Name |Description | Type

| kc.time.date_time
| Current date and time
| String. Format `MM/dd/yyyy hh:mm:ss`

| kc.client.network.ip_address
| IPv4 address of the client
| String

| kc.client.network.host
| Client's host name
| String

| kc.client.id
| The client id
| String

| kc.client.user_agent
| The value of the 'User-Agent' HTTP header
| String[]

| kc.realm.name
| The name of the realm
| String

|===