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:

Custom Filters: