From 218acb9e38159b156a7f17482c34e4ad42384973 Mon Sep 17 00:00:00 2001 From: Jens Langhammer Date: Thu, 12 Dec 2019 18:00:23 +0100 Subject: [PATCH] docs: add providers and sources --- docs/providers.md | 16 ++++++++++++++++ docs/sources.md | 39 +++++++++++++++++++++++++++++++++++++++ mkdocs.yml | 26 ++++++++++++++------------ 3 files changed, 69 insertions(+), 12 deletions(-) create mode 100644 docs/providers.md create mode 100644 docs/sources.md diff --git a/docs/providers.md b/docs/providers.md new file mode 100644 index 000000000..8e896e402 --- /dev/null +++ b/docs/providers.md @@ -0,0 +1,16 @@ +# Providers + +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 also has [Property Mappings](property-mappings.md#saml-property-mapping), which allows you to expose Vendor-specific Fields. diff --git a/docs/sources.md b/docs/sources.md new file mode 100644 index 000000000..66193eaf7 --- /dev/null +++ b/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-Login, using external Providers like 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 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 Start TLS: 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.md#ldap-property-mapping) diff --git a/mkdocs.yml b/mkdocs.yml index c3d12773e..8cdf94595 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -3,21 +3,23 @@ site_url: https://docs.passbook.beryju.org copyright: "Copyright © 2019 - 2020 BeryJu.org" nav: - - Home: index.md - - Installation: - - Installation: installation/install.md - - docker-compose: installation/docker-compose.md - - Kubernetes: installation/kubernetes.md - - Policies: policies.md - - Factors: factors.md - - Property Mappings: property-mappings.md + - Home: index.md + - Installation: + - Installation: installation/install.md + - docker-compose: installation/docker-compose.md + - Kubernetes: installation/kubernetes.md + - Sources: sources.md + - Providers: providers.md + - Property Mappings: property-mappings.md + - Factors: factors.md + - Policies: policies.md repo_name: "BeryJu.org/passbook" repo_url: https://git.beryju.org/BeryJu.org/passbook theme: - name: "material" - logo: "images/logo.svg" + name: "material" + logo: "images/logo.svg" markdown_extensions: - - toc: - permalink: "¶" + - toc: + permalink: "¶"