From 1b82283a2005dcf16485f10d553f8a9d159be12b Mon Sep 17 00:00:00 2001
From: Jens Langhammer
Date: Wed, 19 Feb 2020 10:21:28 +0100
Subject: [PATCH] docs: update policy types, add docs for expression policies
---
docs/policies/expression/index.md | 19 ++++++++++++++++
docs/{policies.md => policies/index.md} | 22 ++-----------------
.../index.md} | 0
.../reference}/user-object.md | 0
docs/providers.md | 10 ++-------
docs/sources.md | 2 +-
mkdocs.yml | 12 +++++-----
.../templates/policy/expression/form.html | 5 +++--
8 files changed, 34 insertions(+), 36 deletions(-)
create mode 100644 docs/policies/expression/index.md
rename docs/{policies.md => policies/index.md} (79%)
rename docs/{property-mappings.md => property-mappings/index.md} (100%)
rename docs/{reference/property-mappings => property-mappings/reference}/user-object.md (100%)
diff --git a/docs/policies/expression/index.md b/docs/policies/expression/index.md
new file mode 100644
index 000000000..fea268056
--- /dev/null
+++ b/docs/policies/expression/index.md
@@ -0,0 +1,19 @@
+# Expression Policy
+
+Expression Policies allows you to write custom Policy Logic using Jinja2 Templating language.
+
+For a language reference, see [here](https://jinja.palletsprojects.com/en/2.11.x/templates/).
+
+The following objects are passed into the variable:
+
+- `request`: A PolicyRequest object, which has the following properties:
+ - `request.user`: The current User, which the Policy is applied against. ([ref](../../property-mappings/reference/user-object.md))
+ - `request.http_request`: The Django HTTP Request, as documented [here](https://docs.djangoproject.com/en/3.0/ref/request-response/#httprequest-objects).
+ - `request.obj`: A Django Model instance. This is only set if the Policy is ran against an object.
+- `pb_is_sso_flow`: Boolean which is true if request was initiated by authenticating through an external Provider.
+- `pb_is_group_member(user, group_name)`: Function which checks if `user` is member of a Group with Name `gorup_name`.
+
+There are also the following custom filters available:
+
+- `regex_match(regex)`: Return True if value matches `regex`
+- `regex_replace(regex, repl)`: Replace string matched by `regex` with `repl`
diff --git a/docs/policies.md b/docs/policies/index.md
similarity index 79%
rename from docs/policies.md
rename to docs/policies/index.md
index c6ed04109..b413a7794 100644
--- a/docs/policies.md
+++ b/docs/policies/index.md
@@ -18,27 +18,9 @@ passbook keeps track of failed login attempts by Source IP and Attempted Usernam
This policy can be used to for example prompt Clients with a low score to pass a Captcha before they can continue.
-### Field matcher Policy
+## Expression Policy
-This policy allows you to evaluate arbitrary comparisons against the User instance. Currently supported fields are:
-
-- Username
-- E-Mail
-- Name
-- Is_active
-- Date joined
-
-Any of the following operations are supported:
-
-- Starts with
-- Ends with
-- Contains
-- Regexp (standard Python engine)
-- Exact
-
-### SSO Policy
-
-This policy evaluates to True if the current Authentication Flow has been initiated through an external Source, like OAuth and SAML.
+See [Expression Policy](expression/index.md).
### Webhook Policy
diff --git a/docs/property-mappings.md b/docs/property-mappings/index.md
similarity index 100%
rename from docs/property-mappings.md
rename to docs/property-mappings/index.md
diff --git a/docs/reference/property-mappings/user-object.md b/docs/property-mappings/reference/user-object.md
similarity index 100%
rename from docs/reference/property-mappings/user-object.md
rename to docs/property-mappings/reference/user-object.md
diff --git a/docs/providers.md b/docs/providers.md
index dcefde902..e7504e532 100644
--- a/docs/providers.md
+++ b/docs/providers.md
@@ -13,11 +13,5 @@ The API exposes Username, E-Mail, Name and Groups in a GitHub-compatible format.
## SAML Provider
-This provider allows you to integrate Enterprise Software using the SAML2 Protocol. It supports signed Requests. This Provider also has [Property Mappings](property-mappings.md#saml-property-mapping), which allows you to expose Vendor-specific Fields.
-Default fields are:
-
-- `eduPersonPrincipalName`: User's E-Mail
-- `cn`: User's Full Name
-- `mail`: User's E-Mail
-- `displayName`: User's Username
-- `uid`: User Unique Identifier
+This provider allows you to integrate Enterprise Software using the SAML2 Protocol. It supports signed Requests. This Provider uses [Property Mappings](property-mappings/index.md#saml-property-mapping) to determine which fields are exposed and what values they return. This makes it possible to expose Vendor-specific Fields.
+Default fields are exposed through Auto-generated Property Mappings, which are prefixed with "Autogenerated..."
diff --git a/docs/sources.md b/docs/sources.md
index 66193eaf7..28c6e6bfd 100644
--- a/docs/sources.md
+++ b/docs/sources.md
@@ -36,4 +36,4 @@ This source allows you to import Users and Groups from an LDAP Server
- Object uniqueness field: Field which contains a unique Identifier.
- Sync groups: Enable/disable Group synchronization. Groups are synced in the background every 5 minutes.
- Sync parent group: Optionally set this Group as parent Group for all synced Groups (allows you to, for example, import AD Groups under a root `imported-from-ad` group.)
-- Property mappings: Define which LDAP Properties map to which passbook Properties. The default set of Property Mappings is generated for Active Directory. See also [LDAP Property Mappings](property-mappings.md#ldap-property-mapping)
+- Property mappings: Define which LDAP Properties map to which passbook Properties. The default set of Property Mappings is generated for Active Directory. See also [LDAP Property Mappings](property-mappings/index.md#ldap-property-mapping)
diff --git a/mkdocs.yml b/mkdocs.yml
index 6b390ef73..baf290709 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -10,9 +10,14 @@ nav:
- Kubernetes: installation/kubernetes.md
- Sources: sources.md
- Providers: providers.md
- - Property Mappings: property-mappings.md
+ - Property Mappings:
+ - Overview: property-mappings/index.md
+ - Reference:
+ - User Object: property-mappings/reference/user-object.md
- Factors: factors.md
- - Policies: policies.md
+ - Policies:
+ - Overview: policies/index.md
+ - Expression: policies/expression/index.md
- Integrations:
- as Provider:
- Amazon Web Services: integrations/services/aws/index.md
@@ -21,9 +26,6 @@ nav:
- Harbor: integrations/services/harbor/index.md
- Sentry: integrations/services/sentry/index.md
- Ansible Tower/AWX: integrations/services/tower-awx/index.md
- - Reference:
- - Property Mappings:
- - User Object: reference/property-mappings/user-object.md
repo_name: "BeryJu.org/passbook"
repo_url: https://github.com/BeryJu/passbook
diff --git a/passbook/policies/expression/templates/policy/expression/form.html b/passbook/policies/expression/templates/policy/expression/form.html
index 18c23b321..9a8a063c6 100644
--- a/passbook/policies/expression/templates/policy/expression/form.html
+++ b/passbook/policies/expression/templates/policy/expression/form.html
@@ -11,10 +11,11 @@
Expression using Jinja. Following variables are available:
- request.user
: Passbook User Object (Reference)
+ request.user
: Passbook User Object (Reference)
request.http_request
: Django HTTP Request Object (Reference)
request.obj
: Model the Policy is run against.
- pb_is_sso_flow
: Boolean which is true if request was initiated by by Authenticating through an external Provider.
+ pb_is_sso_flow
: Boolean which is true if request was initiated by authenticating through an external Provider.
+ pb_is_group_member(user, group_name)
: Function which checks if user
is member of a Group with Name group_name
.
Custom Filters: