new release: 0.12.1-stable

Bumps [sentry-sdk](https://github.com/getsentry/sentry-python) from 0.19.0 to 0.19.1.
- [Release notes](https://github.com/getsentry/sentry-python/releases)
- [Changelog](https://github.com/getsentry/sentry-python/blob/master/CHANGES.md)
- [Commits](https://github.com/getsentry/sentry-python/compare/0.19.0...0.19.1)

Signed-off-by: dependabot[bot] <support@github.com>

Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>

.bumpversion.cfg

@@ -1,5 +1,5 @@
 [bumpversion]
-current_version = 0.4.0-beta
+current_version = 0.12.1-stable
 tag = True
 commit = True
 parse = (?P<major>\d+)\.(?P<minor>\d+)\.(?P<patch>\d+)\-(?P<release>.*)
@@ -15,13 +15,18 @@ values =
 	beta
 	stable
 
-[bumpversion:file:helm/passbook/values.yaml]
+[bumpversion:file:docs/installation/docker-compose.md]
 
-[bumpversion:file:helm/passbook/Chart.yaml]
+[bumpversion:file:docs/installation/kubernetes.md]
 
-[bumpversion:file:.gitlab-ci.yml]
+[bumpversion:file:docker-compose.yml]
+
+[bumpversion:file:helm/values.yaml]
+
+[bumpversion:file:helm/Chart.yaml]
+
+[bumpversion:file:.github/workflows/release.yml]
 
 [bumpversion:file:passbook/__init__.py]
 
-[bumpversion:file:passbook/core/nginx.conf]
+[bumpversion:file:proxy/pkg/version.go]
-

.coveragerc

@@ -1,13 +1,11 @@
 [run]
 source = passbook
+relative_files = true
 omit =
-    env/
+    */asgi.py
-    */wsgi.py
     manage.py
     */migrations/*
     */apps.py
-    passbook/management/commands/web.py
-    passbook/management/commands/worker.py
     docs/
 
 [report]
@@ -22,6 +20,7 @@ exclude_lines =
     def __str__
     def __repr__
     if self\.debug
+    if TYPE_CHECKING
 
     # Don't complain if tests don't hit defensive assertion code:
     raise AssertionError

.dockerignore

@@ -2,3 +2,5 @@ env
 helm
 passbook-ui
 static
+*.env.yml
+node_modules/

.github/FUNDING.yml

@@ -0,0 +1 @@
+custom: ["https://www.paypal.me/beryju"]

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,34 @@
+---
+name: Bug report
+about: Create a report to help us improve
+title: ''
+labels: bug
+assignees: ''
+
+---
+
+**Describe the bug**
+A clear and concise description of what the bug is.
+
+**To Reproduce**
+Steps to reproduce the behavior:
+1. Go to '...'
+2. Click on '....'
+3. Scroll down to '....'
+4. See error
+
+**Expected behavior**
+A clear and concise description of what you expected to happen.
+
+**Screenshots**
+If applicable, add screenshots to help explain your problem.
+
+**Logs**
+Output of docker-compose logs or kubectl logs respectively
+
+**Version and Deployment (please complete the following information):**
+ - passbook version: [e.g. 0.10.0-stable]
+ - Deployment: [e.g. docker-compose, helm]
+
+**Additional context**
+Add any other context about the problem here.

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,20 @@
+---
+name: Feature request
+about: Suggest an idea for this project
+title: ''
+labels: enhancement
+assignees: ''
+
+---
+
+**Is your feature request related to a problem? Please describe.**
+A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+
+**Describe the solution you'd like**
+A clear and concise description of what you want to happen.
+
+**Describe alternatives you've considered**
+A clear and concise description of any alternative solutions or features you've considered.
+
+**Additional context**
+Add any other context or screenshots about the feature request here.

.github/dependabot.yml

@@ -0,0 +1,26 @@
+version: 2
+updates:
+- package-ecosystem: gomod
+  directory: "/proxy"
+  schedule:
+    interval: daily
+    time: "04:00"
+  open-pull-requests-limit: 10
+  assignees:
+  - BeryJu
+- package-ecosystem: npm
+  directory: "/passbook/static/static"
+  schedule:
+    interval: daily
+    time: "04:00"
+  open-pull-requests-limit: 10
+  assignees:
+  - BeryJu
+- package-ecosystem: pip
+  directory: "/"
+  schedule:
+    interval: daily
+    time: "04:00"
+  open-pull-requests-limit: 10
+  assignees:
+  - BeryJu

.github/workflows/release.yml

@@ -0,0 +1,118 @@
+name: passbook-on-release
+
+on:
+  release:
+    types: [published, created]
+
+jobs:
+  # Build
+  build-server:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v1
+      - name: Docker Login Registry
+        env:
+          DOCKER_PASSWORD: ${{ secrets.DOCKER_PASSWORD }}
+          DOCKER_USERNAME: ${{ secrets.DOCKER_USERNAME }}
+        run: docker login -u $DOCKER_USERNAME -p $DOCKER_PASSWORD
+      - name: Building Docker Image
+        run: docker build
+          --no-cache
+          -t beryju/passbook:0.12.1-stable
+          -t beryju/passbook:latest
+          -f Dockerfile .
+      - name: Push Docker Container to Registry (versioned)
+        run: docker push beryju/passbook:0.12.1-stable
+      - name: Push Docker Container to Registry (latest)
+        run: docker push beryju/passbook:latest
+  build-proxy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v1
+      - uses: actions/setup-go@v2
+        with:
+          go-version: "^1.15"
+      - name: prepare go api client
+        run: |
+          cd proxy
+          go get -u github.com/go-swagger/go-swagger/cmd/swagger
+          swagger generate client -f ../swagger.yaml -A passbook -t pkg/
+          go build -v .
+      - name: Docker Login Registry
+        env:
+          DOCKER_PASSWORD: ${{ secrets.DOCKER_PASSWORD }}
+          DOCKER_USERNAME: ${{ secrets.DOCKER_USERNAME }}
+        run: docker login -u $DOCKER_USERNAME -p $DOCKER_PASSWORD
+      - name: Building Docker Image
+        run: |
+          cd proxy
+          docker build \
+          --no-cache \
+          -t beryju/passbook-proxy:0.12.1-stable \
+          -t beryju/passbook-proxy:latest \
+          -f Dockerfile .
+      - name: Push Docker Container to Registry (versioned)
+        run: docker push beryju/passbook-proxy:0.12.1-stable
+      - name: Push Docker Container to Registry (latest)
+        run: docker push beryju/passbook-proxy:latest
+  build-static:
+    runs-on: ubuntu-latest
+    services:
+      postgres:
+        image: postgres:latest
+        env:
+          POSTGRES_DB: passbook
+          POSTGRES_USER: passbook
+          POSTGRES_PASSWORD: "EK-5jnKfjrGRm<77"
+      redis:
+        image: redis:latest
+    steps:
+      - uses: actions/checkout@v1
+      - name: Docker Login Registry
+        env:
+          DOCKER_PASSWORD: ${{ secrets.DOCKER_PASSWORD }}
+          DOCKER_USERNAME: ${{ secrets.DOCKER_USERNAME }}
+        run: docker login -u $DOCKER_USERNAME -p $DOCKER_PASSWORD
+      - name: Building Docker Image
+        run: docker build
+          --no-cache
+          --network=$(docker network ls | grep github | awk '{print $1}')
+          -t beryju/passbook-static:0.12.1-stable
+          -t beryju/passbook-static:latest
+          -f static.Dockerfile .
+      - name: Push Docker Container to Registry (versioned)
+        run: docker push beryju/passbook-static:0.12.1-stable
+      - name: Push Docker Container to Registry (latest)
+        run: docker push beryju/passbook-static:latest
+  test-release:
+    needs:
+      - build-server
+      - build-static
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v1
+      - name: Run test suite in final docker images
+        run: |
+          sudo apt-get install -y pwgen
+          echo "PG_PASS=$(pwgen 40 1)" >> .env
+          echo "PASSBOOK_SECRET_KEY=$(pwgen 50 1)" >> .env
+          docker-compose pull -q
+          docker-compose up --no-start
+          docker-compose start postgresql redis
+          docker-compose run -u root --entrypoint /bin/bash server -c "pip install --no-cache -r requirements-dev.txt && ./manage.py test passbook"
+  sentry-release:
+    needs:
+      - test-release
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v1
+      - name: Create a Sentry.io release
+        uses: tclindner/sentry-releases-action@v1.2.0
+        env:
+          SENTRY_AUTH_TOKEN: ${{ secrets.SENTRY_AUTH_TOKEN }}
+          SENTRY_ORG: beryjuorg
+          SENTRY_PROJECT: passbook
+          SENTRY_URL: https://sentry.beryju.org
+        with:
+          tagName: 0.12.1-stable
+          environment: beryjuorg-prod

.github/workflows/tag.yml

@@ -0,0 +1,63 @@
+name: passbook-on-tag
+
+on:
+  push:
+    tags:
+    - 'version/*'
+
+jobs:
+  build:
+    name: Create Release from Tag
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@master
+      - name: Pre-release test
+        run: |
+          sudo apt-get install -y pwgen
+          echo "PASSBOOK_TAG=latest" >> .env
+          echo "PG_PASS=$(pwgen 40 1)" >> .env
+          echo "PASSBOOK_SECRET_KEY=$(pwgen 50 1)" >> .env
+          docker-compose pull -q
+          docker build \
+            --no-cache \
+            -t beryju/passbook:latest \
+            -f Dockerfile .
+          docker-compose up --no-start
+          docker-compose start postgresql redis
+          docker-compose run -u root --entrypoint /bin/bash server -c "pip install --no-cache -r requirements-dev.txt && ./manage.py test passbook"
+      - name: Install Helm
+        run: |
+          apt update && apt install -y curl
+          curl https://raw.githubusercontent.com/helm/helm/master/scripts/get-helm-3 | bash
+      - name: Helm package
+        run: |
+          helm dependency update helm/
+          helm package helm/
+          mv passbook-*.tgz passbook-chart.tgz
+      - name: Extract version number
+        id: get_version
+        uses: actions/github-script@0.2.0
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          script: |
+            return context.payload.ref.replace(/\/refs\/tags\/version\//, '');
+      - name: Create Release
+        id: create_release
+        uses: actions/create-release@v1.0.0
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          tag_name: ${{ github.ref }}
+          release_name: Release ${{ steps.get_version.outputs.result }}
+          draft: true
+          prerelease: false
+      - name: Upload packaged Helm Chart
+        id: upload-release-asset
+        uses: actions/upload-release-asset@v1.0.1
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          upload_url: ${{ steps.create_release.outputs.upload_url }}
+          asset_path: ./passbook-chart.tgz
+          asset_name: passbook-chart.tgz
+          asset_content_type: application/gzip

.gitignore

@@ -63,6 +63,7 @@ coverage.xml
 *.cover
 .hypothesis/
 .pytest_cache/
+unittest.xml
 
 # Translations
 *.mo
@@ -184,7 +185,6 @@ dmypy.json
 [Ii]nclude
 [Ll]ib64
 [Ll]ocal
-[Ss]cripts
 pyvenv.cfg
 pip-selfcheck.json
 
@@ -192,3 +192,10 @@ pip-selfcheck.json
 /static/
 local.env.yml
 .vscode/
+
+### Helm ###
+# Chart dependencies
+**/charts/*.tgz
+
+# Selenium Screenshots
+selenium_screenshots/**

.gitlab-ci.yml

@@ -1,135 +0,0 @@
-# Global Variables
-stages:
-  - build-base-image
-  - build-dev-image
-  - test
-  - build
-  - package
-image: docker.beryju.org/passbook/dev:latest
-
-variables:
-  POSTGRES_DB: passbook
-  POSTGRES_USER: passbook
-  POSTGRES_PASSWORD: "EK-5jnKfjrGRm<77"
-
-before_script:
-  - pip install pipenv
-  # Ensure all dependencies are installed, even those not included in passbook/dev
-  # According to pipenv docs, -d outputs all packages, however it actually does not
-  - pipenv lock -r > requirements-all.txt
-  - pipenv lock -rd >> requirements-all.txt
-  - pip install -r requirements-all.txt
-
-create-base-image:
-  image:
-    name: gcr.io/kaniko-project/executor:debug
-    entrypoint: [""]
-  before_script:
-    - echo "{\"auths\":{\"docker.beryju.org\":{\"auth\":\"$DOCKER_AUTH\"}}}" > /kaniko/.docker/config.json
-  script:
-    - /kaniko/executor --context $CI_PROJECT_DIR --dockerfile $CI_PROJECT_DIR/base.Dockerfile --destination docker.beryju.org/passbook/base:latest --destination docker.beryju.org/passbook/base:0.4.0-beta
-  stage: build-base-image
-  only:
-    refs:
-      - tags
-      - /^version/.*$/
-
-build-dev-image:
-  image:
-    name: gcr.io/kaniko-project/executor:debug
-    entrypoint: [""]
-  before_script:
-    - echo "{\"auths\":{\"docker.beryju.org\":{\"auth\":\"$DOCKER_AUTH\"}}}" > /kaniko/.docker/config.json
-  script:
-    - /kaniko/executor --context $CI_PROJECT_DIR --dockerfile $CI_PROJECT_DIR/dev.Dockerfile --destination docker.beryju.org/passbook/dev:latest --destination docker.beryju.org/passbook/dev:0.4.0-beta
-  stage: build-dev-image
-  only:
-    refs:
-      - tags
-      - /^version/.*$/
-
-
-isort:
-  script:
-    - isort -c -sg env
-  stage: test
-  services:
-  - postgres:latest
-  - redis:latest
-migrations:
-  script:
-    - python manage.py migrate
-  stage: test
-  services:
-  - postgres:latest
-  - redis:latest
-# prospector:
-#   script:
-#     - prospector
-#   stage: test
-#   services:
-#   - postgres:latest
-#   - redis:latest
-# pylint:
-#   script:
-#     - pylint passbook
-#   stage: test
-#   services:
-#   - postgres:latest
-#   - redis:latest
-coverage:
-  script:
-    - coverage run manage.py test
-    - coverage report
-    - coverage html
-  stage: test
-  services:
-  - postgres:latest
-  - redis:latest
-
-package-passbook-server:
-  image:
-    name: gcr.io/kaniko-project/executor:debug
-    entrypoint: [""]
-  before_script:
-    - echo "{\"auths\":{\"docker.beryju.org\":{\"auth\":\"$DOCKER_AUTH\"}}}" > /kaniko/.docker/config.json
-  script:
-    - /kaniko/executor --context $CI_PROJECT_DIR --dockerfile $CI_PROJECT_DIR/Dockerfile --destination docker.beryju.org/passbook/server:latest --destination docker.beryju.org/passbook/server:0.4.0-beta
-  stage: build
-  only:
-    - tags
-    - /^version/.*$/
-build-passbook-static:
-  stage: build
-  image:
-    name: gcr.io/kaniko-project/executor:debug
-    entrypoint: [""]
-  before_script:
-    - echo "{\"auths\":{\"docker.beryju.org\":{\"auth\":\"$DOCKER_AUTH\"}}}" > /kaniko/.docker/config.json
-  script:
-    - /kaniko/executor --context $CI_PROJECT_DIR --dockerfile $CI_PROJECT_DIR/static.Dockerfile --destination docker.beryju.org/passbook/static:latest --destination docker.beryju.org/passbook/static:0.4.0-beta
-  only:
-    - tags
-    - /^version/.*$/
-  # running collectstatic fully initialises django, hence we need that databases
-  services:
-    - postgres:latest
-    - redis:latest
-
-package-helm:
-  image: debian:stretch-slim
-  stage: package
-  before_script:
-    - apt update && apt install -y curl
-    - curl https://raw.githubusercontent.com/helm/helm/master/scripts/get | bash
-  script:
-    - helm init --client-only
-    - helm dependency build helm/passbook
-    - helm package helm/passbook
-  artifacts:
-    paths:
-      - passbook-*.tgz
-    expire_in: 1 week
-  only:
-    - tags
-    - /^version/.*$/

.isort.cfg

@@ -0,0 +1,6 @@
+[settings]
+multi_line_output=3
+include_trailing_comma=True
+force_grid_wrap=0
+use_parentheses=True
+line_length=88

.prospector.yaml

@@ -3,11 +3,9 @@ test-warnings: true
 doc-warnings: false
 
 ignore-paths:
-  - env
   - migrations
   - docs
   - node_modules
-  - client-packages
 
 uses:
- - django
+  - django

.pylintrc

@@ -1,12 +1,16 @@
 [MASTER]
 
-disable=redefined-outer-name,arguments-differ,no-self-use,cyclic-import,fixme,locally-disabled,unpacking-non-sequence,too-many-ancestors,too-many-branches,too-few-public-methods
+disable=arguments-differ,no-self-use,fixme,locally-disabled,too-many-ancestors,too-few-public-methods,import-outside-toplevel,bad-continuation,signature-differs,similarities,cyclic-import
+
 load-plugins=pylint_django,pylint.extensions.bad_builtin
-#,pylint.extensions.docparams
+
 extension-pkg-whitelist=lxml
+
+# Allow constants to be shorter than normal (and lowercase, for settings.py)
 const-rgx=[a-zA-Z0-9_]{1,40}$
 
-[SIMILARITIES]
+ignored-modules=django-otp
+ignore=migrations
+max-attributes=12
 
-# Minimum lines number of a similarity.
+jobs=12
-min-similarity-lines=20

Dockerfile

@@ -1,8 +1,36 @@
-FROM docker.beryju.org/passbook/base:latest
+FROM python:3.8-slim-buster as locker
 
-COPY ./passbook/ /app/passbook
+COPY ./Pipfile /app/
-COPY ./manage.py /app/
+COPY ./Pipfile.lock /app/
+
+WORKDIR /app/
+
+RUN pip install pipenv && \
+    pipenv lock -r > requirements.txt && \
+    pipenv lock -rd > requirements-dev.txt
+
+FROM python:3.8-slim-buster
+
+WORKDIR /
+COPY --from=locker /app/requirements.txt /
+COPY --from=locker /app/requirements-dev.txt /
+
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends curl ca-certificates gnupg && \
+    curl https://www.postgresql.org/media/keys/ACCC4CF8.asc | apt-key add - && \
+    echo "deb http://apt.postgresql.org/pub/repos/apt buster-pgdg main" > /etc/apt/sources.list.d/pgdg.list && \
+    apt-get update && \
+    apt-get install -y --no-install-recommends postgresql-client-12 postgresql-client-11 build-essential && \
+    apt-get clean && \
+    pip install -r /requirements.txt --no-cache-dir && \
+    apt-get remove --purge -y build-essential && \
+    apt-get autoremove --purge -y && \
+    adduser --system --no-create-home --uid 1000 --group --home /passbook passbook
+
+COPY ./passbook/ /passbook
+COPY ./manage.py /
+COPY ./lifecycle/ /lifecycle
 
 USER passbook
 
-WORKDIR /app/
+ENTRYPOINT [ "/lifecycle/bootstrap.sh" ]

Makefile

@@ -0,0 +1,26 @@
+all: lint-fix lint coverage gen
+
+coverage:
+	coverage run --concurrency=multiprocessing manage.py test --failfast -v 3
+	coverage combine
+	coverage html
+	coverage report
+
+lint-fix:
+	isort -rc .
+	black passbook e2e lifecycle
+
+lint:
+	pyright passbook e2e lifecycle
+	bandit -r passbook e2e lifecycle
+	pylint passbook e2e lifecycle
+	prospector
+
+gen: coverage
+	./manage.py generate_swagger -o swagger.yaml -f yaml
+
+local-stack:
+	export PASSBOOK_TAG=testing
+	docker build -t beryju/passbook:testng .
+	docker-compose up -d
+	docker-compose run --rm server migrate

Pipfile

@@ -4,59 +4,61 @@ url = "https://pypi.org/simple"
 verify_ssl = true
 
 [packages]
-asgiref = "*"
+boto3 = "*"
-beautifulsoup4 = "*"
 celery = "*"
-channels = "*"
-cherrypy = "*"
-colorlog = "*"
-daphne = "*"
 defusedxml = "*"
 django = "*"
 django-cors-middleware = "*"
-django-filters = "*"
+django-dbbackup = "*"
-django-ipware = "*"
+django-filter = "*"
+django-guardian = "*"
 django-model-utils = "*"
-django-oauth-toolkit = "*"
-django-oidc-provider = "*"
 django-otp = "*"
+django-prometheus = "*"
 django-recaptcha = "*"
 django-redis = "*"
-django-rest-framework = "*"
+djangorestframework = "*"
-django-revproxy = "*"
+django-storages = "*"
-djangorestframework = "==3.9.4"
+djangorestframework-guardian = "*"
-drf-yasg = "*"
+drf_yasg2 = "*"
+facebook-sdk = "*"
 ldap3 = "*"
 lxml = "*"
-markdown = "*"
-oauthlib = "*"
 packaging = "*"
-psycopg2 = "*"
+psycopg2-binary = "*"
 pycryptodome = "*"
+pyjwkest = "*"
+uvicorn = {extras = ["standard"],version = "*"}
+gunicorn = "*"
 pyyaml = "*"
 qrcode = "*"
 requests-oauthlib = "*"
 sentry-sdk = "*"
 service_identity = "*"
 signxml = "*"
-urllib3 = {extras = ["secure"],version = "*"}
-websocket_client = "*"
 structlog = "*"
-uwsgi = "*"
+swagger-spec-validator = "*"
+urllib3 = {extras = ["secure"],version = "*"}
+dacite = "*"
+channels = "*"
+channels-redis = "*"
+kubernetes = "*"
+docker = "*"
 
 [requires]
-python_version = "3.7"
+python_version = "3.8"
 
 [dev-packages]
-astroid = "==2.2.5"
-coverage = "*"
-isort = "*"
-pylint = "==2.3.1"
-pylint-django = "==2.0.10"
-prospector = "==1.1.7"
-django-debug-toolbar = "*"
-bumpversion = "*"
-unittest-xml-reporting = "*"
 autopep8 = "*"
 bandit = "*"
+black = "==20.8b1"
+bumpversion = "*"
 colorama = "*"
+coverage = "*"
+django-debug-toolbar = "*"
+pylint = "*"
+pylint-django = "*"
+selenium = "*"
+prospector = "*"
+pytest = "*"
+pytest-django = "*"

README.md

@@ -0,0 +1,54 @@
+<img src="docs/images/logo.svg" height="50" alt="passbook logo"><img src="docs/images/brand_inverted.svg" height="50" alt="passbook">
+
+[![CI Build status](https://img.shields.io/azure-devops/build/beryjuorg/passbook/1?style=flat-square)](https://dev.azure.com/beryjuorg/passbook/_build?definitionId=1)
+![Tests](https://img.shields.io/azure-devops/tests/beryjuorg/passbook/1?compact_message&style=flat-square)
+[![Code Coverage](https://img.shields.io/codecov/c/gh/beryju/passbook?style=flat-square)](https://codecov.io/gh/BeryJu/passbook)
+![Docker pulls](https://img.shields.io/docker/pulls/beryju/passbook.svg?style=flat-square)
+![Latest version](https://img.shields.io/docker/v/beryju/passbook?sort=semver&style=flat-square)
+![LGTM Grade](https://img.shields.io/lgtm/grade/python/github/BeryJu/passbook?style=flat-square)
+
+## What is passbook?
+
+passbook is an open-source Identity Provider focused on flexibility and versatility. You can use passbook in an existing environment to add support for new protocols. passbook is also a great solution for implementing signup/recovery/etc in your application, so you don't have to deal with it.
+
+## Installation
+
+For small/test setups it is recommended to use docker-compose, see the [documentation](https://passbook.beryju.org/installation/docker-compose/)
+
+For bigger setups, there is a Helm Chart in the `helm/` directory. This is documented [here](https://passbook.beryju.org//installation/kubernetes/)
+
+## Screenshots
+
+![](docs/images/screen_apps.png)
+![](docs/images/screen_admin.png)
+
+## Development
+
+To develop on passbook, you need a system with Python 3.7+ (3.8 is recommended). passbook uses [pipenv](https://pipenv.pypa.io/en/latest/) for managing dependencies.
+
+To get started, run
+
+```
+python3 -m pip install pipenv
+git clone https://github.com/BeryJu/passbook.git
+cd passbook
+pipenv shell
+pipenv sync -d
+```
+
+Since passbook uses PostgreSQL-specific fields, you also need a local PostgreSQL instance to develop. passbook also uses redis for caching and message queueing.
+For these databases you can use [Postgres.app](https://postgresapp.com/) and [Redis.app](https://jpadilla.github.io/redisapp/) on macOS or use it the docker-compose file in `scripts/docker-compose.yml`.
+
+To tell passbook about these databases, create a file in the project root called `local.env.yml` with the following contents:
+
+```yaml
+debug: true
+postgresql:
+  user: postgres
+
+log_level: debug
+```
+
+## Security
+
+See [SECURITY.md](SECURITY.md)

SECURITY.md

@@ -0,0 +1,15 @@
+# Security Policy
+
+## Supported Versions
+
+As passbook is currently in a pre-stable, only the latest "stable" version is supported. After passbook 1.0, this will change.
+
+| Version  | Supported          |
+| -------- | ------------------ |
+| 0.10.x   | :white_check_mark: |
+| 0.11.x   | :white_check_mark: |
+| 0.12.x   | :white_check_mark: |
+
+## Reporting a Vulnerability
+
+To report a vulnerability, send an email to [security@beryju.org](mailto:security@beryju.org)

azure-pipelines.yml

@@ -0,0 +1,352 @@
+trigger:
+  - master
+
+resources:
+  - repo: self
+
+variables:
+  POSTGRES_DB: passbook
+  POSTGRES_USER: passbook
+  POSTGRES_PASSWORD: "EK-5jnKfjrGRm<77"
+  ${{ if startsWith(variables['Build.SourceBranch'], 'refs/heads/') }}:
+    branchName: ${{ replace(variables['Build.SourceBranchName'], 'refs/heads/', '') }}
+  ${{ if startsWith(variables['Build.SourceBranch'], 'refs/pull/') }}:
+    branchName: ${{ replace(variables['System.PullRequest.SourceBranch'], 'refs/heads/', '') }}
+
+stages:
+  - stage: Lint
+    jobs:
+      - job: pylint
+        pool:
+          vmImage: 'ubuntu-latest'
+        steps:
+          - task: UsePythonVersion@0
+            inputs:
+              versionSpec: '3.8'
+          - task: CmdLine@2
+            inputs:
+              script: |
+                sudo pip install -U wheel pipenv
+                pipenv install --dev
+          - task: CmdLine@2
+            inputs:
+              script: pipenv run pylint passbook e2e lifecycle
+      - job: black
+        pool:
+          vmImage: 'ubuntu-latest'
+        steps:
+          - task: UsePythonVersion@0
+            inputs:
+              versionSpec: '3.8'
+          - task: CmdLine@2
+            inputs:
+              script: |
+                sudo pip install -U wheel pipenv
+                pipenv install --dev
+          - task: CmdLine@2
+            inputs:
+              script: pipenv run black --check passbook e2e lifecycle
+      - job: prospector
+        pool:
+          vmImage: 'ubuntu-latest'
+        steps:
+          - task: UsePythonVersion@0
+            inputs:
+              versionSpec: '3.8'
+          - task: CmdLine@2
+            inputs:
+              script: |
+                sudo pip install -U wheel pipenv
+                pipenv install --dev
+                pipenv install --dev prospector --skip-lock
+          - task: CmdLine@2
+            inputs:
+              script: pipenv run prospector
+      - job: bandit
+        pool:
+          vmImage: 'ubuntu-latest'
+        steps:
+          - task: UsePythonVersion@0
+            inputs:
+              versionSpec: '3.8'
+          - task: CmdLine@2
+            inputs:
+              script: |
+                sudo pip install -U wheel pipenv
+                pipenv install --dev
+          - task: CmdLine@2
+            inputs:
+              script: pipenv run bandit -r passbook e2e lifecycle
+      - job: pyright
+        pool:
+          vmImage: ubuntu-latest
+        steps:
+          - task: UseNode@1
+            inputs:
+              version: '12.x'
+          - task: UsePythonVersion@0
+            inputs:
+              versionSpec: '3.8'
+          - task: CmdLine@2
+            inputs:
+              script: npm install -g pyright@1.1.79
+          - task: CmdLine@2
+            inputs:
+              script: |
+                sudo pip install -U wheel pipenv
+                pipenv install --dev
+          - task: CmdLine@2
+            inputs:
+              script: pipenv run pyright e2e lifecycle
+  - stage: Test
+    jobs:
+      - job: migrations
+        pool:
+          vmImage: 'ubuntu-latest'
+        steps:
+          - task: UsePythonVersion@0
+            inputs:
+              versionSpec: '3.8'
+          - task: DockerCompose@0
+            displayName: Run services
+            inputs:
+              dockerComposeFile: 'scripts/ci.docker-compose.yml'
+              action: 'Run services'
+              buildImages: false
+          - task: CmdLine@2
+            inputs:
+              script: |
+                sudo pip install -U wheel pipenv
+                pipenv install --dev
+          - task: CmdLine@2
+            inputs:
+              script: pipenv run ./manage.py migrate
+      - job: migrations_from_previous_release
+        pool:
+          vmImage: 'ubuntu-latest'
+        steps:
+          - task: UsePythonVersion@0
+            inputs:
+              versionSpec: '3.8'
+          - task: DockerCompose@0
+            displayName: Run services
+            inputs:
+              dockerComposeFile: 'scripts/ci.docker-compose.yml'
+              action: 'Run services'
+              buildImages: false
+          - task: CmdLine@2
+            displayName: Prepare Last tagged release
+            inputs:
+              script: |
+                git checkout $(git describe --abbrev=0 --match 'version/*')
+                sudo pip install -U wheel pipenv
+                pipenv install --dev
+          - task: CmdLine@2
+            displayName: Migrate to last tagged release
+            inputs:
+              script: pipenv run ./manage.py migrate
+          - task: CmdLine@2
+            displayName: Install current branch
+            inputs:
+              script: |
+                set -x
+                git checkout ${{ variables.branchName }}
+                pipenv sync --dev
+          - task: CmdLine@2
+            displayName: Migrate to current branch
+            inputs:
+              script: pipenv run ./manage.py migrate
+      - job: coverage_unittest
+        pool:
+          vmImage: 'ubuntu-latest'
+        steps:
+          - task: UsePythonVersion@0
+            inputs:
+              versionSpec: '3.8'
+          - task: DockerCompose@0
+            displayName: Run services
+            inputs:
+              dockerComposeFile: 'scripts/ci.docker-compose.yml'
+              action: 'Run services'
+              buildImages: false
+          - task: CmdLine@2
+            displayName: Install K3d and prepare
+            inputs:
+              script: |
+                wget -q -O - https://raw.githubusercontent.com/rancher/k3d/main/install.sh | bash
+                k3d cluster create
+                k3d kubeconfig write -o ~/.kube/config --overwrite
+          - task: CmdLine@2
+            inputs:
+              script: |
+                sudo pip install -U wheel pipenv
+                pipenv install --dev
+          - task: CmdLine@2
+            displayName: Run full test suite
+            inputs:
+              script: |
+                export PB_TEST_K8S=true
+                pipenv run coverage run ./manage.py test passbook -v 3
+          - task: CmdLine@2
+            inputs:
+              script: |
+                mkdir output-unittest
+                mv unittest.xml output-unittest/unittest.xml
+                mv .coverage output-unittest/coverage
+          - task: PublishPipelineArtifact@1
+            inputs:
+              targetPath: 'output-unittest/'
+              artifact: 'coverage-unittest'
+              publishLocation: 'pipeline'
+      - job: coverage_e2e
+        pool:
+          name: coventry
+        steps:
+          - task: UsePythonVersion@0
+            inputs:
+              versionSpec: '3.8'
+          - task: DockerCompose@0
+            displayName: Run services
+            inputs:
+              dockerComposeFile: 'scripts/ci.docker-compose.yml'
+              action: 'Run services'
+              buildImages: false
+          - task: CmdLine@2
+            displayName: Install K3d and prepare
+            inputs:
+              script: |
+                wget -q -O - https://raw.githubusercontent.com/rancher/k3d/main/install.sh | bash
+                k3d cluster create
+                k3d kubeconfig write -o ~/.kube/config --overwrite
+          - task: CmdLine@2
+            inputs:
+              script: |
+                sudo pip install -U wheel pipenv
+                pipenv install --dev
+          - task: DockerCompose@0
+            displayName: Run ChromeDriver
+            inputs:
+              dockerComposeFile: 'e2e/ci.docker-compose.yml'
+              action: 'Run a specific service'
+              serviceName: 'chrome'
+          - task: CmdLine@2
+            displayName: Build static files for e2e
+            inputs:
+              script: |
+                cd passbook/static/static
+                npm i
+                npm run build
+          - task: CmdLine@2
+            displayName: Run full test suite
+            inputs:
+              script: |
+                export PB_TEST_K8S=true
+                pipenv run coverage run ./manage.py test e2e -v 3 --failfast
+          - task: CmdLine@2
+            condition: always()
+            displayName: Cleanup
+            inputs:
+              script: |
+                docker stop $(docker ps -aq)
+                docker container prune -f
+          - task: CmdLine@2
+            displayName: Prepare unittests and coverage for upload
+            inputs:
+              script: |
+                mkdir output-e2e
+                mv unittest.xml output-e2e/unittest.xml
+                mv .coverage output-e2e/coverage
+          - task: PublishPipelineArtifact@1
+            condition: failed()
+            displayName: Upload screenshots if selenium tests fail
+            inputs:
+              targetPath: 'selenium_screenshots/'
+              artifact: 'selenium screenshots'
+              publishLocation: 'pipeline'
+          - task: PublishPipelineArtifact@1
+            inputs:
+              targetPath: 'output-e2e/'
+              artifact: 'coverage-e2e'
+              publishLocation: 'pipeline'
+  - stage: test_combine
+    jobs:
+      - job: test_coverage_combine
+        pool:
+          vmImage: 'ubuntu-latest'
+        steps:
+          - task: DownloadPipelineArtifact@2
+            inputs:
+              buildType: 'current'
+              artifactName: 'coverage-e2e'
+              path: "coverage-e2e/"
+          - task: DownloadPipelineArtifact@2
+            inputs:
+              buildType: 'current'
+              artifactName: 'coverage-unittest'
+              path: "coverage-unittest/"
+          - task: UsePythonVersion@0
+            inputs:
+              versionSpec: '3.8'
+          - task: CmdLine@2
+            inputs:
+              script: |
+                sudo pip install -U wheel pipenv
+                pipenv install --dev
+                pipenv run coverage combine coverage-e2e/coverage coverage-unittest/coverage
+                pipenv run coverage xml
+                pipenv run coverage html
+          - task: PublishCodeCoverageResults@1
+            inputs:
+              codeCoverageTool: 'Cobertura'
+              summaryFileLocation: 'coverage.xml'
+              pathToSources: '$(System.DefaultWorkingDirectory)'
+          - task: PublishTestResults@2
+            condition: succeededOrFailed()
+            inputs:
+              testResultsFormat: 'JUnit'
+              testResultsFiles: |
+                coverage-e2e/unittest.xml
+                coverage-unittest/unittest.xml
+              mergeTestResults: true
+          - task: CmdLine@2
+            env:
+              CODECOV_TOKEN: $(CODECOV_TOKEN)
+            inputs:
+              script: bash <(curl -s https://codecov.io/bash)
+  - stage: Build
+    jobs:
+      - job: build_server
+        pool:
+          vmImage: 'ubuntu-latest'
+        steps:
+        - task: Docker@2
+          inputs:
+            containerRegistry: 'dockerhub'
+            repository: 'beryju/passbook'
+            command: 'buildAndPush'
+            Dockerfile: 'Dockerfile'
+            tags: "gh-${{ variables.branchName }}"
+      - job: build_static
+        pool:
+          vmImage: 'ubuntu-latest'
+        steps:
+        - task: DockerCompose@0
+          displayName: Run services
+          inputs:
+            dockerComposeFile: 'scripts/ci.docker-compose.yml'
+            action: 'Run services'
+            buildImages: false
+        - task: Docker@2
+          inputs:
+            containerRegistry: 'dockerhub'
+            repository: 'beryju/passbook-static'
+            command: 'build'
+            Dockerfile: 'static.Dockerfile'
+            tags: "gh-${{ variables.branchName }}"
+            arguments: "--network=beryjupassbook_default"
+        - task: Docker@2
+          inputs:
+            containerRegistry: 'dockerhub'
+            repository: 'beryju/passbook-static'
+            command: 'push'
+            tags: "gh-${{ variables.branchName }}"

base.Dockerfile

@@ -1,15 +0,0 @@
-FROM python:3.7-alpine
-
-COPY ./Pipfile /app/
-COPY ./Pipfile.lock /app/
-
-WORKDIR /app/
-
-RUN apk update && \
-    apk add --no-cache openssl-dev build-base libxml2-dev libxslt-dev libffi-dev gcc musl-dev libgcc zlib-dev postgresql-dev && \
-    pip install pipenv --no-cache-dir && \
-    pipenv lock -r > requirements.txt && \
-    pipenv --rm && \
-    pip install -r requirements.txt  --no-cache-dir && \
-    adduser -S passbook && \
-    chown -R passbook /app

dev.Dockerfile

@@ -1,4 +0,0 @@
-FROM docker.beryju.org/passbook/base:latest
-
-RUN pipenv lock --dev -r > requirements-dev.txt && \
-    pip install -r /app/requirements-dev.txt  --no-cache-dir

docker-compose.yml

@@ -0,0 +1,91 @@
+---
+version: '3.2'
+
+services:
+  postgresql:
+    image: postgres:12
+    volumes:
+      - database:/var/lib/postgresql/data
+    networks:
+      - internal
+    environment:
+      - POSTGRES_PASSWORD=${PG_PASS:-thisisnotagoodpassword}
+      - POSTGRES_USER=passbook
+      - POSTGRES_DB=passbook
+    env_file:
+      - .env
+  redis:
+    image: redis
+    networks:
+      - internal
+  server:
+    image: beryju/passbook:${PASSBOOK_TAG:-0.12.1-stable}
+    command: server
+    environment:
+      PASSBOOK_REDIS__HOST: redis
+      PASSBOOK_POSTGRESQL__HOST: postgresql
+      PASSBOOK_POSTGRESQL__PASSWORD: ${PG_PASS}
+    ports:
+      - 8000
+    networks:
+      - internal
+    labels:
+      traefik.enable: 'true'
+      traefik.docker.network: internal
+      traefik.http.routers.app-router.rule: PathPrefix(`/`)
+      traefik.http.routers.app-router.service: app-service
+      traefik.http.routers.app-router.tls: 'true'
+      traefik.http.services.app-service.loadbalancer.healthcheck.hostname: passbook-healthcheck-host
+      traefik.http.services.app-service.loadbalancer.server.port: '8000'
+    env_file:
+      - .env
+  worker:
+    image: beryju/passbook:${PASSBOOK_TAG:-0.12.1-stable}
+    command: worker
+    networks:
+      - internal
+    environment:
+      PASSBOOK_REDIS__HOST: redis
+      PASSBOOK_POSTGRESQL__HOST: postgresql
+      PASSBOOK_POSTGRESQL__PASSWORD: ${PG_PASS}
+    volumes:
+      - ./backups:/backups
+      - /var/run/docker.socket:/var/run/docker.socket
+    env_file:
+      - .env
+  static:
+    image: beryju/passbook-static:${PASSBOOK_TAG:-0.12.1-stable}
+    networks:
+      - internal
+    labels:
+      traefik.enable: 'true'
+      traefik.docker.network: internal
+      traefik.http.routers.static-router.rule: PathPrefix(`/static`, `/robots.txt`, `/favicon.ico`)
+      traefik.http.routers.static-router.tls: 'true'
+      traefik.http.routers.static-router.service: static-service
+      traefik.http.services.static-service.loadbalancer.healthcheck.path: /
+      traefik.http.services.static-service.loadbalancer.server.port: '80'
+  traefik:
+    image: traefik:2.3
+    command:
+      - "--accesslog=true"
+      - "--api.insecure=true"
+      - "--providers.docker=true"
+      - "--providers.docker.exposedbydefault=false"
+      - "--entrypoints.http.address=:80"
+      - "--entrypoints.https.address=:443"
+    volumes:
+      - /var/run/docker.sock:/var/run/docker.sock:ro
+    ports:
+      - "0.0.0.0:80:80"
+      - "0.0.0.0:443:443"
+      - "127.0.0.1:8080:8080"
+    networks:
+      - internal
+
+volumes:
+  database:
+    driver: local
+
+networks:
+  internal: {}

docker.env.yml

@@ -0,0 +1,9 @@
+debug: true
+postgresql:
+  user: postgres
+  host: postgresql
+
+redis:
+  host: redis
+
+log_level: debug

docs/expressions/index.md

@@ -0,0 +1,66 @@
+# Expressions
+
+Expressions allow you to write custom logic using Python code.
+
+Expressions are used in different places throughout passbook, and can do different things.
+
+!!! info
+    These functions/objects are available wherever expressions are used. For more specific information, see [Expression Policies](../policies/expression.md) and [Property Mappings](../property-mappings/expression.md)
+
+## Global objects
+
+- `pb_logger`: structlog BoundLogger. ([ref](https://www.structlog.org/en/stable/api.html#structlog.BoundLogger))
+- `requests`: requests Session object. ([ref](https://requests.readthedocs.io/en/master/user/advanced/))
+
+## Generally available functions
+
+### `regex_match(value: Any, regex: str) -> bool`
+
+Check if `value` matches Regular Expression `regex`.
+
+Example:
+
+```python
+return regex_match(request.user.username, '.*admin.*')
+```
+
+### `regex_replace(value: Any, regex: str, repl: str) -> str`
+
+Replace anything matching `regex` within `value` with `repl` and return it.
+
+Example:
+
+```python
+user_email_local = regex_replace(request.user.email, '(.+)@.+', '')
+```
+
+### `pb_is_group_member(user: User, **group_filters) -> bool`
+
+Check if `user` is member of a group matching `**group_filters`.
+
+Example:
+
+```python
+return pb_is_group_member(request.user, name="test_group")
+```
+
+### `pb_user_by(**filters) -> Optional[User]`
+
+Fetch a user matching `**filters`. Returns "None" if no user was found.
+
+Example:
+
+```python
+other_user = pb_user_by(username="other_user")
+```
+
+## Comparing IP Addresses
+
+To compare IP Addresses or check if an IP Address is within a given subnet, you can use the functions `ip_address('192.0.2.1')` and `ip_network('192.0.2.0/24')`. With these objects you can do [arithmetic operations](https://docs.python.org/3/library/ipaddress.html#operators).
+
+You can also check if an IP Address is within a subnet by writing the following:
+
+```python
+ip_address('192.0.2.1') in ip_network('192.0.2.0/24')
+# evaluates to True
+```

docs/expressions/reference/user-object.md

@@ -0,0 +1,26 @@
+# Passbook User Object
+
+The User object has the following attributes:
+
+- `username`: User's username.
+- `email` User's email.
+- `name` User's display name.
+- `is_staff` Boolean field if user is staff.
+- `is_active` Boolean field if user is active.
+- `date_joined` Date user joined/was created.
+- `password_change_date` Date password was last changed.
+- `attributes` Dynamic attributes.
+- `pb_groups` This is a queryset of all the user's groups.
+
+    You can do additional filtering like `user.pb_groups.filter(name__startswith='test')`, see [here](https://docs.djangoproject.com/en/3.1/ref/models/querysets/#id4)
+
+    To get the name of all groups, you can do `[group.name for group in user.pb_groups.all()]`
+
+## Examples
+
+List all the User's group names:
+
+```python
+for group in user.pb_groups.all():
+    yield group.name
+```

docs/flow/examples/enrollment-2-stage.json

@@ -0,0 +1,180 @@
+{
+    "version": 1,
+    "entries": [
+        {
+            "identifiers": {
+                "pk": "773c6673-e4a2-423f-8d32-95b7b4a41cf3",
+                "slug": "default-enrollment-flow"
+            },
+            "model": "passbook_flows.flow",
+            "attrs": {
+                "name": "Default enrollment Flow",
+                "title": "Welcome to passbook!",
+                "designation": "enrollment"
+            }
+        },
+        {
+            "identifiers": {
+                "pk": "cb954fd4-65a5-4ad9-b1ee-180ee9559cf4"
+            },
+            "model": "passbook_stages_prompt.prompt",
+            "attrs": {
+                "field_key": "username",
+                "label": "Username",
+                "type": "text",
+                "required": true,
+                "placeholder": "Username",
+                "order": 0
+            }
+        },
+        {
+            "identifiers": {
+                "pk": "7db91ee8-4290-4e08-8d39-63f132402515"
+            },
+            "model": "passbook_stages_prompt.prompt",
+            "attrs": {
+                "field_key": "password",
+                "label": "Password",
+                "type": "password",
+                "required": true,
+                "placeholder": "Password",
+                "order": 0
+            }
+        },
+        {
+            "identifiers": {
+                "pk": "d30b5eb4-7787-4072-b1ba-65b46e928920"
+            },
+            "model": "passbook_stages_prompt.prompt",
+            "attrs": {
+                "field_key": "password_repeat",
+                "label": "Password (repeat)",
+                "type": "password",
+                "required": true,
+                "placeholder": "Password (repeat)",
+                "order": 1
+            }
+        },
+        {
+            "identifiers": {
+                "pk": "f78d977a-efa6-4cc2-9a0f-2621a9fd94d2"
+            },
+            "model": "passbook_stages_prompt.prompt",
+            "attrs": {
+                "field_key": "name",
+                "label": "Name",
+                "type": "text",
+                "required": true,
+                "placeholder": "Name",
+                "order": 0
+            }
+        },
+        {
+            "identifiers": {
+                "pk": "1ff91927-e33d-4615-95b0-c258e5f0df62"
+            },
+            "model": "passbook_stages_prompt.prompt",
+            "attrs": {
+                "field_key": "email",
+                "label": "Email",
+                "type": "email",
+                "required": true,
+                "placeholder": "Email",
+                "order": 1
+            }
+        },
+        {
+            "identifiers": {
+                "pk": "6c342b94-790d-425a-ae31-6196b6570722",
+                "name": "default-enrollment-prompt-second"
+            },
+            "model": "passbook_stages_prompt.promptstage",
+            "attrs": {
+                "fields": [
+                    "f78d977a-efa6-4cc2-9a0f-2621a9fd94d2",
+                    "1ff91927-e33d-4615-95b0-c258e5f0df62"
+                ]
+            }
+        },
+        {
+            "identifiers": {
+                "pk": "20375f30-7fa7-4562-8f6e-0f61889f2963",
+                "name": "default-enrollment-prompt-first"
+            },
+            "model": "passbook_stages_prompt.promptstage",
+            "attrs": {
+                "fields": [
+                    "cb954fd4-65a5-4ad9-b1ee-180ee9559cf4",
+                    "7db91ee8-4290-4e08-8d39-63f132402515",
+                    "d30b5eb4-7787-4072-b1ba-65b46e928920"
+                ]
+            }
+        },
+        {
+            "identifiers": {
+                "pk": "77090897-eb3f-40db-81e6-b4074b1998c4",
+                "name": "default-enrollment-user-login"
+            },
+            "model": "passbook_stages_user_login.userloginstage",
+            "attrs": {
+                "session_duration": 0
+            }
+        },
+        {
+            "identifiers": {
+                "pk": "a4090add-f483-4ac6-8917-10b493ef843e",
+                "name": "default-enrollment-user-write"
+            },
+            "model": "passbook_stages_user_write.userwritestage",
+            "attrs": {}
+        },
+        {
+            "identifiers": {
+                "pk": "34e1e7d5-8eed-4549-bc7a-305069ff7df0",
+                "target": "773c6673-e4a2-423f-8d32-95b7b4a41cf3",
+                "stage": "20375f30-7fa7-4562-8f6e-0f61889f2963",
+                "order": 0
+            },
+            "model": "passbook_flows.flowstagebinding",
+            "attrs": {
+                "re_evaluate_policies": false
+            }
+        },
+        {
+            "identifiers": {
+                "pk": "e40467a6-3052-488c-a1b5-1ad7a80fe7b3",
+                "target": "773c6673-e4a2-423f-8d32-95b7b4a41cf3",
+                "stage": "6c342b94-790d-425a-ae31-6196b6570722",
+                "order": 1
+            },
+            "model": "passbook_flows.flowstagebinding",
+            "attrs": {
+                "re_evaluate_policies": false
+            }
+        },
+        {
+            "identifiers": {
+                "pk": "76bc594e-2715-49ab-bd40-994abd9a7b70",
+                "target": "773c6673-e4a2-423f-8d32-95b7b4a41cf3",
+                "stage": "a4090add-f483-4ac6-8917-10b493ef843e",
+                "order": 2
+            },
+            "model": "passbook_flows.flowstagebinding",
+            "attrs": {
+                "re_evaluate_policies": false
+            }
+        },
+        {
+            "identifiers": {
+                "pk": "2f324f6d-7646-4108-a6e2-e7f90985477f",
+                "target": "773c6673-e4a2-423f-8d32-95b7b4a41cf3",
+                "stage": "77090897-eb3f-40db-81e6-b4074b1998c4",
+                "order": 3
+            },
+            "model": "passbook_flows.flowstagebinding",
+            "attrs": {
+                "re_evaluate_policies": false
+            }
+        }
+    ]
+}

docs/flow/examples/enrollment-email-verification.json

@@ -0,0 +1,211 @@
+{
+    "version": 1,
+    "entries": [
+        {
+            "identifiers": {
+                "pk": "773c6673-e4a2-423f-8d32-95b7b4a41cf3",
+                "slug": "default-enrollment-flow"
+            },
+            "model": "passbook_flows.flow",
+            "attrs": {
+                "name": "Default enrollment Flow",
+                "title": "Welcome to passbook!",
+                "designation": "enrollment"
+            }
+        },
+        {
+            "identifiers": {
+                "pk": "cb954fd4-65a5-4ad9-b1ee-180ee9559cf4"
+            },
+            "model": "passbook_stages_prompt.prompt",
+            "attrs": {
+                "field_key": "username",
+                "label": "Username",
+                "type": "text",
+                "required": true,
+                "placeholder": "Username",
+                "order": 0
+            }
+        },
+        {
+            "identifiers": {
+                "pk": "7db91ee8-4290-4e08-8d39-63f132402515"
+            },
+            "model": "passbook_stages_prompt.prompt",
+            "attrs": {
+                "field_key": "password",
+                "label": "Password",
+                "type": "password",
+                "required": true,
+                "placeholder": "Password",
+                "order": 0
+            }
+        },
+        {
+            "identifiers": {
+                "pk": "d30b5eb4-7787-4072-b1ba-65b46e928920"
+            },
+            "model": "passbook_stages_prompt.prompt",
+            "attrs": {
+                "field_key": "password_repeat",
+                "label": "Password (repeat)",
+                "type": "password",
+                "required": true,
+                "placeholder": "Password (repeat)",
+                "order": 1
+            }
+        },
+        {
+            "identifiers": {
+                "pk": "f78d977a-efa6-4cc2-9a0f-2621a9fd94d2"
+            },
+            "model": "passbook_stages_prompt.prompt",
+            "attrs": {
+                "field_key": "name",
+                "label": "Name",
+                "type": "text",
+                "required": true,
+                "placeholder": "Name",
+                "order": 0
+            }
+        },
+        {
+            "identifiers": {
+                "pk": "1ff91927-e33d-4615-95b0-c258e5f0df62"
+            },
+            "model": "passbook_stages_prompt.prompt",
+            "attrs": {
+                "field_key": "email",
+                "label": "Email",
+                "type": "email",
+                "required": true,
+                "placeholder": "Email",
+                "order": 1
+            }
+        },
+        {
+            "identifiers": {
+                "pk": "096e6282-6b30-4695-bd03-3b143eab5580",
+                "name": "default-enrollment-email-verficiation"
+            },
+            "model": "passbook_stages_email.emailstage",
+            "attrs": {
+                "host": "localhost",
+                "port": 25,
+                "username": "",
+                "use_tls": false,
+                "use_ssl": false,
+                "timeout": 10,
+                "from_address": "system@passbook.local",
+                "token_expiry": 30,
+                "subject": "passbook",
+                "template": "stages/email/for_email/account_confirmation.html"
+            }
+        },
+        {
+            "identifiers": {
+                "pk": "6c342b94-790d-425a-ae31-6196b6570722",
+                "name": "default-enrollment-prompt-second"
+            },
+            "model": "passbook_stages_prompt.promptstage",
+            "attrs": {
+                "fields": [
+                    "f78d977a-efa6-4cc2-9a0f-2621a9fd94d2",
+                    "1ff91927-e33d-4615-95b0-c258e5f0df62"
+                ]
+            }
+        },
+        {
+            "identifiers": {
+                "pk": "20375f30-7fa7-4562-8f6e-0f61889f2963",
+                "name": "default-enrollment-prompt-first"
+            },
+            "model": "passbook_stages_prompt.promptstage",
+            "attrs": {
+                "fields": [
+                    "cb954fd4-65a5-4ad9-b1ee-180ee9559cf4",
+                    "7db91ee8-4290-4e08-8d39-63f132402515",
+                    "d30b5eb4-7787-4072-b1ba-65b46e928920"
+                ]
+            }
+        },
+        {
+            "identifiers": {
+                "pk": "77090897-eb3f-40db-81e6-b4074b1998c4",
+                "name": "default-enrollment-user-login"
+            },
+            "model": "passbook_stages_user_login.userloginstage",
+            "attrs": {
+                "session_duration": 0
+            }
+        },
+        {
+            "identifiers": {
+                "pk": "a4090add-f483-4ac6-8917-10b493ef843e",
+                "name": "default-enrollment-user-write"
+            },
+            "model": "passbook_stages_user_write.userwritestage",
+            "attrs": {}
+        },
+        {
+            "identifiers": {
+                "pk": "34e1e7d5-8eed-4549-bc7a-305069ff7df0",
+                "target": "773c6673-e4a2-423f-8d32-95b7b4a41cf3",
+                "stage": "20375f30-7fa7-4562-8f6e-0f61889f2963",
+                "order": 0
+            },
+            "model": "passbook_flows.flowstagebinding",
+            "attrs": {
+                "re_evaluate_policies": false
+            }
+        },
+        {
+            "identifiers": {
+                "pk": "e40467a6-3052-488c-a1b5-1ad7a80fe7b3",
+                "target": "773c6673-e4a2-423f-8d32-95b7b4a41cf3",
+                "stage": "6c342b94-790d-425a-ae31-6196b6570722",
+                "order": 1
+            },
+            "model": "passbook_flows.flowstagebinding",
+            "attrs": {
+                "re_evaluate_policies": false
+            }
+        },
+        {
+            "identifiers": {
+                "pk": "76bc594e-2715-49ab-bd40-994abd9a7b70",
+                "target": "773c6673-e4a2-423f-8d32-95b7b4a41cf3",
+                "stage": "a4090add-f483-4ac6-8917-10b493ef843e",
+                "order": 2
+            },
+            "model": "passbook_flows.flowstagebinding",
+            "attrs": {
+                "re_evaluate_policies": false
+            }
+        },
+        {
+            "identifiers": {
+                "pk": "1db34a14-8985-4184-b5c9-254cd585d94f",
+                "target": "773c6673-e4a2-423f-8d32-95b7b4a41cf3",
+                "stage": "096e6282-6b30-4695-bd03-3b143eab5580",
+                "order": 3
+            },
+            "model": "passbook_flows.flowstagebinding",
+            "attrs": {
+                "re_evaluate_policies": false
+            }
+        },
+        {
+            "identifiers": {
+                "pk": "2f324f6d-7646-4108-a6e2-e7f90985477f",
+                "target": "773c6673-e4a2-423f-8d32-95b7b4a41cf3",
+                "stage": "77090897-eb3f-40db-81e6-b4074b1998c4",
+                "order": 4
+            },
+            "model": "passbook_flows.flowstagebinding",
+            "attrs": {
+                "re_evaluate_policies": false
+            }
+        }
+    ]
+}

docs/flow/examples/examples.md

@@ -0,0 +1,49 @@
+# Example Flows
+
+!!! info
+    You can apply theses flows multiple times to stay updated, however this will discard all changes you've made.
+
+
+## Enrollment (2 Stage)
+
+Flow: right-click [here](enrollment-2-stage.json) and save the file.
+
+Sign-up flow for new users, which prompts them for their username, email, password and name. No verification is done. Users are also immediately logged on after this flow.
+
+## Enrollment with email verification
+
+Flow: right-click [here](enrollment-email-verification.json) and save the file.
+
+Same flow as above, with an extra email verification stage.
+
+You'll probably have to adjust the Email stage and set your connection details.
+
+## Two-factor Login
+
+Flow: right-click [here](login-2fa.json) and save the file.
+
+Login flow which follows the default pattern (username/email, then password), but also checks for the user's OTP token, if they have one configured
+
+## Login with conditional Captcha
+
+Flow: right-click [here](login-conditional-captcha.json) and save the file.
+
+Login flow which conditionally shows the users a captcha, based on the reputation of their IP and Username.
+
+By default, the captcha test keys are used. You can get a proper key [here](https://www.google.com/recaptcha/intro/v3.html)
+
+## Recovery with email verification
+
+Flow: right-click [here](recovery-email-verification.json) and save the file.
+
+Recovery flow, the user is sent an email after they've identified themselves. After they click on the link in the email, they are prompted for a new password and immediately logged on.
+
+## User deletion
+
+Flow: right-click [here](unenrollment.json) and save the file.
+
+Flow for users to delete their account,
+
+!!! warning
+    This is done without any warning.
+

docs/flow/examples/login-2fa.json

@@ -0,0 +1,111 @@
+{
+    "version": 1,
+    "entries": [
+        {
+            "identifiers": {
+                "slug": "default-authentication-flow",
+                "pk": "563ece21-e9a4-47e5-a264-23ffd923e393"
+            },
+            "model": "passbook_flows.flow",
+            "attrs": {
+                "name": "Default Authentication Flow",
+                "title": "Welcome to passbook!",
+                "designation": "authentication"
+            }
+        },
+        {
+            "identifiers": {
+                "pk": "69d41125-3987-499b-8d74-ef27b54b88c8",
+                "name": "default-authentication-login"
+            },
+            "model": "passbook_stages_user_login.userloginstage",
+            "attrs": {
+                "session_duration": 0
+            }
+        },
+        {
+            "identifiers": {
+                "pk": "5f594f27-0def-488d-9855-fe604eb13de5",
+                "name": "default-authentication-identification"
+            },
+            "model": "passbook_stages_identification.identificationstage",
+            "attrs": {
+                "user_fields": [
+                    "email",
+                    "username"
+                ],
+                "template": "stages/identification/login.html",
+                "enrollment_flow": null,
+                "recovery_flow": null
+            }
+        },
+        {
+            "identifiers": {
+                "pk": "37f709c3-8817-45e8-9a93-80a925d293c2",
+                "name": "default-authentication-flow-totp"
+            },
+            "model": "passbook_stages_otp_validate.otpvalidatestage",
+            "attrs": {}
+        },
+        {
+            "identifiers": {
+                "pk": "d8affa62-500c-4c5c-a01f-5835e1ffdf40",
+                "name": "default-authentication-password"
+            },
+            "model": "passbook_stages_password.passwordstage",
+            "attrs": {
+                "backends": [
+                    "django.contrib.auth.backends.ModelBackend"
+                ]
+            }
+        },
+        {
+            "identifiers": {
+                "pk": "a3056482-b692-4e3a-93f1-7351c6a351c7",
+                "target": "563ece21-e9a4-47e5-a264-23ffd923e393",
+                "stage": "5f594f27-0def-488d-9855-fe604eb13de5",
+                "order": 0
+            },
+            "model": "passbook_flows.flowstagebinding",
+            "attrs": {
+                "re_evaluate_policies": false
+            }
+        },
+        {
+            "identifiers": {
+                "pk": "4e8538cf-3e18-4a68-82ae-6df6725fa2e6",
+                "target": "563ece21-e9a4-47e5-a264-23ffd923e393",
+                "stage": "d8affa62-500c-4c5c-a01f-5835e1ffdf40",
+                "order": 1
+            },
+            "model": "passbook_flows.flowstagebinding",
+            "attrs": {
+                "re_evaluate_policies": false
+            }
+        },
+        {
+            "identifiers": {
+                "pk": "688aec6f-5622-42c6-83a5-d22072d7e798",
+                "target": "563ece21-e9a4-47e5-a264-23ffd923e393",
+                "stage": "37f709c3-8817-45e8-9a93-80a925d293c2",
+                "order": 2
+            },
+            "model": "passbook_flows.flowstagebinding",
+            "attrs": {
+                "re_evaluate_policies": false
+            }
+        },
+        {
+            "identifiers": {
+                "pk": "f3fede3a-a9b5-4232-9ec7-be7ff4194b27",
+                "target": "563ece21-e9a4-47e5-a264-23ffd923e393",
+                "stage": "69d41125-3987-499b-8d74-ef27b54b88c8",
+                "order": 3
+            },
+            "model": "passbook_flows.flowstagebinding",
+            "attrs": {
+                "re_evaluate_policies": false
+            }
+        }
+    ]
+}

docs/flow/examples/login-conditional-captcha.json

@@ -0,0 +1,139 @@
+{
+    "version": 1,
+    "entries": [
+        {
+            "identifiers": {
+                "slug": "default-authentication-flow",
+                "pk": "563ece21-e9a4-47e5-a264-23ffd923e393"
+            },
+            "model": "passbook_flows.flow",
+            "attrs": {
+                "name": "Default Authentication Flow",
+                "title": "Welcome to passbook!",
+                "designation": "authentication"
+            }
+        },
+        {
+            "identifiers": {
+                "name": "default-authentication-login",
+                "pk": "69d41125-3987-499b-8d74-ef27b54b88c8"
+            },
+            "model": "passbook_stages_user_login.userloginstage",
+            "attrs": {
+                "session_duration": 0
+            }
+        },
+        {
+            "identifiers": {
+                "name": "default-authentication-flow-captcha",
+                "pk": "a368cafc-1494-45e9-b75b-b5e7ac2bd3e4"
+            },
+            "model": "passbook_stages_captcha.captchastage",
+            "attrs": {
+                "public_key": "6LeIxAcTAAAAAJcZVRqyHh71UMIEGNQ_MXjiZKhI",
+                "private_key": "6LeIxAcTAAAAAGG-vFI1TnRWxMZNFuojJ4WifJWe"
+            }
+        },
+        {
+            "identifiers": {
+                "name": "default-authentication-identification",
+                "pk": "5f594f27-0def-488d-9855-fe604eb13de5"
+            },
+            "model": "passbook_stages_identification.identificationstage",
+            "attrs": {
+                "user_fields": [
+                    "email",
+                    "username"
+                ],
+                "template": "stages/identification/login.html",
+                "enrollment_flow": null,
+                "recovery_flow": null
+            }
+        },
+        {
+            "identifiers": {
+                "name": "default-authentication-password",
+                "pk": "d8affa62-500c-4c5c-a01f-5835e1ffdf40"
+            },
+            "model": "passbook_stages_password.passwordstage",
+            "attrs": {
+                "backends": [
+                    "django.contrib.auth.backends.ModelBackend"
+                ]
+            }
+        },
+        {
+            "identifiers": {
+                "pk": "a3056482-b692-4e3a-93f1-7351c6a351c7",
+                "target": "563ece21-e9a4-47e5-a264-23ffd923e393",
+                "stage": "5f594f27-0def-488d-9855-fe604eb13de5",
+                "order": 0
+            },
+            "model": "passbook_flows.flowstagebinding",
+            "attrs": {
+                "re_evaluate_policies": false
+            }
+        },
+        {
+            "identifiers": {
+                "pk": "4e8538cf-3e18-4a68-82ae-6df6725fa2e6",
+                "target": "563ece21-e9a4-47e5-a264-23ffd923e393",
+                "stage": "d8affa62-500c-4c5c-a01f-5835e1ffdf40",
+                "order": 1
+            },
+            "model": "passbook_flows.flowstagebinding",
+            "attrs": {
+                "re_evaluate_policies": false
+            }
+        },
+        {
+            "identifiers": {
+                "pk": "3bcd6af0-48a6-4e18-87f3-d251a1a58226",
+                "target": "563ece21-e9a4-47e5-a264-23ffd923e393",
+                "stage": "a368cafc-1494-45e9-b75b-b5e7ac2bd3e4",
+                "order": 2
+            },
+            "model": "passbook_flows.flowstagebinding",
+            "attrs": {
+                "re_evaluate_policies": false
+            }
+        },
+        {
+            "identifiers": {
+                "pk": "f3fede3a-a9b5-4232-9ec7-be7ff4194b27",
+                "target": "563ece21-e9a4-47e5-a264-23ffd923e393",
+                "stage": "69d41125-3987-499b-8d74-ef27b54b88c8",
+                "order": 3
+            },
+            "model": "passbook_flows.flowstagebinding",
+            "attrs": {
+                "re_evaluate_policies": false
+            }
+        },
+        {
+            "identifiers": {
+                "pk": "688c9890-47ad-4327-a9e5-380e88d34be5"
+            },
+            "model": "passbook_policies_reputation.reputationpolicy",
+            "attrs": {
+                "name": "default-authentication-flow-conditional-captcha",
+                "check_ip": true,
+                "check_username": true,
+                "threshold": -5
+            }
+        },
+        {
+            "identifiers": {
+                "pk": "02e4d220-3448-44db-822e-c5255cf7c250",
+                "policy": "688c9890-47ad-4327-a9e5-380e88d34be5",
+                "target": "3bcd6af0-48a6-4e18-87f3-d251a1a58226",
+                "order": 0
+            },
+            "model": "passbook_policies.policybinding",
+            "attrs": {
+                "enabled": true,
+                "timeout": 30
+            }
+        }
+    ]
+}

docs/flow/examples/recovery-email-verification.json

@@ -0,0 +1,185 @@
+{
+    "version": 1,
+    "entries": [
+        {
+            "identifiers": {
+                "pk": "a5993183-89c0-43d2-a7f4-ddffb17baba7",
+                "slug": "default-recovery-flow"
+            },
+            "model": "passbook_flows.flow",
+            "attrs": {
+                "name": "Default recovery flow",
+                "title": "Reset your password",
+                "designation": "recovery"
+            }
+        },
+        {
+            "identifiers": {
+                "pk": "1ff91927-e33d-4615-95b0-c258e5f0df62"
+            },
+            "model": "passbook_stages_prompt.prompt",
+            "attrs": {
+                "field_key": "email",
+                "label": "Email",
+                "type": "email",
+                "required": true,
+                "placeholder": "Email",
+                "order": 1
+            }
+        },
+        {
+            "identifiers": {
+                "pk": "7db91ee8-4290-4e08-8d39-63f132402515"
+            },
+            "model": "passbook_stages_prompt.prompt",
+            "attrs": {
+                "field_key": "password",
+                "label": "Password",
+                "type": "password",
+                "required": true,
+                "placeholder": "Password",
+                "order": 0
+            }
+        },
+        {
+            "identifiers": {
+                "pk": "d30b5eb4-7787-4072-b1ba-65b46e928920"
+            },
+            "model": "passbook_stages_prompt.prompt",
+            "attrs": {
+                "field_key": "password_repeat",
+                "label": "Password (repeat)",
+                "type": "password",
+                "required": true,
+                "placeholder": "Password (repeat)",
+                "order": 1
+            }
+        },
+        {
+            "identifiers": {
+                "pk": "e54045a7-6ecb-4ad9-ad37-28e72d8e565e",
+                "name": "default-recovery-identification"
+            },
+            "model": "passbook_stages_identification.identificationstage",
+            "attrs": {
+                "user_fields": [
+                    "email",
+                    "username"
+                ],
+                "template": "stages/identification/recovery.html",
+                "enrollment_flow": null,
+                "recovery_flow": null
+            }
+        },
+        {
+            "identifiers": {
+                "pk": "3909fd60-b013-4668-8806-12e9507dab97",
+                "name": "default-recovery-user-write"
+            },
+            "model": "passbook_stages_user_write.userwritestage",
+            "attrs": {}
+        },
+        {
+            "identifiers": {
+                "pk": "66f948dc-3f74-42b2-b26b-b8b9df109efb",
+                "name": "default-recovery-email"
+            },
+            "model": "passbook_stages_email.emailstage",
+            "attrs": {
+                "host": "localhost",
+                "port": 25,
+                "username": "",
+                "use_tls": false,
+                "use_ssl": false,
+                "timeout": 10,
+                "from_address": "system@passbook.local",
+                "token_expiry": 30,
+                "subject": "passbook",
+                "template": "stages/email/for_email/password_reset.html"
+            }
+        },
+        {
+            "identifiers": {
+                "pk": "975d5502-1e22-4d10-b560-fbc5bd70ff4d",
+                "name": "Change your password"
+            },
+            "model": "passbook_stages_prompt.promptstage",
+            "attrs": {
+                "fields": [
+                    "7db91ee8-4290-4e08-8d39-63f132402515",
+                    "d30b5eb4-7787-4072-b1ba-65b46e928920"
+                ]
+            }
+        },
+        {
+            "identifiers": {
+                "pk": "fcdd4206-0d35-4ad2-a59f-5a72422936bb",
+                "name": "default-recovery-user-login"
+            },
+            "model": "passbook_stages_user_login.userloginstage",
+            "attrs": {
+                "session_duration": 0
+            }
+        },
+        {
+            "identifiers": {
+                "pk": "7af7558e-2196-4b9f-a08e-d38420b7cfbb",
+                "target": "a5993183-89c0-43d2-a7f4-ddffb17baba7",
+                "stage": "e54045a7-6ecb-4ad9-ad37-28e72d8e565e",
+                "order": 0
+            },
+            "model": "passbook_flows.flowstagebinding",
+            "attrs": {
+                "re_evaluate_policies": false
+            }
+        },
+        {
+            "identifiers": {
+                "pk": "29446fd6-dd93-4e92-9830-2d81debad5ae",
+                "target": "a5993183-89c0-43d2-a7f4-ddffb17baba7",
+                "stage": "66f948dc-3f74-42b2-b26b-b8b9df109efb",
+                "order": 1
+            },
+            "model": "passbook_flows.flowstagebinding",
+            "attrs": {
+                "re_evaluate_policies": false
+            }
+        },
+        {
+            "identifiers": {
+                "pk": "1219d06e-2c06-4c5b-a162-78e3959c6cf0",
+                "target": "a5993183-89c0-43d2-a7f4-ddffb17baba7",
+                "stage": "975d5502-1e22-4d10-b560-fbc5bd70ff4d",
+                "order": 2
+            },
+            "model": "passbook_flows.flowstagebinding",
+            "attrs": {
+                "re_evaluate_policies": false
+            }
+        },
+        {
+            "identifiers": {
+                "pk": "66de86ba-0707-46a0-8475-ff2e260d6935",
+                "target": "a5993183-89c0-43d2-a7f4-ddffb17baba7",
+                "stage": "3909fd60-b013-4668-8806-12e9507dab97",
+                "order": 3
+            },
+            "model": "passbook_flows.flowstagebinding",
+            "attrs": {
+                "re_evaluate_policies": false
+            }
+        },
+        {
+            "identifiers": {
+                "pk": "9cec2334-d4a2-4895-a2b2-bc5ae4e9639a",
+                "target": "a5993183-89c0-43d2-a7f4-ddffb17baba7",
+                "stage": "fcdd4206-0d35-4ad2-a59f-5a72422936bb",
+                "order": 4
+            },
+            "model": "passbook_flows.flowstagebinding",
+            "attrs": {
+                "re_evaluate_policies": false
+            }
+        }
+    ]
+}

docs/flow/examples/unenrollment.json

@@ -0,0 +1,37 @@
+{
+    "version": 1,
+    "entries": [
+        {
+            "identifiers": {
+                "pk": "59a576ce-2f23-4a63-b63a-d18dc7e550f5",
+                "slug": "default-unenrollment-flow"
+            },
+            "model": "passbook_flows.flow",
+            "attrs": {
+                "name": "Default unenrollment flow",
+                "title": "Delete your account",
+                "designation": "unenrollment"
+            }
+        },
+        {
+            "identifiers": {
+                "pk": "c62ac2a4-2735-4a0f-abd0-8523d68c1209",
+                "name": "default-unenrollment-user-delete"
+            },
+            "model": "passbook_stages_user_delete.userdeletestage",
+            "attrs": {}
+        },
+        {
+            "identifiers": {
+                "pk": "eb9aff2b-b95d-40b3-ad08-233aa77bbcf3",
+                "target": "59a576ce-2f23-4a63-b63a-d18dc7e550f5",
+                "stage": "c62ac2a4-2735-4a0f-abd0-8523d68c1209",
+                "order": 0
+            },
+            "model": "passbook_flows.flowstagebinding",
+            "attrs": {
+                "re_evaluate_policies": false
+            }
+        }
+    ]
+}

docs/flow/flows.md

@@ -0,0 +1,44 @@
+# Flows
+
+Flows are a method of describing a sequence of stages. A stage represents a single verification or logic step. They are used to authenticate users, enroll them, and more.
+
+Upon flow execution, a plan containing all stages is generated. This means that all attached policies are evaluated upon execution. This behaviour can be altered by enabling the **Re-evaluate Policies** option on the binding.
+
+To determine which flow is linked, passbook searches all flows with the required designation and chooses the first instance the current user has access to.
+
+## Permissions
+
+Flows can have policies assigned to them. These policies determine if the current user is allowed to see and use this flow.
+
+## Designation
+
+Flows are designated for a single purpose. This designation changes when a flow is used. The following designations are available:
+
+### Authentication
+
+This is designates a flow to be used for authentication.
+
+The authentication flow should always contain a [**User Login**](stages/user_login.md) stage, which attaches the staged user to the current session.
+
+### Invalidation
+
+This designates a flow to be used to invalidate a session.
+
+This stage should always contain a [**User Logout**](stages/user_logout.md) stage, which resets the current session.
+
+### Enrollment
+
+This designates a flow for enrollment. This flow can contain any amount of verification stages, such as [**email**](stages/email/index.md) or [**captcha**](stages/captcha/index.md). At the end, to create the user, you can use the [**user_write**](stages/user_write.md) stage, which either updates the currently staged user, or if none exists, creates a new one.
+
+### Unenrollment
+
+This designates a flow for unenrollment. This flow can contain any amount of verification stages, such as [**email**](stages/email/index.md) or [**captcha**](stages/captcha/index.md). As a final stage, to delete the account, use the [**user_delete**](stages/user_delete.md) stage.
+
+### Recovery
+
+This designates a flow for recovery. This flow normally contains an [**identification**](stages/identification/index.md) stage to find the user. It can also contain any amount of verification stages, such as [**email**](stages/email/index.md) or [**captcha**](stages/captcha/index.md).
+Afterwards, use the [**prompt**](stages/prompt/index.md) stage to ask the user for a new password and the [**user_write**](stages/user_write.md) stage to update the password.
+
+### Setup
+
+This designates a flow for general setup. This designation doesn't have any constraints in what you can do. For example, by default this designation is used to configure Factors, like change a password and setup TOTP.

docs/flow/stages/captcha/index.md

@@ -0,0 +1,7 @@
+# Captcha stage
+
+This stage adds a form of verification using [Google's ReCaptcha](https://www.google.com/recaptcha/intro/v3.html).
+
+This stage has two required fields: Public key and private key. These can both be acquired at https://www.google.com/recaptcha/admin.
+
+![](captcha-admin.png)

docs/flow/stages/dummy/index.md

@@ -0,0 +1,5 @@
+# Dummy stage
+
+This stage is used for development and has no function. It presents the user with a form which requires a single confirmation.
+
+![](dummy.png)

docs/flow/stages/email/index.md

@@ -0,0 +1,5 @@
+# Email
+
+This stage can be used for email verification. passbook's background worker will send an email using the specified connection details. When an email can't be delivered, delivery is automatically retried periodically.
+
+![](email-recovery.png)

docs/flow/stages/identification/index.md

@@ -0,0 +1,25 @@
+# Identification
+
+This stage provides a ready-to-go form for users to identify themselves.
+
+## Options
+
+### User Fields
+
+Select which fields the user can use to identify themselves. Multiple fields can be specified and separated with a comma.
+Valid choices:
+
+- email
+- username
+
+### Template
+
+This specifies which template is rendered. Currently there are two templates:
+
+The `Login` template shows configured Sources below the login form, as well as linking to the defined Enrollment and Recovery flows.
+
+The `Recovery` template shows only the form.
+
+### Enrollment/Recovery Flow
+
+These fields specify if and which flows are linked on the form. The enrollment flow is linked as `Need an account? Sign up.`, and the recovery flow is linked as `Forgot username or password?`.

docs/flow/stages/invitation/index.md

@@ -0,0 +1,7 @@
+# Invitation Stage
+
+This stage can be used to invite users. You can use this to enroll users with preset values.
+
+If the option `Continue Flow without Invitation` is enabled, this stage will continue even when no invitation token is present.
+
+To check if a user has used an invitation within a policy, you can check `request.context.invitation_in_effect`.

docs/flow/stages/otp/index.md

@@ -0,0 +1,7 @@
+# OTP Stage
+
+This stage offers a generic Time-based One-time Password authentication step.
+
+You can optionally enforce this step, which will force every user without OTP setup to configure it.
+
+This stage uses a 6-digit Code with a 30 second time-drift. This is currently not changeable.

docs/flow/stages/password/index.md

@@ -0,0 +1,3 @@
+# Password Stage
+
+This is a generic password prompt which authenticates the current `pending_user`. This stage allows the selection of the source the user is authenticated against.

docs/flow/stages/prompt/index.md

@@ -0,0 +1,42 @@
+# Prompt Stage
+
+This stage is used to show the user arbitrary prompts.
+
+## Prompt
+
+The prompt can be any of the following types:
+
+| Type     | Description                                                      |
+|----------|------------------------------------------------------------------|
+| text     | Arbitrary text. No client-side validation is done.               |
+| email    | Email input. Requires a valid email adress.                      |
+| password | Password input.                                                  |
+| number   | Number input. Any number is allowed.                             |
+| checkbox | Simple checkbox.                                                 |
+| hidden   | Hidden input field. Allows for the pre-setting of default values.|
+
+A prompt has the following attributes:
+
+### `field_key`
+
+The HTML name used for the prompt. This key is also used to later retrieve the data in expression policies:
+
+```python
+request.context.get('prompt_data').get('<field_key>')
+```
+
+### `label`
+
+The label used to describe the field. Depending on the selected template, this may not be shown.
+
+### `required`
+
+A flag which decides whether or not this field is required.
+
+### `placeholder`
+
+A field placeholder, shown within the input field. This field is also used by the `hidden` type as the actual value.
+
+### `order`
+
+The numerical index of the prompt. This applies to all stages which this prompt is a part of.

docs/flow/stages/prompt/validation.md

@@ -0,0 +1,16 @@
+# Prompt Validation
+
+Further validation of prompts can be done using policies.
+
+To validate that two password fields are identical, create the following expression policy:
+
+```python
+if request.context.get('prompt_data').get('password') == request.context.get('prompt_data').get('password_repeat'):
+    return True
+
+pb_message("Passwords don't match.")
+return False
+```
+This policy expects you to have two password fields with `field_key` set to `password` and `password_repeat`.
+
+Afterwards, bind this policy to the prompt stage you want to validate.

docs/flow/stages/user_delete.md

@@ -0,0 +1,8 @@
+# User Delete Stage
+
+!!! danger
+    This stage deletes the `pending_user` without any confirmation. You have to make sure the user is aware of this.
+
+This stage is intended for an unenrollment flow. It deletes the currently pending user.
+
+The pending user is also removed from the current session.

docs/flow/stages/user_login.md

@@ -0,0 +1,5 @@
+# User Login Stage
+
+This stage attaches a currently pending user to the current session.
+
+It can be used after `user_write` during an enrollment flow, or after a `password` stage during an authentication flow.

docs/flow/stages/user_logout.md

@@ -0,0 +1,3 @@
+# User Logout Stage
+
+Opposite stage of [User Login Stages](user_login.md). It removes the user from the current session.

docs/flow/stages/user_write.md

@@ -0,0 +1,3 @@
+# User Write Stage
+
+This stages writes data from the current context to the current pending user. If no user is pending, a new one is created.

docs/images/brand.svg

@@ -1,2 +1,2 @@
 <svg version="1.1" id="Layer_1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" x="0px" y="0px"
-  width="270px" height="20px" viewBox="0 0 270 10" enable-background="new 0 0 270 10" xml:space="preserve"><defs><style>.cls-1{isolation:isolate;}.cls-2{fill:#fff;}</style></defs><g class="cls-1"><path class="cls-2" d="M1.65,11V2.45H2.87V3a2.81,2.81,0,0,1,.47-.45A1.13,1.13,0,0,1,4,2.38,1.11,1.11,0,0,1,5.1,3a1.55,1.55,0,0,1,.16.5,5.61,5.61,0,0,1,0,.81V6.58c0,.45,0,.77,0,1a1.17,1.17,0,0,1-.55.9,1.23,1.23,0,0,1-.7.16,1.35,1.35,0,0,1-.64-.16A1.53,1.53,0,0,1,2.89,8h0v3ZM4.08,4.43a1.21,1.21,0,0,0-.14-.6.51.51,0,0,0-.46-.22A.54.54,0,0,0,3,3.82a.8.8,0,0,0-.17.54V6.73A.68.68,0,0,0,3,7.2a.6.6,0,0,0,.44.18A.53.53,0,0,0,4,7.17a1,1,0,0,0,.12-.5Z"/><path class="cls-2" d="M8.63,8.54V7.91h0a2.24,2.24,0,0,1-.48.52,1.13,1.13,0,0,1-.69.18A1.39,1.39,0,0,1,7,8.54a1.09,1.09,0,0,1-.43-.24,1.32,1.32,0,0,1-.33-.49A2.33,2.33,0,0,1,6.11,7a4.89,4.89,0,0,1,.08-.91,1.51,1.51,0,0,1,.31-.65,1.44,1.44,0,0,1,.59-.38A3.19,3.19,0,0,1,8,4.93h.59V4.33a1,1,0,0,0-.13-.52A.52.52,0,0,0,8,3.61a.71.71,0,0,0-.44.15.78.78,0,0,0-.26.46H6.13A2,2,0,0,1,6.69,2.9a1.73,1.73,0,0,1,.57-.38A2,2,0,0,1,8,2.38a2.18,2.18,0,0,1,.72.12,1.71,1.71,0,0,1,.59.36,2,2,0,0,1,.38.6,2.18,2.18,0,0,1,.14.84V8.54Zm0-2.62-.34,0a1.2,1.2,0,0,0-.67.18.76.76,0,0,0-.29.68.89.89,0,0,0,.17.56A.55.55,0,0,0,8,7.53a.63.63,0,0,0,.49-.2.91.91,0,0,0,.17-.58Z"/><path class="cls-2" d="M13,4.16a.59.59,0,0,0-.2-.47.65.65,0,0,0-.42-.16.59.59,0,0,0-.45.19.66.66,0,0,0-.15.43.8.8,0,0,0,.08.33.85.85,0,0,0,.44.29l.71.29a1.73,1.73,0,0,1,.95.72,2,2,0,0,1,.26,1,1.85,1.85,0,0,1-.52,1.3,1.56,1.56,0,0,1-.58.39,1.88,1.88,0,0,1-2-.32,1.58,1.58,0,0,1-.4-.57,1.81,1.81,0,0,1-.17-.8h1.15a1.11,1.11,0,0,0,.17.47.56.56,0,0,0,.49.22.71.71,0,0,0,.47-.18A.59.59,0,0,0,13,6.8a.69.69,0,0,0-.13-.43,1.08,1.08,0,0,0-.48-.32l-.59-.21a2.08,2.08,0,0,1-.9-.64,1.66,1.66,0,0,1-.33-1,1.89,1.89,0,0,1,.14-.72,1.78,1.78,0,0,1,.4-.57,1.5,1.5,0,0,1,.56-.36,1.82,1.82,0,0,1,.7-.13,1.93,1.93,0,0,1,.69.13,1.6,1.6,0,0,1,.54.38,1.85,1.85,0,0,1,.36.57,1.82,1.82,0,0,1,.13.7Z"/><path class="cls-2" d="M17.2,4.16a.63.63,0,0,0-.2-.47.69.69,0,0,0-.43-.16.55.55,0,0,0-.44.19.62.62,0,0,0-.16.43.68.68,0,0,0,.09.33.81.81,0,0,0,.43.29l.72.29a1.7,1.7,0,0,1,.94.72,2,2,0,0,1,.26,1,1.85,1.85,0,0,1-.52,1.3,1.61,1.61,0,0,1-.57.39,1.81,1.81,0,0,1-.74.15,1.76,1.76,0,0,1-1.24-.47,1.61,1.61,0,0,1-.41-.57,2,2,0,0,1-.17-.8h1.15a1.12,1.12,0,0,0,.18.47.53.53,0,0,0,.48.22.72.72,0,0,0,.48-.18.59.59,0,0,0,.21-.48.69.69,0,0,0-.14-.43,1,1,0,0,0-.48-.32l-.58-.21a2.06,2.06,0,0,1-.91-.64,1.66,1.66,0,0,1-.33-1A1.89,1.89,0,0,1,15,3.44a1.78,1.78,0,0,1,.4-.57,1.58,1.58,0,0,1,.56-.36,1.82,1.82,0,0,1,.7-.13,1.93,1.93,0,0,1,.69.13,1.75,1.75,0,0,1,.55.38,1.85,1.85,0,0,1,.36.57,2,2,0,0,1,.13.7Z"/><path class="cls-2" d="M19.2,8.54V0h1.22V3h0a1.53,1.53,0,0,1,.48-.47,1.39,1.39,0,0,1,.65-.16,1.26,1.26,0,0,1,.69.16,1.35,1.35,0,0,1,.4.39,1.18,1.18,0,0,1,.15.51,7.72,7.72,0,0,1,0,1V6.73a5.56,5.56,0,0,1-.05.8,1.56,1.56,0,0,1-.15.5,1.12,1.12,0,0,1-1.07.58,1.15,1.15,0,0,1-.7-.18A3.79,3.79,0,0,1,20.42,8v.55Zm2.44-4.21a1,1,0,0,0-.13-.51A.5.5,0,0,0,21,3.61a.57.57,0,0,0-.44.18.66.66,0,0,0-.18.48V6.63a.83.83,0,0,0,.17.54.52.52,0,0,0,.45.21.49.49,0,0,0,.45-.22,1.11,1.11,0,0,0,.15-.6Z"/><path class="cls-2" d="M23.76,4.49a4.83,4.83,0,0,1,0-.68A1.55,1.55,0,0,1,24,3.26a1.59,1.59,0,0,1,.62-.64,1.84,1.84,0,0,1,1-.24,1.87,1.87,0,0,1,1,.24,1.59,1.59,0,0,1,.62.64,1.55,1.55,0,0,1,.18.55,4.83,4.83,0,0,1,.05.68v2a4.72,4.72,0,0,1-.05.68,1.55,1.55,0,0,1-.18.55,1.59,1.59,0,0,1-.62.64,1.87,1.87,0,0,1-1,.24,1.84,1.84,0,0,1-1-.24A1.59,1.59,0,0,1,24,7.73a1.55,1.55,0,0,1-.18-.55,4.72,4.72,0,0,1,0-.68ZM25,6.69a.72.72,0,0,0,.17.52.53.53,0,0,0,.43.17A.55.55,0,0,0,26,7.21a.72.72,0,0,0,.16-.52V4.3A.74.74,0,0,0,26,3.78a.55.55,0,0,0-.44-.17.53.53,0,0,0-.43.17A.74.74,0,0,0,25,4.3Z"/><path class="cls-2" d="M28.2,4.49a4.83,4.83,0,0,1,.05-.68,1.55,1.55,0,0,1,.18-.55,1.59,1.59,0,0,1,.62-.64,1.84,1.84,0,0,1,1-.24,1.87,1.87,0,0,1,1,.24,1.59,1.59,0,0,1,.62.64,1.55,1.55,0,0,1,.18.55,4.83,4.83,0,0,1,.05.68v2a4.72,4.72,0,0,1-.05.68,1.55,1.55,0,0,1-.18.55,1.59,1.59,0,0,1-.62.64,1.87,1.87,0,0,1-1,.24,1.84,1.84,0,0,1-1-.24,1.59,1.59,0,0,1-.62-.64,1.55,1.55,0,0,1-.18-.55,4.72,4.72,0,0,1-.05-.68Zm1.22,2.2a.72.72,0,0,0,.17.52.53.53,0,0,0,.43.17.55.55,0,0,0,.44-.17.72.72,0,0,0,.16-.52V4.3a.74.74,0,0,0-.16-.52A.55.55,0,0,0,30,3.61a.53.53,0,0,0-.43.17.74.74,0,0,0-.17.52Z"/><path class="cls-2" d="M32.75,8.54V0H34V5.11h0l1.47-2.66H36.7L35.24,4.93,37,8.54H35.66l-1.1-2.63L34,6.83V8.54Z"/></g></svg>
+  width="120px" height="20px" viewBox="15 0 10 10" enable-background="new 0 0 270 10" xml:space="preserve"><defs><style>.cls-1{isolation:isolate;}.cls-2{fill:#fff;}</style></defs><g class="cls-1"><path class="cls-2" d="M1.65,11V2.45H2.87V3a2.81,2.81,0,0,1,.47-.45A1.13,1.13,0,0,1,4,2.38,1.11,1.11,0,0,1,5.1,3a1.55,1.55,0,0,1,.16.5,5.61,5.61,0,0,1,0,.81V6.58c0,.45,0,.77,0,1a1.17,1.17,0,0,1-.55.9,1.23,1.23,0,0,1-.7.16,1.35,1.35,0,0,1-.64-.16A1.53,1.53,0,0,1,2.89,8h0v3ZM4.08,4.43a1.21,1.21,0,0,0-.14-.6.51.51,0,0,0-.46-.22A.54.54,0,0,0,3,3.82a.8.8,0,0,0-.17.54V6.73A.68.68,0,0,0,3,7.2a.6.6,0,0,0,.44.18A.53.53,0,0,0,4,7.17a1,1,0,0,0,.12-.5Z"/><path class="cls-2" d="M8.63,8.54V7.91h0a2.24,2.24,0,0,1-.48.52,1.13,1.13,0,0,1-.69.18A1.39,1.39,0,0,1,7,8.54a1.09,1.09,0,0,1-.43-.24,1.32,1.32,0,0,1-.33-.49A2.33,2.33,0,0,1,6.11,7a4.89,4.89,0,0,1,.08-.91,1.51,1.51,0,0,1,.31-.65,1.44,1.44,0,0,1,.59-.38A3.19,3.19,0,0,1,8,4.93h.59V4.33a1,1,0,0,0-.13-.52A.52.52,0,0,0,8,3.61a.71.71,0,0,0-.44.15.78.78,0,0,0-.26.46H6.13A2,2,0,0,1,6.69,2.9a1.73,1.73,0,0,1,.57-.38A2,2,0,0,1,8,2.38a2.18,2.18,0,0,1,.72.12,1.71,1.71,0,0,1,.59.36,2,2,0,0,1,.38.6,2.18,2.18,0,0,1,.14.84V8.54Zm0-2.62-.34,0a1.2,1.2,0,0,0-.67.18.76.76,0,0,0-.29.68.89.89,0,0,0,.17.56A.55.55,0,0,0,8,7.53a.63.63,0,0,0,.49-.2.91.91,0,0,0,.17-.58Z"/><path class="cls-2" d="M13,4.16a.59.59,0,0,0-.2-.47.65.65,0,0,0-.42-.16.59.59,0,0,0-.45.19.66.66,0,0,0-.15.43.8.8,0,0,0,.08.33.85.85,0,0,0,.44.29l.71.29a1.73,1.73,0,0,1,.95.72,2,2,0,0,1,.26,1,1.85,1.85,0,0,1-.52,1.3,1.56,1.56,0,0,1-.58.39,1.88,1.88,0,0,1-2-.32,1.58,1.58,0,0,1-.4-.57,1.81,1.81,0,0,1-.17-.8h1.15a1.11,1.11,0,0,0,.17.47.56.56,0,0,0,.49.22.71.71,0,0,0,.47-.18A.59.59,0,0,0,13,6.8a.69.69,0,0,0-.13-.43,1.08,1.08,0,0,0-.48-.32l-.59-.21a2.08,2.08,0,0,1-.9-.64,1.66,1.66,0,0,1-.33-1,1.89,1.89,0,0,1,.14-.72,1.78,1.78,0,0,1,.4-.57,1.5,1.5,0,0,1,.56-.36,1.82,1.82,0,0,1,.7-.13,1.93,1.93,0,0,1,.69.13,1.6,1.6,0,0,1,.54.38,1.85,1.85,0,0,1,.36.57,1.82,1.82,0,0,1,.13.7Z"/><path class="cls-2" d="M17.2,4.16a.63.63,0,0,0-.2-.47.69.69,0,0,0-.43-.16.55.55,0,0,0-.44.19.62.62,0,0,0-.16.43.68.68,0,0,0,.09.33.81.81,0,0,0,.43.29l.72.29a1.7,1.7,0,0,1,.94.72,2,2,0,0,1,.26,1,1.85,1.85,0,0,1-.52,1.3,1.61,1.61,0,0,1-.57.39,1.81,1.81,0,0,1-.74.15,1.76,1.76,0,0,1-1.24-.47,1.61,1.61,0,0,1-.41-.57,2,2,0,0,1-.17-.8h1.15a1.12,1.12,0,0,0,.18.47.53.53,0,0,0,.48.22.72.72,0,0,0,.48-.18.59.59,0,0,0,.21-.48.69.69,0,0,0-.14-.43,1,1,0,0,0-.48-.32l-.58-.21a2.06,2.06,0,0,1-.91-.64,1.66,1.66,0,0,1-.33-1A1.89,1.89,0,0,1,15,3.44a1.78,1.78,0,0,1,.4-.57,1.58,1.58,0,0,1,.56-.36,1.82,1.82,0,0,1,.7-.13,1.93,1.93,0,0,1,.69.13,1.75,1.75,0,0,1,.55.38,1.85,1.85,0,0,1,.36.57,2,2,0,0,1,.13.7Z"/><path class="cls-2" d="M19.2,8.54V0h1.22V3h0a1.53,1.53,0,0,1,.48-.47,1.39,1.39,0,0,1,.65-.16,1.26,1.26,0,0,1,.69.16,1.35,1.35,0,0,1,.4.39,1.18,1.18,0,0,1,.15.51,7.72,7.72,0,0,1,0,1V6.73a5.56,5.56,0,0,1-.05.8,1.56,1.56,0,0,1-.15.5,1.12,1.12,0,0,1-1.07.58,1.15,1.15,0,0,1-.7-.18A3.79,3.79,0,0,1,20.42,8v.55Zm2.44-4.21a1,1,0,0,0-.13-.51A.5.5,0,0,0,21,3.61a.57.57,0,0,0-.44.18.66.66,0,0,0-.18.48V6.63a.83.83,0,0,0,.17.54.52.52,0,0,0,.45.21.49.49,0,0,0,.45-.22,1.11,1.11,0,0,0,.15-.6Z"/><path class="cls-2" d="M23.76,4.49a4.83,4.83,0,0,1,0-.68A1.55,1.55,0,0,1,24,3.26a1.59,1.59,0,0,1,.62-.64,1.84,1.84,0,0,1,1-.24,1.87,1.87,0,0,1,1,.24,1.59,1.59,0,0,1,.62.64,1.55,1.55,0,0,1,.18.55,4.83,4.83,0,0,1,.05.68v2a4.72,4.72,0,0,1-.05.68,1.55,1.55,0,0,1-.18.55,1.59,1.59,0,0,1-.62.64,1.87,1.87,0,0,1-1,.24,1.84,1.84,0,0,1-1-.24A1.59,1.59,0,0,1,24,7.73a1.55,1.55,0,0,1-.18-.55,4.72,4.72,0,0,1,0-.68ZM25,6.69a.72.72,0,0,0,.17.52.53.53,0,0,0,.43.17A.55.55,0,0,0,26,7.21a.72.72,0,0,0,.16-.52V4.3A.74.74,0,0,0,26,3.78a.55.55,0,0,0-.44-.17.53.53,0,0,0-.43.17A.74.74,0,0,0,25,4.3Z"/><path class="cls-2" d="M28.2,4.49a4.83,4.83,0,0,1,.05-.68,1.55,1.55,0,0,1,.18-.55,1.59,1.59,0,0,1,.62-.64,1.84,1.84,0,0,1,1-.24,1.87,1.87,0,0,1,1,.24,1.59,1.59,0,0,1,.62.64,1.55,1.55,0,0,1,.18.55,4.83,4.83,0,0,1,.05.68v2a4.72,4.72,0,0,1-.05.68,1.55,1.55,0,0,1-.18.55,1.59,1.59,0,0,1-.62.64,1.87,1.87,0,0,1-1,.24,1.84,1.84,0,0,1-1-.24,1.59,1.59,0,0,1-.62-.64,1.55,1.55,0,0,1-.18-.55,4.72,4.72,0,0,1-.05-.68Zm1.22,2.2a.72.72,0,0,0,.17.52.53.53,0,0,0,.43.17.55.55,0,0,0,.44-.17.72.72,0,0,0,.16-.52V4.3a.74.74,0,0,0-.16-.52A.55.55,0,0,0,30,3.61a.53.53,0,0,0-.43.17.74.74,0,0,0-.17.52Z"/><path class="cls-2" d="M32.75,8.54V0H34V5.11h0l1.47-2.66H36.7L35.24,4.93,37,8.54H35.66l-1.1-2.63L34,6.83V8.54Z"/></g></svg>

docs/images/brand_inverted.svg

@@ -0,0 +1,2 @@
+<svg version="1.1" id="Layer_1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" x="0px" y="0px"
+  width="120px" height="20px" viewBox="15 0 10 10" enable-background="new 0 0 270 10" xml:space="preserve"><defs><style>.cls-1{isolation:isolate;}.cls-2{fill:#000;}</style></defs><g class="cls-1"><path class="cls-2" d="M1.65,11V2.45H2.87V3a2.81,2.81,0,0,1,.47-.45A1.13,1.13,0,0,1,4,2.38,1.11,1.11,0,0,1,5.1,3a1.55,1.55,0,0,1,.16.5,5.61,5.61,0,0,1,0,.81V6.58c0,.45,0,.77,0,1a1.17,1.17,0,0,1-.55.9,1.23,1.23,0,0,1-.7.16,1.35,1.35,0,0,1-.64-.16A1.53,1.53,0,0,1,2.89,8h0v3ZM4.08,4.43a1.21,1.21,0,0,0-.14-.6.51.51,0,0,0-.46-.22A.54.54,0,0,0,3,3.82a.8.8,0,0,0-.17.54V6.73A.68.68,0,0,0,3,7.2a.6.6,0,0,0,.44.18A.53.53,0,0,0,4,7.17a1,1,0,0,0,.12-.5Z"/><path class="cls-2" d="M8.63,8.54V7.91h0a2.24,2.24,0,0,1-.48.52,1.13,1.13,0,0,1-.69.18A1.39,1.39,0,0,1,7,8.54a1.09,1.09,0,0,1-.43-.24,1.32,1.32,0,0,1-.33-.49A2.33,2.33,0,0,1,6.11,7a4.89,4.89,0,0,1,.08-.91,1.51,1.51,0,0,1,.31-.65,1.44,1.44,0,0,1,.59-.38A3.19,3.19,0,0,1,8,4.93h.59V4.33a1,1,0,0,0-.13-.52A.52.52,0,0,0,8,3.61a.71.71,0,0,0-.44.15.78.78,0,0,0-.26.46H6.13A2,2,0,0,1,6.69,2.9a1.73,1.73,0,0,1,.57-.38A2,2,0,0,1,8,2.38a2.18,2.18,0,0,1,.72.12,1.71,1.71,0,0,1,.59.36,2,2,0,0,1,.38.6,2.18,2.18,0,0,1,.14.84V8.54Zm0-2.62-.34,0a1.2,1.2,0,0,0-.67.18.76.76,0,0,0-.29.68.89.89,0,0,0,.17.56A.55.55,0,0,0,8,7.53a.63.63,0,0,0,.49-.2.91.91,0,0,0,.17-.58Z"/><path class="cls-2" d="M13,4.16a.59.59,0,0,0-.2-.47.65.65,0,0,0-.42-.16.59.59,0,0,0-.45.19.66.66,0,0,0-.15.43.8.8,0,0,0,.08.33.85.85,0,0,0,.44.29l.71.29a1.73,1.73,0,0,1,.95.72,2,2,0,0,1,.26,1,1.85,1.85,0,0,1-.52,1.3,1.56,1.56,0,0,1-.58.39,1.88,1.88,0,0,1-2-.32,1.58,1.58,0,0,1-.4-.57,1.81,1.81,0,0,1-.17-.8h1.15a1.11,1.11,0,0,0,.17.47.56.56,0,0,0,.49.22.71.71,0,0,0,.47-.18A.59.59,0,0,0,13,6.8a.69.69,0,0,0-.13-.43,1.08,1.08,0,0,0-.48-.32l-.59-.21a2.08,2.08,0,0,1-.9-.64,1.66,1.66,0,0,1-.33-1,1.89,1.89,0,0,1,.14-.72,1.78,1.78,0,0,1,.4-.57,1.5,1.5,0,0,1,.56-.36,1.82,1.82,0,0,1,.7-.13,1.93,1.93,0,0,1,.69.13,1.6,1.6,0,0,1,.54.38,1.85,1.85,0,0,1,.36.57,1.82,1.82,0,0,1,.13.7Z"/><path class="cls-2" d="M17.2,4.16a.63.63,0,0,0-.2-.47.69.69,0,0,0-.43-.16.55.55,0,0,0-.44.19.62.62,0,0,0-.16.43.68.68,0,0,0,.09.33.81.81,0,0,0,.43.29l.72.29a1.7,1.7,0,0,1,.94.72,2,2,0,0,1,.26,1,1.85,1.85,0,0,1-.52,1.3,1.61,1.61,0,0,1-.57.39,1.81,1.81,0,0,1-.74.15,1.76,1.76,0,0,1-1.24-.47,1.61,1.61,0,0,1-.41-.57,2,2,0,0,1-.17-.8h1.15a1.12,1.12,0,0,0,.18.47.53.53,0,0,0,.48.22.72.72,0,0,0,.48-.18.59.59,0,0,0,.21-.48.69.69,0,0,0-.14-.43,1,1,0,0,0-.48-.32l-.58-.21a2.06,2.06,0,0,1-.91-.64,1.66,1.66,0,0,1-.33-1A1.89,1.89,0,0,1,15,3.44a1.78,1.78,0,0,1,.4-.57,1.58,1.58,0,0,1,.56-.36,1.82,1.82,0,0,1,.7-.13,1.93,1.93,0,0,1,.69.13,1.75,1.75,0,0,1,.55.38,1.85,1.85,0,0,1,.36.57,2,2,0,0,1,.13.7Z"/><path class="cls-2" d="M19.2,8.54V0h1.22V3h0a1.53,1.53,0,0,1,.48-.47,1.39,1.39,0,0,1,.65-.16,1.26,1.26,0,0,1,.69.16,1.35,1.35,0,0,1,.4.39,1.18,1.18,0,0,1,.15.51,7.72,7.72,0,0,1,0,1V6.73a5.56,5.56,0,0,1-.05.8,1.56,1.56,0,0,1-.15.5,1.12,1.12,0,0,1-1.07.58,1.15,1.15,0,0,1-.7-.18A3.79,3.79,0,0,1,20.42,8v.55Zm2.44-4.21a1,1,0,0,0-.13-.51A.5.5,0,0,0,21,3.61a.57.57,0,0,0-.44.18.66.66,0,0,0-.18.48V6.63a.83.83,0,0,0,.17.54.52.52,0,0,0,.45.21.49.49,0,0,0,.45-.22,1.11,1.11,0,0,0,.15-.6Z"/><path class="cls-2" d="M23.76,4.49a4.83,4.83,0,0,1,0-.68A1.55,1.55,0,0,1,24,3.26a1.59,1.59,0,0,1,.62-.64,1.84,1.84,0,0,1,1-.24,1.87,1.87,0,0,1,1,.24,1.59,1.59,0,0,1,.62.64,1.55,1.55,0,0,1,.18.55,4.83,4.83,0,0,1,.05.68v2a4.72,4.72,0,0,1-.05.68,1.55,1.55,0,0,1-.18.55,1.59,1.59,0,0,1-.62.64,1.87,1.87,0,0,1-1,.24,1.84,1.84,0,0,1-1-.24A1.59,1.59,0,0,1,24,7.73a1.55,1.55,0,0,1-.18-.55,4.72,4.72,0,0,1,0-.68ZM25,6.69a.72.72,0,0,0,.17.52.53.53,0,0,0,.43.17A.55.55,0,0,0,26,7.21a.72.72,0,0,0,.16-.52V4.3A.74.74,0,0,0,26,3.78a.55.55,0,0,0-.44-.17.53.53,0,0,0-.43.17A.74.74,0,0,0,25,4.3Z"/><path class="cls-2" d="M28.2,4.49a4.83,4.83,0,0,1,.05-.68,1.55,1.55,0,0,1,.18-.55,1.59,1.59,0,0,1,.62-.64,1.84,1.84,0,0,1,1-.24,1.87,1.87,0,0,1,1,.24,1.59,1.59,0,0,1,.62.64,1.55,1.55,0,0,1,.18.55,4.83,4.83,0,0,1,.05.68v2a4.72,4.72,0,0,1-.05.68,1.55,1.55,0,0,1-.18.55,1.59,1.59,0,0,1-.62.64,1.87,1.87,0,0,1-1,.24,1.84,1.84,0,0,1-1-.24,1.59,1.59,0,0,1-.62-.64,1.55,1.55,0,0,1-.18-.55,4.72,4.72,0,0,1-.05-.68Zm1.22,2.2a.72.72,0,0,0,.17.52.53.53,0,0,0,.43.17.55.55,0,0,0,.44-.17.72.72,0,0,0,.16-.52V4.3a.74.74,0,0,0-.16-.52A.55.55,0,0,0,30,3.61a.53.53,0,0,0-.43.17.74.74,0,0,0-.17.52Z"/><path class="cls-2" d="M32.75,8.54V0H34V5.11h0l1.47-2.66H36.7L35.24,4.93,37,8.54H35.66l-1.1-2.63L34,6.83V8.54Z"/></g></svg>

docs/index.md

@@ -0,0 +1,16 @@
+#
+![passbook logo](images/logo.svg){: style="height:50px"}
+![passbook brand](images/brand.svg){: style="height:50px"}
+
+## What is passbook?
+
+passbook is an open-source Identity Provider focused on flexibility and versatility. You can use passbook in an existing environment to add support for new protocols. passbook is also a great solution for implementing signup/recovery/etc in your application, so you don't have to deal with it.
+
+## Installation
+
+See [Docker-compose](installation/docker-compose.md) or [Kubernetes](installation/kubernetes.md)
+
+## Screenshots
+
+![](images/screen_apps.png)
+![](images/screen_admin.png)

docs/installation/docker-compose.md

@@ -0,0 +1,44 @@
+# docker-compose
+
+This installation method is for test-setups and small-scale productive setups.
+
+## Prerequisites
+
+- docker
+- docker-compose
+
+## Install
+
+Download the latest `docker-compose.yml` from [here](https://raw.githubusercontent.com/BeryJu/passbook/master/docker-compose.yml). Place it in a directory of your choice.
+
+To optionally enable error-reporting, run `echo PASSBOOK_ERROR_REPORTING__ENABLED=true >> .env`
+
+To optionally deploy a different version run `echo PASSBOOK_TAG=0.12.1-stable >> .env`
+
+If this is a fresh passbook install run the following commands to generate a password:
+
+```
+sudo apt-get install -y pwgen
+echo "PG_PASS=$(pwgen 40 1)" >> .env
+echo "PASSBOOK_SECRET_KEY=$(pwgen 50 1)" >> .env
+```
+
+Afterwards, run these commands to finish
+
+```
+docker-compose pull
+docker-compose up -d
+docker-compose run --rm server migrate
+```
+
+The compose file statically references the latest version available at the time of downloading, which can be overridden with the `SERVER_TAG` environment variable.
+
+If you plan to use this setup for production, it is also advised to change the PostgreSQL password by setting `PG_PASS` to a password of your choice.
+
+Now you can pull the Docker images needed by running `docker-compose pull`. After this has finished, run `docker-compose up -d` to start passbook.
+
+passbook will then be reachable via HTTP on port 80, and HTTPS on port 443. You can optionally configure the packaged traefik to use Let's Encrypt certificates for TLS Encryption.
+
+If you plan to access passbook via a reverse proxy which does SSL Termination, make sure you use the HTTPS port, so passbook is aware of the SSL connection.
+
+The initial setup process also creates a default admin user, the username and password for which is `pbadmin`. It is highly recommended to change this password as soon as you log in.

docs/installation/kubernetes.md

@@ -0,0 +1,76 @@
+# Kubernetes
+
+For a mid to high-load installation, Kubernetes is recommended. passbook is installed using a helm-chart.
+
+This installation automatically applies database migrations on startup. After the installation is done, you can use `pbadmin` as username and password.
+
+```yaml
+###################################
+# Values directly affecting passbook
+###################################
+image:
+  name: beryju/passbook
+  name_static: beryju/passbook-static
+  tag: 0.12.1-stable
+
+nameOverride: ""
+
+serverReplicas: 1
+workerReplicas: 1
+
+# Enable the Kubernetes integration which lets passbook deploy outposts into kubernetes
+kubernetesIntegration: true
+
+config:
+  # Optionally specify fixed secret_key, otherwise generated automatically
+  # secretKey: _k*@6h2u2@q-dku57hhgzb7tnx*ba9wodcb^s9g0j59@=y(@_o
+  # Enable error reporting
+  errorReporting:
+    enabled: false
+    environment: customer
+    sendPii: false
+  # Log level used by web and worker
+  # Can be either debug, info, warning, error
+  logLevel: warning
+
+# Enable Database Backups to S3
+# backup:
+#   accessKey: access-key
+#   secretKey: secret-key
+#   bucket: s3-bucket
+#   region: eu-central-1
+#   host: s3-host
+
+ingress:
+  annotations: {}
+    # kubernetes.io/ingress.class: nginx
+    # kubernetes.io/tls-acme: "true"
+  path: /
+  hosts:
+    - passbook.k8s.local
+  tls: []
+  #  - secretName: chart-example-tls
+  #    hosts:
+  #      - passbook.k8s.local
+
+###################################
+# Values controlling dependencies
+###################################
+
+install:
+  postgresql: true
+  redis: true
+
+# These values influence the bundled postgresql and redis charts, but are also used by passbook to connect
+postgresql:
+  postgresqlDatabase: passbook
+
+redis:
+  cluster:
+    enabled: false
+  master:
+    persistence:
+      enabled: false
+    # https://stackoverflow.com/a/59189742
+    disableCommands: []
+```

docs/installation/reverse-proxy.md

@@ -0,0 +1,42 @@
+# passbook behind a reverse-proxy
+
+If you want to access passbook behind a reverse-proxy, use a config like this. It is important that Websocket is enabled, so that Outposts can connect.
+
+```
+map $http_upgrade $connection_upgrade {
+    default upgrade;
+    ''      close;
+}
+
+server {
+    # Server config
+    listen 80;
+    server_name sso.domain.tld;
+
+    # 301 to SSL
+    location / {
+            return 301 https://$host$request_uri;
+    }
+}
+server {
+    # Server config
+    listen 443 ssl http2;
+    server_name sso.domain.tld;
+
+    # SSL Certs
+    ssl_certificate /etc/letsencrypt/live/domain.tld/fullchain.pem;
+    ssl_certificate_key /etc/letsencrypt/live/domain.tld/privkey.pem;
+
+    # Proxy site
+    location / {
+        proxy_pass https://<hostname of your passbook server>;
+        proxy_http_version 1.1;
+        proxy_set_header X-Forwarded-Proto https;
+        proxy_set_header X-Forwarded-Port 443;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header Host $http_host;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection $connection_upgrade;
+    }
+}
+```

docs/integrations/services/aws/index.md

@@ -0,0 +1,72 @@
+# Amazon Web Services Integration
+
+## What is AWS
+
+!!! note ""
+    Amazon Web Services (AWS) is the world’s most comprehensive and broadly adopted cloud platform, offering over 175 fully featured services from data centers globally. Millions of customers—including the fastest-growing startups, largest enterprises, and leading government agencies—are using AWS to lower costs, become more agile, and innovate faster.
+
+## Preparation
+
+The following placeholders will be used:
+
+- `passbook.company` is the FQDN of the passbook install.
+
+Create an application in passbook and note the slug, as this will be used later. Create a SAML provider with the following parameters:
+
+- ACS URL: `https://signin.aws.amazon.com/saml`
+- Audience: `urn:amazon:webservices`
+- Issuer: `passbook`
+- Binding: `Post`
+
+You can of course use a custom signing certificate, and adjust durations.
+
+## AWS
+
+Create a role with the permissions you desire, and note the ARN.
+
+After you've created the Property Mappings below, add them to the Provider.
+
+Create an application, assign policies, and assign this provider.
+
+Export the metadata from passbook, and create an Identity Provider [here](https://console.aws.amazon.com/iam/home#/providers).
+
+#### Role Mapping
+
+The Role mapping specifies the AWS ARN(s) of the identity provider, and the role the user should assume ([see](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_saml_assertions.html#saml_role-attribute)).
+
+This Mapping needs to have the SAML Name field set to "https://aws.amazon.com/SAML/Attributes/Role"
+
+As expression, you can return a static ARN like so
+
+```python
+return "arn:aws:iam::123412341234:role/saml_role,arn:aws:iam::123412341234:saml-provider/passbook"
+```
+
+Or, if you want to assign AWS Roles based on Group membership, you can add a custom attribute to the Groups, for example "aws_role", and use this snippet below. Groups are sorted by name and later groups overwrite earlier groups' attributes.
+
+```python
+role_name = user.group_attributes().get("aws_role", "")
+return f"arn:aws:iam::123412341234:role/{role_name},arn:aws:iam::123412341234:saml-provider/passbook"
+```
+
+If you want to allow a user to choose from multiple roles, use this snippet
+
+```python
+return [
+    "arn:aws:iam::123412341234:role/role_a,arn:aws:iam::123412341234:saml-provider/passbook",
+    "arn:aws:iam::123412341234:role/role_b,arn:aws:iam::123412341234:saml-provider/passbook",
+    "arn:aws:iam::123412341234:role/role_c,arn:aws:iam::123412341234:saml-provider/passbook",
+]
+```
+
+### RoleSessionName Mapping
+
+The RoleSessionMapping specifies what identifier will be shown at the top of the Management Console ([see](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_saml_assertions.html#saml_role-session-attribute)).
+
+This mapping needs to have the SAML Name field set to "https://aws.amazon.com/SAML/Attributes/RoleSessionName".
+
+To use the user's username, use this snippet
+
+```python
+return user.username
+```

docs/integrations/services/gitlab/index.md

@@ -0,0 +1,59 @@
+# GitLab Integration
+
+## What is GitLab
+
+From https://about.gitlab.com/what-is-gitlab/
+
+!!! note ""
+    GitLab is a complete DevOps platform, delivered as a single application. This makes GitLab unique and makes Concurrent DevOps possible, unlocking your organization from the constraints of a pieced together toolchain. Join us for a live Q&A to learn how GitLab can give you unmatched visibility and higher levels of efficiency in a single application across the DevOps lifecycle.
+
+## Preparation
+
+The following placeholders will be used:
+
+- `gitlab.company` is the FQDN of the GitLab Install
+- `passbook.company` is the FQDN of the passbook Install
+
+Create an application in passbook and note the slug, as this will be used later. Create a SAML provider with the following parameters:
+
+- ACS URL: `https://gitlab.company/users/auth/saml/callback`
+- Audience: `https://gitlab.company`
+- Issuer: `https://gitlab.company`
+- Binding: `Post`
+
+You can of course use a custom signing certificate, and adjust durations. To get the value for `idp_cert_fingerprint`, you can use a tool like [this](https://www.samltool.com/fingerprint.php).
+
+## GitLab Configuration
+
+Paste the following block in your `gitlab.rb` file, after replacing the placeholder values from above. The file is located in `/etc/gitlab`.
+
+```ruby
+gitlab_rails['omniauth_enabled'] = true
+gitlab_rails['omniauth_allow_single_sign_on'] = ['saml']
+gitlab_rails['omniauth_sync_email_from_provider'] = 'saml'
+gitlab_rails['omniauth_sync_profile_from_provider'] = ['saml']
+gitlab_rails['omniauth_sync_profile_attributes'] = ['email']
+gitlab_rails['omniauth_auto_sign_in_with_provider'] = 'saml'
+gitlab_rails['omniauth_block_auto_created_users'] = false
+gitlab_rails['omniauth_auto_link_saml_user'] = true
+gitlab_rails['omniauth_providers'] = [
+  {
+    name: 'saml',
+    args: {
+      assertion_consumer_service_url: 'https://gitlab.company/users/auth/saml/callback',
+      idp_cert_fingerprint: '4E:1E:CD:67:4A:67:5A:E9:6A:D0:3C:E6:DD:7A:F2:44:2E:76:00:6A',
+      idp_sso_target_url: 'https://passbook.company/application/saml/<passbook application slug>/sso/binding/post/',
+      issuer: 'https://gitlab.company',
+      name_identifier_format: 'urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress',
+      attribute_statements: {
+        email: ['urn:oid:1.3.6.1.4.1.5923.1.1.1.6'],
+        first_name: ['urn:oid:2.5.4.3'],
+        nickname: ['urn:oid:2.16.840.1.113730.3.1.241']
+      }
+    },
+    label: 'passbook'
+  }
+]
+```
+
+Afterwards, either run `gitlab-ctl reconfigure` if you're running GitLab Omnibus, or restart the container if you're using the container.

docs/integrations/services/harbor/index.md

@@ -0,0 +1,27 @@
+# Harbor Integration
+
+## What is Harbor
+
+From https://goharbor.io
+
+!!! note ""
+    Harbor is an open source container image registry that secures images with role-based access control, scans images for vulnerabilities, and signs images as trusted. A CNCF Incubating project, Harbor delivers compliance, performance, and interoperability to help you consistently and securely manage images across cloud native compute platforms like Kubernetes and Docker.
+
+## Preparation
+
+The following placeholders will be used:
+
+-   `harbor.company` is the FQDN of the Harbor install.
+-   `passbook.company` is the FQDN of the passbook install.
+
+Create an application in passbook. Create an OpenID provider with the following parameters:
+
+-   Client Type: `Confidential`
+-   Response types: `code (Authorization Code Flow)`
+-   JWT Algorithm: `RS256`
+-   Redirect URIs: `https://harbor.company/c/oidc/callback`
+-   Scopes: `openid`
+
+## Harbor
+
+![](./harbor.png)

docs/integrations/services/rancher/index.md

@@ -0,0 +1,28 @@
+# Rancher Integration
+
+## What is Rancher
+
+From https://rancher.com/products/rancher
+
+!!! note ""
+    An enterprise platform for managing Kubernetes Everywhere
+    Rancher is a platform built to address the needs of the DevOps teams deploying applications with Kubernetes, and the IT staff responsible for delivering an enterprise-critical service.
+
+## Preparation
+
+The following placeholders will be used:
+
+-   `rancher.company` is the FQDN of the Rancher install.
+-   `passbook.company` is the FQDN of the passbook install.
+
+Create an application in passbook and note the slug, as this will be used later. Create a SAML provider with the following parameters:
+
+-   ACS URL: `https://rancher.company/v1-saml/adfs/saml/acs`
+-   Audience: `https://rancher.company/v1-saml/adfs/saml/metadata`
+-   Issuer: `passbook`
+
+You can of course use a custom signing certificate, and adjust durations.
+
+## Rancher
+
+![](./rancher.png)

docs/integrations/services/sentry/index.md

@@ -0,0 +1,45 @@
+# Sentry Integration
+
+## What is Sentry
+
+From https://sentry.io
+
+!!! note ""
+    Sentry provides self-hosted and cloud-based error monitoring that helps all software
+    teams discover, triage, and prioritize errors in real-time.
+
+    One million developers at over fifty thousand companies already ship
+    better software faster with Sentry. Won’t you join them?
+
+## Preparation
+
+The following placeholders will be used:
+
+- `sentry.company` is the FQDN of the Sentry install.
+- `passbook.company` is the FQDN of the passbook install.
+
+Create an application in passbook. Create a SAML Provider with the following values
+
+- ACS URL: `https://sentry.company/saml/acs/<sentry organisation name>/`
+- Audience: `https://sentry.company/saml/metadata/<sentry organisation name>/`
+- Issuer: `passbook`
+- Service Provider Binding: `Post`
+- Property Mapping: Select all Autogenerated Mappings
+
+## Sentry
+
+**This guide assumes you've installed Sentry using [getsentry/onpremise](https://github.com/getsentry/onpremise)**
+
+Navigate to Settings -> Auth, and click on Configure next to SAML2
+
+![](./auth.png)
+
+In passbook, get the Metadata URL by right-clicking `Download Metadata` and selecting Copy Link Address, and paste that URL into Sentry.
+
+On the next screen, input these Values
+
+IdP User ID: `urn:oid:0.9.2342.19200300.100.1.1`
+User Email: `urn:oid:0.9.2342.19200300.100.1.3`
+First Name: `urn:oid:2.5.4.3`
+
+After confirming, Sentry will authenticate with passbook, and you should be redirected back to a page confirming your settings.

docs/integrations/services/sonarr/index.md

@@ -0,0 +1,37 @@
+# Sonarr Integration
+
+!!! note
+    These instructions apply to all projects in the *arr Family. If you use multiple of these projects, you can assign them to the same Outpost.
+
+## What is Sonarr
+
+From https://github.com/Sonarr/Sonarr
+
+!!! note ""
+    Sonarr is a PVR for Usenet and BitTorrent users. It can monitor multiple RSS feeds for new episodes of your favorite shows and will grab, sort and rename them. It can also be configured to automatically upgrade the quality of files already downloaded when a better quality format becomes available.
+
+
+## Preparation
+
+The following placeholders will be used:
+
+- `sonarr.company` is the FQDN of the Sonarr install.
+- `passbook.company` is the FQDN of the passbook install.
+
+Create an application in passbook. Create a Proxy Provider with the following values
+
+- Internal host
+
+    If Sonarr is running in docker, and you're deploying the passbook proxy on the same host, set the value to `http://sonarr:8989`, where sonarr is the name of your container.
+
+    If Sonarr is running on a different server than where you are deploying the passbook proxy, set the value to `http://sonarr.company:8989`.
+
+- External host
+
+    Set this to the external URL you will be accessing Sonarr from.
+
+## Deployment
+
+Create an outpost deployment for the provider you've created above, as described [here](../../../outposts/outposts.md). Deploy this Outpost either on the same host or a different host that can access Sonarr.
+
+The outpost will connect to passbook and configure itself.

docs/integrations/services/tautulli/index.md

@@ -0,0 +1,50 @@
+# Tautulli Integration
+
+## What is Tautulli
+
+From https://tautulli.com/
+
+!!! note
+    Tautulli is a 3rd party application that you can run alongside your Plex Media Server to monitor activity and track various statistics. Most importantly, these statistics include what has been watched, who watched it, when and where they watched it, and how it was watched. The only thing missing is "why they watched it", but who am I to question your 42 plays of Frozen. All statistics are presented in a nice and clean interface with many tables and graphs, which makes it easy to brag about your server to everyone else.
+
+## Preparation
+
+The following placeholders will be used:
+
+- `tautulli.company` is the FQDN of the Tautulli install.
+- `passbook.company` is the FQDN of the passbook install.
+
+## passbook Setup
+
+Because Tautulli requires valid HTTP Basic credentials, you must save your HTTP Basic Credentials in passbook. The recommended way to do this is to create a Group. Name the group "Tautulli Users", for example. For this group, add the following attributes:
+
+```yaml
+tautulli_user: username
+tautulli_password: password
+```
+
+Add all Tautulli users to the Group. You should also create a Group Membership Policy to limit access to the application.
+
+Create an application in passbook. Create a Proxy provider with the following parameters:
+
+- Internal host
+
+    If Tautulli is running in docker, and you're deploying the passbook proxy on the same host, set the value to `http://tautulli:3579`, where tautulli is the name of your container.
+
+    If Tautulli is running on a different server to where you are deploying the passbook proxy, set the value to `http://tautulli.company:3579`.
+
+- External host
+
+    Set this to the external URL you will be accessing Tautulli from.
+
+Enable the `Set HTTP-Basic Authentication` option. Set and `HTTP-Basic Username` and `HTTP-Basic Password` to `tautulli_user` and `tautulli_password` respectively. These values can be chosen freely, `tautulli_` is just used as a prefix for clarity.
+
+## Tautulli Setup
+
+In Tautulli, navigate to Settings and enable the "Show Advanced" option. Navigate to "Web Interface" on the sidebar, and ensure the Option `Use Basic Authentication` is checked.
+
+![](./tautulli.png)
+
+Save the settings, and restart Tautulli if prompted.
+
+Afterwards, you need to deploy an Outpost in front of Tautulli, as descried [here](../sonarr/index.md)

docs/integrations/services/tower-awx/index.md

@@ -0,0 +1,75 @@
+# Ansible Tower / AWX Integration
+
+## What is Tower
+
+From https://docs.ansible.com/ansible/2.5/reference_appendices/tower.html
+
+!!! note ""
+    Ansible Tower (formerly ‘AWX’) is a web-based solution that makes Ansible even more easy to use for IT teams of all kinds. It’s designed to be the hub for all of your automation tasks.
+
+    Tower allows you to control access to who can access what, even allowing sharing of SSH credentials without someone being able to transfer those credentials. Inventory can be graphically managed or synced with a wide variety of cloud sources. It logs all of your jobs, integrates well with LDAP, and has an amazing browsable REST API. Command line tools are available for easy integration with Jenkins as well. Provisioning callbacks provide great support for autoscaling topologies.
+
+!!! note
+    AWX is the open-source version of Tower. The term "AWX" will be used interchangeably throughout this document.
+
+## Preparation
+
+The following placeholders will be used:
+
+- `awx.company` is the FQDN of the AWX/Tower install.
+- `passbook.company` is the FQDN of the passbook install.
+
+Create an application in passbook and note the slug, as this will be used later. Create a SAML provider with the following parameters:
+
+- ACS URL: `https://awx.company/sso/complete/saml/`
+- Audience: `awx`
+- Service Provider Binding: Post
+- Issuer: `https://awx.company/sso/metadata/saml/`
+
+You can of course use a custom signing certificate, and adjust durations.
+
+## AWX Configuration
+
+Navigate to `https://awx.company/#/settings/auth` to configure SAML. Set the Field `SAML SERVICE PROVIDER ENTITY ID` to `awx`.
+
+For the fields `SAML SERVICE PROVIDER PUBLIC CERTIFICATE` and `SAML SERVICE PROVIDER PRIVATE KEY`, you can either use custom certificates, or use the self-signed pair generated by passbook.
+
+Provide metadata in the `SAML Service Provider Organization Info` field:
+
+```json
+{
+ "en-US": {
+  "name": "passbook",
+  "url": "https://passbook.company",
+  "displayname": "passbook"
+ }
+}
+```
+
+Provide metadata in the  `SAML Service Provider Technical Contact` and `SAML Service Provider Technical Contact` fields:
+
+```json
+{
+ "givenName": "Admin Name",
+ "emailAddress": "admin@company"
+}
+```
+
+In the `SAML Enabled Identity Providers` paste the following configuration:
+
+```json
+{
+ "passbook": {
+  "attr_username": "urn:oid:2.16.840.1.113730.3.1.241",
+  "attr_user_permanent_id": "urn:oid:0.9.2342.19200300.100.1.1",
+  "x509cert": "MIIDEjCCAfqgAwIBAgIRAJZ9pOZ1g0xjiHtQAAejsMEwDQYJKoZIhvcNAQELBQAwMDEuMCwGA1UEAwwlcGFzc2Jvb2sgU2VsZi1zaWduZWQgU0FNTCBDZXJ0aWZpY2F0ZTAeFw0xOTEyMjYyMDEwNDFaFw0yMDEyMjYyMDEwNDFaMFkxLjAsBgNVBAMMJXBhc3Nib29rIFNlbGYtc2lnbmVkIFNBTUwgQ2VydGlmaWNhdGUxETAPBgNVBAoMCHBhc3Nib29rMRQwEgYDVQQLDAtTZWxmLXNpZ25lZDCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAO/ktBYZkY9xAijF4acvzX6Q1K8KoIZeyde8fVgcWBz4L5FgDQ4/dni4k2YAcPdwteGL4nKVzetUzjbRCBUNuO6lqU4J4WNNX4Xg4Ir7XLRoAQeo+omTPBdpJ1p02HjtN5jT01umN3bK2yto1e37CJhK6WJiaXqRewPxh4lI4aqdj3BhFkJ3I3r2qxaWOAXQ6X7fg3w/ny7QP53//ouZo7hSLY3GIcRKgvdjjVM3OW5C3WLpOq5Dez5GWVJ17aeFCfGQ8bwFKde6qfYqyGcU9xHB36TtVHB9hSFP/tUFhkiSOxtsrYwCgCyXm4UTSpP+wiNyjKfFw7qGLBvA2hGTNw8CAwEAATANBgkqhkiG9w0BAQsFAAOCAQEAh9PeAqPRQk1/SSygIFADZBi08O/DPCshFwEHvJATIcTzcDD8UGAjXh+H5OlkDyX7KyrcaNvYaafCUo63A+WprdtdY5Ty6SBEwTYyiQyQfwM9BfK+imCoif1Ai7xAelD7p9lNazWq7JU+H/Ep7U7Q7LvpxAbK0JArt+IWTb2NcMb3OWE1r0gFbs44O1l6W9UbJTbyLMzbGbe5i+NHlgnwPwuhtRMh0NUYabGHKcHbhwyFhfGAQv2dAp5KF1E5gu6ZzCiFePzc0FrqXQyb2zpFYcJHXquiqaOeG7cZxRHYcjrl10Vxzki64XVA9BpdELgKSnupDGUEJsRUt3WVOmvZuA==",
+  "url": "https://passbook.company/application/saml/awx/login/",
+  "attr_last_name": "User.LastName",
+  "entity_id": "https://awx.company/sso/metadata/saml/",
+  "attr_email": "urn:oid:0.9.2342.19200300.100.1.3",
+  "attr_first_name": "urn:oid:2.5.4.3"
+ }
+}
+```
+
+`x509cert` is the certificate configured in passbook. Remove the `--BEGIN CERTIFICATE--` and `--END CERTIFICATE--` headers, then enter the cert as one non-breaking string.

docs/integrations/services/ubuntu-landscape/index.md

@@ -0,0 +1,58 @@
+# Ubuntu Landscape Integration
+
+## What is Ubuntu Landscape
+
+From https://en.wikipedia.org/wiki/Landscape_(software)
+
+!!! note ""
+
+    Landscape is a systems management tool developed by Canonical. It can be run on-premises or in the cloud depending on the needs of the user. It is primarily designed for use with Ubuntu derivatives such as Desktop, Server, and Core.
+
+!!! warning
+
+    This requires passbook 0.10.3 or newer.
+
+## Preparation
+
+The following placeholders will be used:
+
+ - `landscape.company` is the FQDN of the Landscape server.
+ - `passbook.company` is the FQDN of the passbook install.
+
+Landscape uses the OpenID-Connect Protocol for single-sign on.
+
+## passbook Setup
+
+Create an OAuth2/OpenID-Connect Provider with the default settings. Set the Redirect URIs to `https://landscape.company/login/handle-openid`. Select all Autogenerated Scopes.
+
+Keep Note of the Client ID and the Client Secret.
+
+Create an application and assign access policies to the application. Set the application's provider to the provider you've just created.
+
+## Landscape Setup
+
+On the Landscape Server, edit the file `/etc/landscape/service.conf` and add the following snippet under the `[landscape]` section:
+
+```
+oidc-issuer = https://passbook.company/application/o/<slug of the application you've created>/
+oidc-client-id = <client ID of the provider you've created>
+oidc-client-secret = <client Secret of the provider you've created>
+```
+
+Afterwards, run `sudo lsctl restart` to restart the Landscape services.
+
+## Appendix
+
+To make an OpenID-Connect User admin, you have to insert some rows into the database.
+
+First login with your passbook user, and make sure the user is created successfully.
+
+Run `sudo -u postgres psql landscape-standalone-main` on the Landscape server to open a PostgreSQL Prompt.
+Then run `select * from person;` to get a list of all users. Take note of the ID given to your new user.
+
+Run the following commands to make this user an administrator:
+
+```sql
+INSERT INTO person_account VALUES (<user id>, 1);
+INSERT INTO person_access VALUES (<user id>, 1, 1);
+```

docs/integrations/services/vmware-vcenter/index.md

@@ -0,0 +1,83 @@
+# VMware vCenter Integration
+
+## What is vCenter
+
+From https://en.wikipedia.org/wiki/VCenter
+
+!!! note ""
+
+    vCenter Server is the centralized management utility for VMware, and is used to manage virtual machines, multiple ESXi hosts, and all dependent components from a single centralized location. VMware vMotion and svMotion require the use of vCenter and ESXi hosts.
+
+!!! warning
+
+    This requires passbook 0.10.3 or newer.
+
+!!! warning
+
+    This requires VMware vCenter 7.0.0 or newer.
+
+!!! note
+
+    It seems that the vCenter still needs to be joined to the Active Directory Domain, otherwise group membership does not work correctly. We're working on a fix for this, for the meantime your vCenter should be part of your Domain.
+
+## Preparation
+
+The following placeholders will be used:
+
+ - `vcenter.company` is the FQDN of the vCenter server.
+ - `passbook.company` is the FQDN of the passbook install.
+
+Since vCenter only allows OpenID-Connect in combination with Active Directory, it is recommended to have passbook sync with the same Active Directory.
+
+### Step 1
+
+Under *Property Mappings*, create a *Scope Mapping*. Give it a name like "OIDC-Scope-VMware-vCenter". Set the scope name to `openid` and the expression to the following
+
+```python
+return {
+  "domain": "<your active directory domain>",
+}
+```
+
+### Step 2
+
+!!! note
+    If your Active Directory Schema is the same as your Email address schema, skip to Step 3.
+
+Under *Sources*, click *Edit* and ensure that "Autogenerated Active Directory Mapping: userPrincipalName -> attributes.upn" has been added to your source.
+
+### Step 3
+
+Under *Providers*, create an OAuth2/OpenID Provider with these settings:
+
+ - Client Type: Confidential
+ - Response Type: code (ADFS Compatibility Mode, sends id_token as access_token)
+ - JWT Algorithm: RS256
+ - Redirect URI: `https://vcenter.company/ui/login/oauth2/authcode`
+ - Post Logout Redirect URIs: `https://vcenter.company/ui/login`
+ - Sub Mode: If your Email address Schema matches your UPN, select "Based on the User's Email...", otherwise select "Based on the User's UPN...".
+ - Scopes: Select the Scope Mapping you've created in Step 1
+
+![](./passbook_setup.png)
+
+### Step 4
+
+Create an application which uses this provider. Optionally apply access restrictions to the application.
+
+Set the Launch URL to `https://vcenter.company/ui/login/oauth2`. This will skip vCenter's User Prompt and directly log you in.
+
+## vCenter Setup
+
+Login as local Administrator account (most likely ends with vsphere.local). Using the Menu in the Navigation bar, navigate to *Administration -> Single Sing-on -> Configuration*.
+
+Click on *Change Identity Provider* in the top-right corner.
+
+In the wizard, select "Microsoft ADFS" and click Next.
+
+Fill in the Client Identifier and Shared Secret from the Provider in passbook. For the OpenID Address, click on *View Setup URLs* in passbook, and copy the OpenID Configuration URL.
+
+On the next page, fill in your Active Directory Connection Details. These should be similar to what you have set in passbook.
+
+![](./vcenter_post_setup.png)
+
+If your vCenter was already setup with LDAP beforehand, your Role assignments will continue to work.

docs/integrations/sources/active-directory/index.md

@@ -0,0 +1,55 @@
+# Active Directory Integration
+
+## Preparation
+
+The following placeholders will be used:
+
+ - `ad.company` is the Name of the Active Directory domain.
+ - `passbook.company` is the FQDN of the passbook install.
+
+## Active Directory Setup
+
+1. Open Active Directory Users and Computers
+
+2. Create a user in Active Directory, matching your naming scheme
+
+    ![](./01_user_create.png)
+
+3. Give the User a password, generated using for example `pwgen 64 1`.
+
+4. Open the Delegation of Control Wizard by right-clicking the domain.
+
+5. Select the passbook service user you've just created.
+
+6. Ensure the "Reset user password and force password change at next logon" Option is checked.
+
+    ![](./02_delegate.png)
+
+## passbook Setup
+
+In passbook, create a new LDAP Source in Administration -> Sources.
+
+Use these settings:
+
+- Server URI: `ldap://ad.company`
+
+    For passbook to be able to write passwords back to Active Directory, make sure to use `ldaps://`
+
+- Bind CN: `<name of your service user>@ad.company`
+- Bind Password: The password you've given the user above
+- Base DN: The base DN which you want passbook to sync
+- Property Mappings: Select all and click the right arrow
+
+The other settings might need to be adjusted based on the setup of your domain.
+
+- Addition User/Group DN: Additional DN which is *prepended* to your Base DN for user synchronization.
+- Addition Group DN: Additional DN which is *prepended* to your Base DN for group synchronization.
+- User object filter: Which objects should be considered users.
+- Group object filter: Which objects should be considered groups.
+- User group membership field: Which user field saves the group membership
+- Object uniqueness field: A user field which contains a unique Identifier
+- Sync parent group: If enabled, all synchronized groups will be given this group as a parent.
+
+After you save the source, a synchronization will start in the background. When its done, you cen see the summary on the System Tasks page.
+
+![](./03_pb_status.png)

docs/maintenance/backups/index.md

@@ -0,0 +1,111 @@
+# Backup and restore
+
+!!! warning
+
+    Local backups are only supported for docker-compose installs. If you want to backup a Kubernetes instance locally, use an S3-compatible server such as [minio](https://min.io/)
+
+### Backup
+
+Local backups can be created by running the following command in your passbook installation directory
+
+```
+docker-compose run --rm worker backup
+```
+
+This will dump the current database into the `./backups` folder. By defaults, the last 10 Backups are kept.
+
+To schedule these backups, use the following snippet in a crontab
+
+```
+0 0 * * * bash -c "cd <passbook install location> && docker-compose run --rm worker backup" >/dev/null
+```
+
+!!! notice
+
+    passbook does support automatic backups on a schedule, however this is currently not recommended, as there is no way to monitor these scheduled tasks.
+
+### Restore
+
+Run this command in your passbook installation directory
+
+```
+docker-compose run --rm worker restore
+```
+
+This will prompt you to restore from your last backup. If you want to restore from a specific file, use the `-i` flag with the filename:
+
+```
+docker-compose run --rm worker restore -i default-2020-10-03-115557.psql
+```
+
+After you've restored the backup, it is recommended to restart all services with `docker-compose restart`.
+
+### S3 Configuration
+
+!!! notice
+
+    To trigger backups with S3 enabled, use the same commands as above.
+
+#### S3 Preparation
+
+passbook expects the bucket you select to already exist. The IAM User given to passbook should have the following permissions
+
+```json
+{
+    "Version": "2012-10-17",
+    "Statement": [
+        {
+            "Sid": "VisualEditor0",
+            "Effect": "Allow",
+            "Action": [
+                "s3:PutObject",
+                "s3:GetObjectAcl",
+                "s3:GetObject",
+                "s3:ListBucket",
+                "s3:DeleteObject",
+                "s3:PutObjectAcl"
+            ],
+            "Principal": {
+                "AWS": "arn:aws:iam::example-AWS-account-ID:user/example-user-name"
+            },
+            "Resource": [
+                "arn:aws:s3:::example-bucket-name/*",
+                "arn:aws:s3:::example-bucket-name"
+            ]
+        }
+    ]
+}
+```
+
+#### docker-compose
+
+Set the following values in your `.env` file.
+
+```
+PASSBOOK_POSTGRESQL__S3_BACKUP__ACCESS_KEY=
+PASSBOOK_POSTGRESQL__S3_BACKUP__SECRET_KEY=
+PASSBOOK_POSTGRESQL__S3_BACKUP__BUCKET=
+PASSBOOK_POSTGRESQL__S3_BACKUP__REGION=
+```
+
+If you want to backup to an S3-compatible server, like [minio](https://min.io/), use this setting:
+
+```
+PASSBOOK_POSTGRESQL__S3_BACKUP__HOST=http://play.min.io
+```
+
+#### Kubernetes
+
+Simply enable these options in your values.yaml file
+
+```yaml
+# Enable Database Backups to S3
+backup:
+  access_key: access-key
+  secret_key: secret-key
+  bucket: s3-bucket
+  region: eu-central-1
+  host: s3-host
+```
+
+Afterwards, run a `helm upgrade` to update the ConfigMap. Because passbook-scheduled backups are not recommended currently, a Kubernetes CronJob is created that runs the backup daily.

docs/outposts/deploy-docker-compose.md

@@ -0,0 +1,20 @@
+# Outpost deployment in docker-compose
+
+To deploy an outpost with docker-compose, use  this snippet in your docker-compose file.
+
+You can also run the outpost in a separate docker-compose project, you just have to ensure that the outpost container can reach your application container.
+
+```yaml
+version: '3.5'
+
+services:
+  passbook_proxy:
+    image: beryju/passbook-proxy:0.10.0-stable
+    ports:
+      - 4180:4180
+      - 4443:4443
+    environment:
+      PASSBOOK_HOST: https://your-passbook.tld
+      PASSBOOK_INSECURE: 'false'
+      PASSBOOK_TOKEN: token-generated-by-passbook
+```

docs/outposts/deploy-kubernetes.md

@@ -0,0 +1,99 @@
+# Outpost deployment on Kubernetes
+
+Use the following manifest, replacing all values surrounded with `__`.
+
+Afterwards, configure the proxy provider to connect to `<service name>.<namespace>.svc.cluster.local`, and update your Ingress to connect to the `passbook-outpost` service.
+
+```yaml
+apiVersion: v1
+kind: Secret
+metadata:
+  labels:
+    app.kubernetes.io/instance: test
+    app.kubernetes.io/managed-by: passbook.beryju.org
+    app.kubernetes.io/name: passbook-proxy
+    app.kubernetes.io/version: 0.10.0
+  name: passbook-outpost-api
+stringData:
+  passbook_host: '__PASSBOOK_URL__'
+  passbook_host_insecure: 'true'
+  token: '__PASSBOOK_TOKEN__'
+type: Opaque
+---
+apiVersion: v1
+kind: Service
+metadata:
+  labels:
+    app.kubernetes.io/instance: test
+    app.kubernetes.io/managed-by: passbook.beryju.org
+    app.kubernetes.io/name: passbook-proxy
+    app.kubernetes.io/version: 0.10.0
+  name: passbook-outpost
+spec:
+  ports:
+  - name: http
+    port: 4180
+    protocol: TCP
+    targetPort: http
+  - name: https
+    port: 4443
+    protocol: TCP
+    targetPort: https
+  selector:
+    app.kubernetes.io/instance: test
+    app.kubernetes.io/managed-by: passbook.beryju.org
+    app.kubernetes.io/name: passbook-proxy
+    app.kubernetes.io/version: 0.10.0
+  type: ClusterIP
+---
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  labels:
+    app.kubernetes.io/instance: test
+    app.kubernetes.io/managed-by: passbook.beryju.org
+    app.kubernetes.io/name: passbook-proxy
+    app.kubernetes.io/version: 0.10.0
+  name: passbook-outpost
+spec:
+  selector:
+    matchLabels:
+      app.kubernetes.io/instance: test
+      app.kubernetes.io/managed-by: passbook.beryju.org
+      app.kubernetes.io/name: passbook-proxy
+      app.kubernetes.io/version: 0.10.0
+  template:
+    metadata:
+      labels:
+        app.kubernetes.io/instance: test
+        app.kubernetes.io/managed-by: passbook.beryju.org
+        app.kubernetes.io/name: passbook-proxy
+        app.kubernetes.io/version: 0.10.0
+    spec:
+      containers:
+      - env:
+        - name: PASSBOOK_HOST
+          valueFrom:
+            secretKeyRef:
+              key: passbook_host
+              name: passbook-outpost-api
+        - name: PASSBOOK_TOKEN
+          valueFrom:
+            secretKeyRef:
+              key: token
+              name: passbook-outpost-api
+        - name: PASSBOOK_INSECURE
+          valueFrom:
+            secretKeyRef:
+              key: passbook_host_insecure
+              name: passbook-outpost-api
+        image: beryju/passbook-proxy:0.10.0-stable
+        name: proxy
+        ports:
+        - containerPort: 4180
+          name: http
+          protocol: TCP
+        - containerPort: 4443
+          name: https
+          protocol: TCP
+```

docs/outposts/outposts.md

@@ -0,0 +1,14 @@
+# Outposts
+
+An outpost is a single deployment of a passbook component, which can be deployed in a completely separate environment. Currently, only the Proxy Provider is supported as outpost.
+
+![](outposts.png)
+
+Upon creation, a service account and a token is generated. The service account only has permissions to read the outpost and provider configuration. This token is used by the Outpost to connect to passbook.
+
+To deploy an outpost, see: <a name="deploy">
+
+- [Kubernetes](deploy-kubernetes.md)
+- [docker-compose](deploy-docker-compose.md)
+
+In future versions, this snippet will be automatically generated. You will also be able to deploy an outpost directly into a kubernetes cluster.

docs/outposts/upgrading.md

@@ -0,0 +1,9 @@
+# Upgrading an Outpost
+
+In the Outpost Overview list, you'll see if any deployed outposts are out of date.
+
+![](./upgrading_outdated.png)
+
+To upgrade the Outpost to the latest version, simple adjust the docker tag of the outpost the the new version.
+
+Since the configuration is managed by passbook, that's all you have to do.

docs/policies/expression.md

@@ -0,0 +1,37 @@
+# Expression Policies
+
+!!! notice
+    These variables are available in addition to the common variables/functions defined in [**Expressions**](../expressions/index.md)
+
+The passing of the policy is determined by the return value of the code. Use `return True` to pass a policy and `return False` to fail it.
+
+### Available Functions
+
+#### `pb_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
+pb_message("Access denied")
+return False
+```
+
+### Context variables
+
+- `request`: A PolicyRequest object, which has the following properties:
+    - `request.user`: The current user, against which the policy is applied. ([ref](../expressions/reference/user-object.md))
+    - `request.http_request`: The Django HTTP Request. ([ref](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.
+    - `request.context`: A dictionary with dynamic data. This depends on the origin of the execution.
+- `pb_is_sso_flow`: Boolean which is true if request was initiated by authenticating through an external provider.
+- `pb_client_ip`: Client's IP Address or '255.255.255.255' if no IP Address could be extracted. Can be [compared](../expressions/index.md#comparing-ip-addresses)
+
+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:
+
+- `prompt_data`: Data which has been saved from a prompt stage or an external source.
+- `application`: The application the user is in the process of authorizing.
+- `pending_user`: The currently pending user

docs/policies/index.md

@@ -0,0 +1,42 @@
+# Policies
+
+## Kinds
+
+There are two different kinds of policies; Standard Policy and Password Policy. Normal policies evaluate to True or False, and can be used everywhere. Password policies apply when a password is set (during user enrollment, recovery or anywhere else). These policies can be used to apply password rules such as length, complexity, etc. They can also be used to expire passwords after a certain amount of time.
+
+## Standard Policies
+
+---
+
+### Reputation Policy
+
+passbook keeps track of failed login attempts by source IP and attempted username. These values are saved as scores. Each failed login decreases the score for the client IP as well as the targeted username by 1 (one).
+
+This policy can be used, for example, to prompt clients with a low score to pass a captcha before they can continue.
+
+## Expression Policy
+
+See [Expression Policy](expression.md).
+
+## Password Policies
+
+---
+
+### Password Policy
+
+This policy allows you to specify password rules, such as length and required characters.
+The following rules can be set:
+
+- Minimum amount of uppercase characters.
+- Minimum amount of lowercase characters.
+- Minimum amount of symbols characters.
+- Minimum length.
+- Symbol charset (define which characters are counted as symbols).
+
+### Have I Been Pwned Policy
+
+This policy checks the hashed password against the [Have I Been Pwned](https://haveibeenpwned.com/) API. This only sends the first 5 characters of the hashed password. The remaining comparison is done within passbook.
+
+### Password-Expiry Policy
+
+This policy can enforce regular password rotation by expiring set passwords after a finite amount of time. This forces users to set a new password.

docs/property-mappings/expression.md

@@ -0,0 +1,12 @@
+# Property Mapping Expressions
+
+The property mapping should return a value that is expected by the Provider/Source. Supported types are documented in the individual Provider/Source. Returning `None` is always accepted and would simply skip the mapping for which `None` was returned.
+
+!!! notice
+    These variables are available in addition to the common variables/functions defined in [**Expressions**](../expressions/index.md)
+
+### Context Variables
+
+- `user`: The current user. This may be `None` if there is no contextual user. ([ref](../expressions/reference/user-object.md))
+- `request`: The current request. This may be `None` if there is no contextual request. ([ref](https://docs.djangoproject.com/en/3.0/ref/request-response/#httprequest-objects))
+- Other arbitrary arguments given by the provider, this is documented on the Provider/Source.

docs/property-mappings/index.md

@@ -0,0 +1,25 @@
+# Property Mappings
+
+Property Mappings allow you to pass information to external applications. For example, pass the current user's groups as a SAML parameter. Property Mappings are also used to map Source fields to passbook fields, for example when using LDAP.
+
+## SAML Property Mapping
+
+SAML Property Mappings allow you embed information into the SAML AuthN request. This information can then be used by the application to, for example, assign permissions to the object.
+
+You can find examples [here](integrations/).
+
+## LDAP Property Mapping
+
+LDAP Property Mappings are used when you define a LDAP Source. These mappings define which LDAP property maps to which passbook property. By default, the following mappings are created:
+
+- Autogenerated LDAP Mapping: givenName -> first_name
+- Autogenerated LDAP Mapping: mail -> email
+- Autogenerated LDAP Mapping: name -> name
+- Autogenerated LDAP Mapping: sAMAccountName -> username
+- Autogenerated LDAP Mapping: sn -> last_name
+
+These are configured with most common LDAP setups.
+
+## Scope Mapping
+
+Scope Mappings are used by the OAuth2 Provider to map information from passbook to OAuth2/OpenID Claims.

docs/providers/oauth2.md

@@ -0,0 +1,31 @@
+# OAuth2 Provider
+
+This provider supports both generic OAuth2 as well as OpenID Connect
+
+Scopes can be configured using Scope Mappings, a type of [Property Mappings](../property-mappings/index.md#scope-mapping).
+
+Endpoint | URL
+---------|---
+Authorization        | `/application/o/authorize/`
+Token                | `/application/o/token/`
+User Info            | `/application/o/userinfo/`
+End Session          | `/application/o/end-session/`
+Introspect           | `/application/o/end-session/`
+JWKS                 | `/application/o/<application slug>/jwks/`
+OpenID Configuration | `/application/o/<application slug>/.well-known/openid-configuration`
+
+## GitHub Compatibility
+
+This provider also exposes a GitHub-compatible endpoint. This endpoint can be used by applications, which support authenticating against GitHub Enterprise, but not generic OpenID Connect.
+
+To use any of the GitHub Compatibility scopes, you have to use the GitHub Compatibility Endpoints.
+
+
+Endpoint | URL
+---------|---
+Authorization        | `/login/oauth/authorize`
+Token                | `/login/oauth/access_token`
+User Info            | `/user`
+User Teams Info      | `/user/teams`
+
+To access the user's email address, a scope of `user:email` is required. To access their groups, `read:org` is required. Because these scopes are handled by a different endpoint, they are not customisable as a Scope Mapping.

docs/providers/proxy.md

@@ -0,0 +1,16 @@
+# Proxy Provider
+
+!!! info
+    This provider is to be used in conjunction with [Outposts](../outposts/outposts.md)
+
+This provider protects applications, which have no built-in support for OAuth2 or SAML. This is done by running a lightweight Reverse Proxy in front of the application, which authenticates the requests.
+
+passbook Proxy is based on [oauth2_proxy](https://github.com/oauth2-proxy/oauth2-proxy), but has been integrated more tightly with passbook.
+
+The Proxy these extra headers to the application:
+
+Header Name | Value
+-------------|-------
+X-Auth-Request-User | The user's unique identifier
+X-Auth-Request-Email | The user's email address
+X-Auth-Request-Preferred-Username | The user's username

docs/providers/saml.md

@@ -0,0 +1,12 @@
+# SAML Provider
+
+This provider allows you to integrate enterprise software using the SAML2 Protocol. It supports signed requests and 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".
+
+
+Endpoint | URL
+---------|---
+SSO (Redirect binding) | `/application/saml/<application slug>/sso/binding/redirect/`
+SSO (POST binding) | `/application/saml/<application slug>/sso/binding/post/`
+IdP-initiated login | `/application/saml/<application slug>/sso/binding/init/`
+Metadata Download | `/application/saml/<application slug>/metadata/`

docs/requirements.txt

@@ -0,0 +1,2 @@
+mkdocs
+mkdocs-material

docs/runtime.txt

@@ -0,0 +1 @@
+3.7

docs/sources.md

@@ -0,0 +1,39 @@
+# Sources
+
+Sources allow you to connect passbook to an existing user directory. They can also be used for social logins, using external providers such as Facebook, Twitter, etc.
+
+## Generic OAuth Source
+
+**All Integration-specific Sources are documented in the Integrations Section**
+
+This source allows users to enroll themselves with an external OAuth-based Identity Provider. The generic provider expects the endpoint to return OpenID-Connect compatible information. Vendor-specific implementations have their own OAuth Source.
+
+-   Policies: Allow/Forbid users from linking their accounts with this provider.
+-   Request Token URL: This field is used for OAuth v1 implementations and will be provided by the provider.
+-   Authorization URL: This value will be provided by the provider.
+-   Access Token URL: This value will be provided by the provider.
+-   Profile URL: This URL is called by passbook to retrieve user information upon successful authentication.
+-   Consumer key/Consumer secret: These values will be provided by the provider.
+
+## SAML Source
+
+This source allows passbook to act as a SAML Service Provider. Just like the SAML Provider, it supports signed requests. Vendor-specific documentation can be found in the Integrations Section.
+
+## LDAP Source
+
+This source allows you to import users and groups from an LDAP Server.
+
+-   Server URI: URI to your LDAP server/Domain Controller.
+-   Bind CN: CN of the bind user. This can also be a UPN in the format of `user@domain.tld`.
+-   Bind password: Password used during the bind process.
+-   Enable StartTLS: Enables StartTLS functionality. To use LDAPS instead, use port `636`.
+-   Base DN: Base DN used for all LDAP queries.
+-   Addition User DN: Prepended to the base DN for user queries.
+-   Addition Group DN: Prepended to the base DN for group queries.
+-   User object filter: Consider objects matching this filter to be users.
+-   Group object filter: Consider objects matching this filter to be groups.
+-   User group membership field: This field contains the user's group memberships.
+-   Object uniqueness field: This field 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 the parent group for all synced groups. An example use case of this would be to import Active Directory 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/index.md#ldap-property-mapping)

docs/terminology.md

@@ -0,0 +1,27 @@
+### Policy
+
+At a base level a policy is a yes/no gate. It will either evaluate to True or False depending on the Policy Kind and settings. For example, a "Group Membership Policy" evaluates to True if the user is member of the specified Group and False if not. This can be used to conditionally apply Stages, grant/deny access to various objects, and for other custom logic.
+
+### Provider
+
+A Provider is a way for other applications to authenticate against passbook. Common Providers are OpenID Connect (OIDC) and SAML.
+
+### Source
+
+Sources are locations from which users can be added to passbook. For example, an LDAP Connection to import Users from Active Directory, or an OAuth2 Connection to allow Social Logins.
+
+### Application
+
+An application links together Policies with a Provider, allowing you to control access. It also holds Information like UI Name, Icon and more.
+
+### Stages
+
+A stage represents a single verification or logic step. They are used to authenticate users, enroll users, and more. These stages can optionally be applied to a flow via policies.
+
+### Flows
+
+Flows are an ordered sequence of stages. These flows can be used to define how a user authenticates, enrolls, etc.
+
+### Property Mappings
+
+Property Mappings allow you to make information available for external applications. For example, if you want to login to AWS with passbook, you'd use Property Mappings to set the user's roles in AWS based on their group memberships in passbook.

docs/troubleshooting/access.md

@@ -0,0 +1,11 @@
+# Troubleshooting access problems
+
+## I get an access denied error when trying to access an application.
+
+If your user is a superuser, or has the attribute `passbook_user_debug` set to true:
+
+![](./passbook_user_debug.png)
+
+Afterwards, try to access the application again. You will now see a message explaining which policy denied you access:
+
+![](./access_denied_message.png)