This repository has been archived on 2024-05-31. You can view files and clone it, but cannot push or open issues or pull requests.
authentik/website/docs/policies/expression.mdx

153 lines
5.6 KiB
Plaintext
Raw Normal View History

---
title: Expression Policies
---
The passing of the policy is determined by the return value of the code. Use
```python
return True
```
to pass a policy and
```python
return False
```
to fail it.
## 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
2020-12-05 21:08:42 +00:00
ak_message("Access denied")
return False
```
### `ak_call_policy(name: str, **kwargs) -> PolicyResult`
:::info
Requires authentik 2021.12
:::
Call another policy with the name _name_. Current request is passed to policy. Key-word arguments
can be used to modify the request's context.
Example:
```python
result = ak_call_policy("test-policy")
# result is a PolicyResult object, so you can access `.passing` and `.messages`.
return result.passing
result = ak_call_policy("test-policy-2", foo="bar")
# Inside the `test-policy-2` you can then use `request.context["foo"]`
return result.passing
```
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](../user-group/user.md#object-attributes)
:::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 object, see [GeoIP](https://geoip2.readthedocs.io/en/latest/#geoip2.models.City)
- `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
2020-12-05 21:08:42 +00:00
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](../user-group/user.md#object-attributes)
- `context['is_restored']`: Set to `True` when the flow plan has been restored from a flow token, 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
}
```