From 296e1f49621319e1df66e950b33b68e3afbd91fd Mon Sep 17 00:00:00 2001 From: Jens Langhammer Date: Wed, 9 Sep 2020 19:14:12 +0200 Subject: [PATCH] docs: improve documentation for providers --- docs/property-mappings/index.md | 4 ++++ docs/providers.md | 24 ------------------------ docs/providers/oauth2.md | 31 +++++++++++++++++++++++++++++++ docs/providers/saml.md | 12 ++++++++++++ mkdocs.yml | 4 +++- 5 files changed, 50 insertions(+), 25 deletions(-) delete mode 100644 docs/providers.md create mode 100644 docs/providers/oauth2.md create mode 100644 docs/providers/saml.md diff --git a/docs/property-mappings/index.md b/docs/property-mappings/index.md index 7b7edd0d4..7cde9571e 100644 --- a/docs/property-mappings/index.md +++ b/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. diff --git a/docs/providers.md b/docs/providers.md deleted file mode 100644 index b48312612..000000000 --- a/docs/providers.md +++ /dev/null @@ -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". diff --git a/docs/providers/oauth2.md b/docs/providers/oauth2.md new file mode 100644 index 000000000..336077666 --- /dev/null +++ b/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//jwks/` +OpenID Configuration | `/application/o//.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. diff --git a/docs/providers/saml.md b/docs/providers/saml.md new file mode 100644 index 000000000..f2952f38f --- /dev/null +++ b/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//sso/binding/redirect/` +SSO (POST binding) | `/application/saml//sso/binding/post/` +IdP-initiated login | `/application/saml//sso/binding/init/` +Metadata Download | `/application/saml//metadata/` diff --git a/mkdocs.yml b/mkdocs.yml index aaf593948..c50ee983f 100644 --- a/mkdocs.yml +++ b/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: