diff --git a/docs/openid.md b/docs/openid.md
index f685fd551a..49180eec52 100644
--- a/docs/openid.md
+++ b/docs/openid.md
@@ -79,7 +79,7 @@ oidc_providers:
display_name_template: "{{ user.name }}"
```
-### [Dex][dex-idp]
+### Dex
[Dex][dex-idp] is a simple, open-source, certified OpenID Connect Provider.
Although it is designed to help building a full-blown provider with an
@@ -117,7 +117,7 @@ oidc_providers:
localpart_template: "{{ user.name }}"
display_name_template: "{{ user.name|capitalize }}"
```
-### [Keycloak][keycloak-idp]
+### Keycloak
[Keycloak][keycloak-idp] is an opensource IdP maintained by Red Hat.
@@ -166,7 +166,9 @@ oidc_providers:
localpart_template: "{{ user.preferred_username }}"
display_name_template: "{{ user.name }}"
```
-### [Auth0][auth0]
+### Auth0
+
+[Auth0][auth0] is a hosted SaaS IdP solution.
1. Create a regular web application for Synapse
2. Set the Allowed Callback URLs to `[synapse public baseurl]/_synapse/client/oidc/callback`
@@ -209,7 +211,7 @@ oidc_providers:
### GitHub
-GitHub is a bit special as it is not an OpenID Connect compliant provider, but
+[GitHub][github-idp] is a bit special as it is not an OpenID Connect compliant provider, but
just a regular OAuth2 provider.
The [`/user` API endpoint](https://developer.github.com/v3/users/#get-the-authenticated-user)
@@ -242,11 +244,13 @@ oidc_providers:
display_name_template: "{{ user.name }}"
```
-### [Google][google-idp]
+### Google
+
+[Google][google-idp] is an OpenID certified authentication and authorisation provider.
1. Set up a project in the Google API Console (see
https://developers.google.com/identity/protocols/oauth2/openid-connect#appsetup).
-2. add an "OAuth Client ID" for a Web Application under "Credentials".
+2. Add an "OAuth Client ID" for a Web Application under "Credentials".
3. Copy the Client ID and Client Secret, and add the following to your synapse config:
```yaml
oidc_providers:
@@ -446,3 +450,51 @@ The synapse config will look like this:
config:
email_template: "{{ user.email }}"
```
+
+## Django OAuth Toolkit
+
+[django-oauth-toolkit](https://github.com/jazzband/django-oauth-toolkit) is a
+Django application providing out of the box all the endpoints, data and logic
+needed to add OAuth2 capabilities to your Django projects. It supports
+[OpenID Connect too](https://django-oauth-toolkit.readthedocs.io/en/latest/oidc.html).
+
+Configuration on Django's side:
+
+1. Add an application: https://example.com/admin/oauth2_provider/application/add/ and choose parameters like this:
+* `Redirect uris`: https://synapse.example.com/_synapse/client/oidc/callback
+* `Client type`: `Confidential`
+* `Authorization grant type`: `Authorization code`
+* `Algorithm`: `HMAC with SHA-2 256`
+2. You can [customize the claims](https://django-oauth-toolkit.readthedocs.io/en/latest/oidc.html#customizing-the-oidc-responses) Django gives to synapse (optional):
+ <details>
+ <summary>Code sample</summary>
+
+ ```python
+ class CustomOAuth2Validator(OAuth2Validator):
+
+ def get_additional_claims(self, request):
+ return {
+ "sub": request.user.email,
+ "email": request.user.email,
+ "first_name": request.user.first_name,
+ "last_name": request.user.last_name,
+ }
+ ```
+ </details>
+Your synapse config is then:
+
+```yaml
+oidc_providers:
+ - idp_id: django_example
+ idp_name: "Django Example"
+ issuer: "https://example.com/o/"
+ client_id: "your-client-id" # CHANGE ME
+ client_secret: "your-client-secret" # CHANGE ME
+ scopes: ["openid"]
+ user_profile_method: "userinfo_endpoint" # needed because oauth-toolkit does not include user information in the authorization response
+ user_mapping_provider:
+ config:
+ localpart_template: "{{ user.email.split('@')[0] }}"
+ display_name_template: "{{ user.first_name }} {{ user.last_name }}"
+ email_template: "{{ user.email }}"
+```
|
