From 7e3c8213c1a399966068db2c4a68cfbedc78068a Mon Sep 17 00:00:00 2001
From: Hugo <hugo@hashbang.fr>
Date: Thu, 17 Jun 2021 11:21:07 +0200
Subject: [PATCH 1/2] doc: add django-oauth-toolkit to oidc doc

Signed-off-by: Hugo Delval <hugo.delval@gmail.com>
---
 changelog.d/10192.doc |  1 +
 docs/openid.md        | 48 +++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 49 insertions(+)
 create mode 100644 changelog.d/10192.doc

diff --git a/changelog.d/10192.doc b/changelog.d/10192.doc
new file mode 100644
index 000000000000..3dd00537e8d9
--- /dev/null
+++ b/changelog.d/10192.doc
@@ -0,0 +1 @@
+Add documentation on how to connect Django with synapse using oidc and django-oauth-toolkit. Contributed by @HugoDelval.
diff --git a/docs/openid.md b/docs/openid.md
index cfaafc50150f..b0fd4b82be6f 100644
--- a/docs/openid.md
+++ b/docs/openid.md
@@ -446,3 +446,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>
+3. 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 }}"
+```

From f9df94f8cb8d3ec4ef4776c78fab188b57b699f6 Mon Sep 17 00:00:00 2001
From: Hugo <hugo@hashbang.fr>
Date: Mon, 23 Aug 2021 10:22:51 +0200
Subject: [PATCH 2/2] doc: tweak oidc doc presentation

Signed-off-by: Hugo Delval <hugo.delval@gmail.com>

Thanks to comments by @richvdh: https://github.com/matrix-org/synapse/pull/10192
---
 docs/openid.md | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)

diff --git a/docs/openid.md b/docs/openid.md
index b0fd4b82be6f..0c13ba5824c3 100644
--- a/docs/openid.md
+++ b/docs/openid.md
@@ -454,13 +454,13 @@ 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:**
+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`
+* `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>
@@ -476,8 +476,8 @@ needed to add OAuth2 capabilities to your Django projects. It supports
                 "last_name": request.user.last_name,
             }
     ```
-  </details>
-3. Your synapse config is then:
+   </details>
+Your synapse config is then:
 
 ```yaml
 oidc_providers: