whenever a user tries to access an application without being authenticated to passbook, we now show notice which application they are going to continue to.
* flows: introduce FlowPlan markers, which indicate when a stage needs re-evaluation
Implement re_evaluate_policies
add unittests for several different scenarios
closes#78
* flows: move markers to separate files, cleanup formatting
* flows: fix self.next is not callable
* core: start migrating to flows for authorisation
* sources/oauth: start type-hinting
* core: create default user
* core: only show user delete button if an unenrollment flow exists
* flows: Correctly check initial policies on flow with context
* policies: add more verbosity to engine
* sources/oauth: migrate to flows
* sources/oauth: fix typing errors
* flows: add more tests
* sources/oauth: start implementing unittests
* sources/ldap: add option to disable user sync, move connection init to model
* sources/ldap: re-add default PropertyMappings
* providers/saml: re-add default PropertyMappings
* admin: fix missing stage count
* stages/identification: fix sources not being shown
* crypto: fix being unable to save with private key
* crypto: re-add default self-signed keypair
* policies: rewrite cache_key to prevent wrong cache
* sources/saml: migrate to flows for auth and enrollment
* stages/consent: add new stage
* admin: fix PropertyMapping widget not rendering properly
* core: provider.authorization_flow is mandatory
* flows: add support for "autosubmit" attribute on form
* flows: add InMemoryStage for dynamic stages
* flows: optionally allow empty flows from FlowPlanner
* providers/saml: update to authorization_flow
* sources/*: fix flow executor URL
* flows: fix pylint error
* flows: wrap responses in JSON object to easily handle redirects
* flow: dont cache plan's context
* providers/oauth: rewrite OAuth2 Provider to use flows
* providers/*: update docstrings of models
* core: fix forms not passing help_text through safe
* flows: fix HttpResponses not being converted to JSON
* providers/oidc: rewrite to use flows
* flows: fix linting
* policies/expression: migrate to raw python instead of jinja2
* lib/expression: create base evaluator, custom subclass for policies
* core: rewrite propertymappings to use python
* providers/saml: update to new PropertyMappings
* sources/ldap: update to new PropertyMappings
* docs: update docs for new propertymappings
* root: remove jinja2
* root: re-add jinja to lock file as its implicitly required
default_context can be used to influence policies during the planning. This should be used when the Planner is called from other views to correctly preseed the plan.
This also checks if there is a PENDING_USER set, and uses that user for the cache key instead
bootstrap now exits (0) when all services are up, instead continuously running. This is combined with a simple bash script, which does this job instead.
This also adds /bootstrap.sh as docker ENTRYPOINT
move can_handle calls to binding endpoints (/login/ and /login/initiate/), so that /login/authorize/ works either way, can clean up the session and audit
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.
# If this is a productive installation, set a different PostgreSQL Password
# export PG_PASS=$(pwgen 40 1)
docker-compose pull
docker-compose up -d
docker-compose exec server ./manage.py migrate
docker-compose exec server ./manage.py createsuperuser
docker-compose run --rm server migrate
```
For bigger setups, there is a Helm Chart in the `helm/` directory. This is documented [here](https://passbook.beryju.org//installation/kubernetes/)
## Screenshots
## 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:
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)
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:
A factor represents a single authenticating factor for a user. Common examples of this would be a password or an OTP. These factors can be combined in any order, and can be dynamically enabled using policies.
## Password Factor
This is the standard Password Factor. It allows you to select which Backend the password is checked with. here you can also specify which Policies are used to check the password. You can also specify which Factors a User has to pass to recover their account.
## Dummy Factor
This factor waits a random amount of time. Mostly used for debugging.
## E-Mail Factor
This factor is mostly for recovery, and used in conjunction with the Password Factor.
## OTP Factor
This is your typical One-Time Password implementation, compatible with Authy and Google Authenticator. You can enfore this Factor so that every user has to configure it, or leave it optional.
## Captcha Factor
While this factor doesn't really authenticate a user, it is part of the Authentication Flow. passbook uses Google's reCaptcha implementation.
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.
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.
### Change Password
This designates a flow for password changes. This flow can 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.
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.
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?`.
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.
Welcome to the passbook Documentation. passbook is an open-source Identity Provider and Usermanagement software. It can be used as a central directory for users or customers and it can integrate with your existing Directory.
## What is passbook?
passbook can also be used as part of an Application to facilitate User Enrollment, Password recovery and Social Login.
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.
passbook uses the following Terminology:
## Installation
### Policy
See [Docker-compose](installation/docker-compose.md) or [Kubernetes](installation/kubernetes.md)
A Policy is at a base level 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 Factors and grant/deny access.
## Screenshots
### Provider
A Provider is a way for other Applications to authenticate against passbook. Common Providers are OpenID Connect (OIDC) and SAML.
### Source
Sources are ways to get users into passbook. This might be 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.
### Factors
Factors represent Authentication Factors, like a Password or OTP. These Factors can be dynamically enabled using policies. This allows you to, for example, force users from a certain IP ranges to complete a Captcha to authenticate.
### 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 based on their Groups.
This installation Method is for test-setups and small-scale productive setups.
This installation method is for test-setups and small-scale productive setups.
## Prerequisites
@ -11,16 +11,25 @@ This installation Method is for test-setups and small-scale productive setups.
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.
passbook needs to know it's primary URL to create links in E-Mails and set cookies, so you have to run the following command:
```
export PASSBOOK_DOMAIN=domain.tld # this can be any domain or IP, it just needs to point to passbook.
# If this is a productive installation, set a different PostgreSQL Password
# export PG_PASS=$(pwgen 40 1)
docker-compose pull
docker-compose up -d
docker-compose run --rm server migrate
```
The compose file references the current latest version, which can be overridden with the `SERVER_TAG`Environment variable.
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.
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 on Port 80. You can optionally configure the packaged traefik to use Let's Encrypt for TLS Encryption.
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.
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.
For a mid to high-load Installation, Kubernetes is recommended. passbook is installed using a helm-chart.
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.
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).
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).
An Enterprise Platform for Managing Kubernetes Everywhere
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
-`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:
Create an application in passbook and note the slug, as this will be used later. Create a SAML provider with the following parameters:
@ -10,30 +10,30 @@ From https://docs.ansible.com/ansible/2.5/reference_appendices/tower.html
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, and AWX will be used interchangeably throughout this document.
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
-`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:
Create an application in passbook and note the slug, as this will be used later. Create a SAML provider with the following parameters:
You can of course use a custom Signing Certificate, and adjust durations.
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.
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:
Provide metadata in the `SAML Service Provider Organization Info`field:
```json
{
@ -45,7 +45,7 @@ Provide Metadata in the `SAML Service Provider Organization Info` Field:
}
```
Provide Metadata in the `SAML Service Provider Technical Contact` and `SAML Service Provider Technical Contact`Fields:
Provide metadata in the `SAML Service Provider Technical Contact` and `SAML Service Provider Technical Contact`fields:
```json
{
@ -71,4 +71,4 @@ In the `SAML Enabled Identity Providers` paste the following configuration:
}
```
`x509cert` is the Certificate configured in passbook. Remove the --BEGIN CERTIFICATE-- and --END CERTIFICATE-- headers, then enter the cert as one non-breaking string.
`x509cert` is the certificate configured in passbook. Remove the `--BEGIN CERTIFICATE--` and `--END CERTIFICATE--` headers, then enter the cert as one non-breaking string.
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.
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, you can for example use this docker-compose snippet:
```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:'true'
PASSBOOK_TOKEN:token-generated-by-passbook
```
In future versions, this snippet will be automatically generated. You will also be able to deploy an outpost directly into a kubernetes cluster.w
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")
returnFalse
```
### 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)
-`pb_flow_plan`: Current Plan if Policy is called from the Flow Planner.
Expression Policies allows you to write custom Policy Logic using Jinja2 Templating language.
For a language reference, see [here](https://jinja.palletsprojects.com/en/2.11.x/templates/).
The following objects are passed into the variable:
-`request`: A PolicyRequest object, which has the following properties:
-`request.user`: The current User, which the Policy is applied against. ([ref](../../property-mappings/reference/user-object.md))
-`request.http_request`: The Django HTTP Request, as documented [here](https://docs.djangoproject.com/en/3.0/ref/request-response/#httprequest-objects).
-`request.obj`: A Django Model instance. This is only set if the Policy is ran against an object.
-`pb_is_sso_flow`: Boolean which is true if request was initiated by authenticating through an external Provider.
-`pb_is_group_member(user, group_name)`: Function which checks if `user` is member of a Group with Name `gorup_name`.
-`pb_logger`: Standard Python Logger Object, which can be used to debug expressions.
-`pb_client_ip`: Client's IP Address.
There are also the following custom filters available:
-`regex_match(regex)`: Return True if value matches `regex`
-`regex_replace(regex, repl)`: Replace string matched by `regex` with `repl`
There are two different Kind of policies, a Standard Policy and a Password Policy. Normal Policies just 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 like length, etc. The can also be used to expire passwords after a certain amount of time.
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
---
### Group-Membership Policy
This policy evaluates to True if the current user is a Member of the selected group.
### 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 one.
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 to for example prompt Clients with a low score to pass a Captcha before they can continue.
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/index.md).
### Webhook Policy
This policy allows you to send an arbitrary HTTP Request to any URL. You can then use JSONPath to extract the result you need.
See [Expression Policy](expression.md).
## Password Policies
@ -32,19 +24,19 @@ This policy allows you to send an arbitrary HTTP Request to any URL. You can the
### Password Policy
This Policy allows you to specify Password rules, like Length and required Characters.
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)
- 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.
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.
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.
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.
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.
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 assign permissions for example.
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/)
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, these mappings are created:
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:
Providers allow external Applications to authenticate against passbook and use its User Information.
## OpenID Provider
This provider uses the commonly used OpenID Connect variation of OAuth2.
## OAuth2 Provider
This provider is slightly different than the OpenID Provider. While it uses the same basic OAuth2 Protocol, it provides a GitHub-compatible Endpoint. This allows you to integrate Applications, which don't support Custom OpenID Providers.
The API exposes Username, E-Mail, Name and Groups in a GitHub-compatible format.
## SAML Provider
This provider allows you to integrate Enterprise Software using the SAML2 Protocol. It supports signed Requests. This Provider 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..."
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.
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
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".
Sources allow you to connect passbook to an existing User directory. They can also be used for Social-Login, using external Providers like Facebook, Twitter, etc.
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. Vendorspecific Implementations have their own OAuth Source.
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.
- 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. Vendorspecific documentation can be found in the Integrations Section
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
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 to bind as, 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 SSL instead, use port `636`
- Base DN: Base DN used for all LDAP queries
- Addition User DN: Prepended to Base DN for User-queries.
- Addition Group DN: Prepended to 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: Field which contains Groups of user.
- Object uniqueness field: Field which contains a unique Identifier.
- Sync groups: Enable/disable Group synchronization. Groups are synced in the background every 5 minutes.
- Sync parent group: Optionally set this Group as parent Group for all synced Groups (allows you to, for example, import AD Groups under a root `imported-from-ad` group.)
- Property mappings: Define which LDAP Properties map to which passbook Properties. The default set of Property Mappings is generated for Active Directory. See also [LDAP Property Mappings](property-mappings/index.md#ldap-property-mapping)
- 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 userqueries.
- Addition Group DN: Prepended to the base DN for groupqueries.
- 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)
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.
This update brings a lot of big features, such as:
- New OAuth2/OpenID Provider
This new provider merges both OAuth2 and OpenID. It is based on the codebase of the old provider, which has been simplified and cleaned from the ground up. Support for Property Mappings has also been added. Because of this change, OpenID and OAuth2 Providers will have to be re-created.
- Proxy Provider
Due to this new OAuth2 Provider, the Application Gateway Provider, now simply called "Proxy Provider" has been revamped as well. The new passbook Proxy integrates more tightly with passbook via the new Outposts system. The new proxy also supports multiple applications per proxy instance, can configure TLS based on passbook Keypairs, and more.
See [Proxy](../providers/proxy.md)
- Outpost System
This is a new Object type, currently used only by the Proxy Provider. It manages the creation and permissions of service accounts, which are used by the outposts to communicate with passbook.
See [Outposts](../outposts/outposts.md)
- Flow Import/Export
Flows can now be imported and exported. This feature can be used as a backup system, or to share complex flows with other people. Example flows have also been added to the documentation to help you get going with passbook.
## Under the hood
- passbook now runs on Django 3.1 and Channels with complete ASGI enabled
- uwsgi has been replaced with Gunicorn and uvicorn
- Elastic APM has been replaced with Sentry Performance metrics
- Flow title is now configurable separately from the name
- All logging output is now json
## Upgrading
### docker-compose
The docker-compose file has been updated, please download the latest from `https://raw.githubusercontent.com/BeryJu/passbook/master/docker-compose.yml`.
By default, the new compose file uses a fixed version to prevent unintended updates.
Before updating the file, stop all containers. Then download the file, pull the new containers and start the database.
```
docker-compose down
docker-compose pull
docker-compose up --no-start
docker-compose start redis postgrseql
docker-compose run --rm server migrate
docker-compose up -d
```
### Helm
A few options have changed:
-`error_reporting` was changed from a simple boolean to a dictionary:
```yaml
error_reporting:
enabled:false
environment:customer
send_pii:false
```
- The `apm` and `monitoring` blocks have been removed.
-`serverReplicas` and `workerReplicas` have been added
### Upgrading
This upgrade only applies if you are upgrading from a running 0.9 instance. Passbook detects this on startup, and automatically executes this upgrade.
Because this upgrade brings the new OAuth2 Provider, the old providers will be lost in the process. Make sure to take note of the providers you want to bring over.
Another side-effect of this upgrade is the change of OAuth2 URLs, see [here](../providers/oauth2.md).
Due to some database changes that had to be rather sooner than later, there is no possibility to directly upgrade. You must extract the data before hand and import it again. It is recommended to spin up a second instance of passbook to do this.
To export data from your old instance, run this command:
After that, create a new passbook instance in a different namespace (kubernetes) or in a different folder (docker-compose). Once this instance is running, you can use the following commands to restore the data. On docker-compose, you still have to run the `migrate` command, to create all database structures.
<buttontype="submit"class="btn">Sign in with passbook</button><br/>
</form>
</div>
<script>
if(window.location.hash){
(function(){
varinputs=document.getElementsByName('rd');
for(vari=0;i<inputs.length;i++){
inputs[i].value+=window.location.hash;
}
})();
}
</script>
</body>
</html>
{{end}}
Some files were not shown because too many files have changed in this diff
Show More
Reference in New Issue
Block a user
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
