docs: improve documentation for providers

docs/property-mappings/index.md

@@ -19,3 +19,7 @@ LDAP Property Mappings are used when you define a LDAP Source. These mappings de
 - 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.md

@@ -1,24 +0,0 @@
-# Providers
-
-Providers allow external applications to authenticate against passbook and use its user information.
-
-## OpenID Provider
-
-This provider utilises 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, email, name, and groups in a GitHub-compatible format.
-This provider currently supports the following scopes:
-
-- `openid`: Access OpenID Userinfo
-- `userinfo`: Access OpenID Userinfo
-- `email`: Access OpenID Email
-- `user:email`: GitHub Compatibility: User Email
-- `read:org`: GitHub Compatibility: User Groups
-
-## 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".

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/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/`

mkdocs.yml

@@ -26,7 +26,9 @@ nav:
       - User Logout Stage: flow/stages/user_logout.md
       - User Write Stage: flow/stages/user_write.md
   - Sources: sources.md
-  - Providers: providers.md
+  - Providers:
+    - OAuth2: providers/oauth2.md
+    - SAML: providers/saml.md
   - Expressions:
     - Overview: expressions/index.md
     - Reference: