119 lines
3.8 KiB
Text
119 lines
3.8 KiB
Text
[[_policy_evaluation_api]]
|
|
= Policy Evaluation API
|
|
|
|
When writing rule-based policies using JavaScript or JBoss Drools, {project_name} provides an Evaluation API that provides useful information to help determine whether a permission should be granted.
|
|
|
|
This API consists of a few interfaces that provide you access to information, such as
|
|
|
|
* The permission being evaluated, representing both the resource and scopes being requested.
|
|
* The attributes associated with the resource being requested
|
|
* Runtime environment and any other attribute associated with the execution context
|
|
* Information about users such as group membership and roles
|
|
|
|
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();
|
|
|
|
/**
|
|
* Returns a {@link Realm} that can be used by policies to query information.
|
|
*
|
|
* @return a {@link Realm} instance
|
|
*/
|
|
Realm getRealm();
|
|
|
|
/**
|
|
* Grants the requested permission to the caller.
|
|
*/
|
|
void grant();
|
|
|
|
/**
|
|
* Denies the requested permission.
|
|
*/
|
|
void deny();
|
|
}
|
|
```
|
|
|
|
When processing an authorization request, {project_name} creates an `Evaluation` instance before evaluating any policy. This instance is then passed to each policy to determine whether access is *GRANT* or *DENY*.
|
|
|
|
Policies determine this 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 must explicitly invoke the `grant()` method to indicate to the policy evaluation engine that permission should be granted.
|
|
|
|
For more information about the Evaluation API see the {apidocs_link}[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
|
|
|
|
The `Identity` is built based on the OAuth2 Access Token that was sent along with the authorization request, and this construct has access to all claims
|
|
extracted from the original token. For example, if you are using a _Protocol Mapper_ to include a custom claim in an 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 to both the execution and runtime environments. 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
|
|
|
|
|===
|