174 lines
6.7 KiB
Plaintext
174 lines
6.7 KiB
Plaintext
---
|
||
title: Expression Policies
|
||
---
|
||
|
||
Expression policies are perhaps the most flexible way to define specific implementations of flows and stages. With Expression polices, you can provide Python code to enforce custom checks and validation.
|
||
|
||
The passing of the policy is determined by the return value of the code.
|
||
|
||
To pass a policy, use:
|
||
|
||
```python
|
||
return True
|
||
```
|
||
|
||
To fail a policy use:
|
||
|
||
```python
|
||
return False
|
||
```
|
||
|
||
**Example**:
|
||
Here's a simple policy that you could bind to a MFA validation stage if you want to specify that only certain users should be prompted for MFA validation:
|
||
|
||
```
|
||
if request.context["pending_user"].username == "marie":
|
||
return True
|
||
return False
|
||
```
|
||
|
||
If the return is `True` that means Yes, use this stage (i.e. the user will get the MFA prompt). A return of `False` means remove this stage from the plan.
|
||
|
||
## Available Functions
|
||
|
||
### `ak_message(message: str)`
|
||
|
||
Add a message, visible by the end user. This can be used to show the reason why they were denied.
|
||
|
||
Example:
|
||
|
||
```python
|
||
ak_message("Access denied")
|
||
return False
|
||
```
|
||
|
||
import Functions from "../../expressions/_functions.md";
|
||
|
||
<Functions />
|
||
|
||
## Variables
|
||
|
||
import Objects from "../../expressions/_objects.md";
|
||
|
||
<Objects />
|
||
|
||
- `request`: A PolicyRequest object, which has the following properties:
|
||
|
||
- `request.user`: The current user, against which the policy is applied. See [User](../../users-sources/user/index.mdx)
|
||
|
||
:::caution
|
||
When a policy is executed in the context of a flow, this will be set to the user initiaing request, and will only be changed by a `user_login` stage. For that reason, using this value in authentication flow policies may not return the expected user. Use `context['pending_user']` instead; User Identification and other stages update this value during flow execution.
|
||
|
||
If the user is not authenticated, this will be set to a user called _AnonymousUser_, which is an instance of [authentik.core.models.User](https://docs.djangoproject.com/en/4.1/ref/contrib/auth/#django.contrib.auth.models.User) (authentik uses django-guardian for per-object permissions, [see](https://django-guardian.readthedocs.io/en/stable/)).
|
||
:::
|
||
|
||
- `request.http_request`: The Django HTTP Request. See [Django documentation](https://docs.djangoproject.com/en/4.1/ref/request-response/#httprequest-objects).
|
||
- `request.obj`: A Django Model instance. This is only set if the policy is ran against an object.
|
||
- `request.context`: A dictionary with dynamic data. This depends on the origin of the execution.
|
||
|
||
- `geoip`: GeoIP dictionary. The following fields are available:
|
||
|
||
:::info
|
||
For basic country matching, consider using a [GeoIP policy](./index.md#geoip-policy).
|
||
:::
|
||
|
||
- `continent`: a two character continent code like `NA` (North America) or `OC` (Oceania).
|
||
- `country`: the two character [ISO 3166-1](https://en.wikipedia.org/wiki/ISO_3166-1) alpha code for the country.
|
||
- `lat`: the approximate latitude of the location associated with the IP address.
|
||
- `long`: the approximate longitude of the location associated with the IP address.
|
||
- `city`: the name of the city. May be empty.
|
||
|
||
```python
|
||
return context["geoip"]["continent"] == "EU"
|
||
```
|
||
|
||
- `asn`: ASN dictionary. The following fields are available:
|
||
|
||
:::info
|
||
For basic ASN matching, consider using a [GeoIP policy](./index.md#geoip-policy).
|
||
:::
|
||
|
||
- `asn`: the autonomous system number associated with the IP address.
|
||
- `as_org`: the organization associated with the registered autonomous system number for the IP address.
|
||
- `network`: the network associated with the record. In particular, this is the largest network where all of the fields except `ip_address` have the same value.
|
||
|
||
```python
|
||
return context["asn"]["asn"] == 64496
|
||
```
|
||
|
||
- `ak_is_sso_flow`: Boolean which is true if request was initiated by authenticating through an external provider.
|
||
- `ak_client_ip`: Client's IP Address or 255.255.255.255 if no IP Address could be extracted. Can be [compared](#comparing-ip-addresses), for example
|
||
|
||
```python
|
||
return ak_client_ip in ip_network('10.0.0.0/24')
|
||
# or
|
||
return ak_client_ip.is_private
|
||
```
|
||
|
||
See also [Python documentation](https://docs.python.org/3/library/ipaddress.html#ipaddress.ip_address)
|
||
|
||
Additionally, when the policy is executed from a flow, every variable from the flow's current context is accessible under the `context` object.
|
||
|
||
This includes the following:
|
||
|
||
- `context['flow_plan']`: The actual flow plan itself, can be used to inject stages.
|
||
|
||
- `context['flow_plan'].context`: The context of the currently active flow, which differs from the policy context. Some fields of flow plan context are passed to the root context, and updated from it, like 'prompt_data', but not every variable
|
||
- `context['flow_plan'].context['redirect']`: The URL the user should be redirected to after the flow execution succeeds. (Optional)
|
||
|
||
- `context['prompt_data']`: Data which has been saved from a prompt stage or an external source. (Optional)
|
||
- `context['application']`: The application the user is in the process of authorizing. (Optional)
|
||
- `context['source']`: The source the user is authenticating/enrolling with. (Optional)
|
||
- `context['pending_user']`: The currently pending user, see [User](../../users-sources/user/user_ref.md)
|
||
- `context['is_restored']`: Contains the flow token when the flow plan was restored from a link, for example the user clicked a link to a flow which was sent by an email stage. (Optional)
|
||
- `context['auth_method']`: Authentication method (this value is set by password stages) (Optional)
|
||
|
||
Depending on method, `context['auth_method_args']` is also set.
|
||
|
||
Can be any of:
|
||
|
||
- `password`: Standard password login
|
||
- `auth_mfa`: MFA login (this method is only set if no password was used)
|
||
|
||
Sets `context['auth_method_args']` to
|
||
|
||
```json
|
||
{
|
||
"mfa_devices": [
|
||
{
|
||
"pk": 1,
|
||
"app": "otp_static",
|
||
"name": "Static Token",
|
||
"model_name": "staticdevice"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
- `auth_webauthn_pwl`: Password-less WebAuthn login
|
||
- `jwt`: OAuth Machine-to-machine login via external JWT
|
||
- `app_password`: App password (token)
|
||
|
||
Sets `context['auth_method_args']` to
|
||
|
||
```json
|
||
{
|
||
"token": {
|
||
"pk": "f6d639aac81940f38dcfdc6e0fe2a786",
|
||
"app": "authentik_core",
|
||
"name": "test (expires=2021-08-23 15:45:54.725880+00:00)",
|
||
"model_name": "token"
|
||
}
|
||
}
|
||
```
|
||
|
||
- `ldap`: LDAP bind authentication
|
||
|
||
Sets `context['auth_method_args']` to
|
||
|
||
```json
|
||
{
|
||
"source": {} // Information about the source used
|
||
}
|
||
```
|