From 74007ef5eee52d565048a68f870200c84a3e5721 Mon Sep 17 00:00:00 2001 From: richvdh Date: Wed, 7 Jul 2021 09:44:14 +0000 Subject: deploy: 7c823789921ac34f1fee670be7ef7f6c8266832b --- latest/jwt.html | 344 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 344 insertions(+) create mode 100644 latest/jwt.html (limited to 'latest/jwt.html') diff --git a/latest/jwt.html b/latest/jwt.html new file mode 100644 index 0000000000..e296c25fac --- /dev/null +++ b/latest/jwt.html @@ -0,0 +1,344 @@ + + + + + + JSON Web Tokens - Synapse + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + + + + + + +
+
+ +
+ +
+ +

JWT Login Type

+

Synapse comes with a non-standard login type to support +JSON Web Tokens. In general the +documentation for +the login endpoint +is still valid (and the mechanism works similarly to the +token based login).

+

To log in using a JSON Web Token, clients should submit a /login request as +follows:

+
{
+  "type": "org.matrix.login.jwt",
+  "token": "<jwt>"
+}
+
+

Note that the login type of m.login.jwt is supported, but is deprecated. This +will be removed in a future version of Synapse.

+

The token field should include the JSON web token with the following claims:

+
    +
  • The sub (subject) claim is required and should encode the local part of the +user ID.
    • +
  • The expiration time (exp), not before time (nbf), and issued at (iat) +claims are optional, but validated if present.
    • +
  • The issuer (iss) claim is optional, but required and validated if configured.
    • +
  • The audience (aud) claim is optional, but required and validated if configured. +Providing the audience claim when not configured will cause validation to fail.
    • +
+

In the case that the token is not valid, the homeserver must respond with +403 Forbidden and an error code of M_FORBIDDEN.

+

As with other login types, there are additional fields (e.g. device_id and +initial_device_display_name) which can be included in the above request.

+

Preparing Synapse

+

The JSON Web Token integration in Synapse uses the +PyJWT library, which must be installed +as follows:

+
    +
  • +

    The relevant libraries are included in the Docker images and Debian packages +provided by matrix.org so no further action is needed.

    +
    • +
  • +

    If you installed Synapse into a virtualenv, run /path/to/env/bin/pip install synapse[pyjwt] to install the necessary dependencies.

    +
    • +
  • +

    For other installation mechanisms, see the documentation provided by the +maintainer.

    +
    • +
+

To enable the JSON web token integration, you should then add an jwt_config section +to your configuration file (or uncomment the enabled: true line in the +existing section). See sample_config.yaml for some +sample settings.

+

How to test JWT as a developer

+

Although JSON Web Tokens are typically generated from an external server, the +examples below use PyJWT directly.

+
    +
  1. +

    Configure Synapse with JWT logins, note that this example uses a pre-shared +secret and an algorithm of HS256:

    +
    jwt_config:
+    enabled: true
+    secret: "my-secret-token"
+    algorithm: "HS256"
+
    +
    2. +
  2. +

    Generate a JSON web token:

    +
    $ pyjwt --key=my-secret-token --alg=HS256 encode sub=test-user
+eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJ0ZXN0LXVzZXIifQ.Ag71GT8v01UO3w80aqRPTeuVPBIBZkYhNTJJ-_-zQIc
+
    +
    3. +
  3. +

    Query for the login types and ensure org.matrix.login.jwt is there:

    +
    curl http://localhost:8080/_matrix/client/r0/login
+
    +
    4. +
  4. +

    Login used the generated JSON web token from above:

    +
    $ curl http://localhost:8082/_matrix/client/r0/login -X POST \
+    --data '{"type":"org.matrix.login.jwt","token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJ0ZXN0LXVzZXIifQ.Ag71GT8v01UO3w80aqRPTeuVPBIBZkYhNTJJ-_-zQIc"}'
+{
+    "access_token": "<access token>",
+    "device_id": "ACBDEFGHI",
+    "home_server": "localhost:8080",
+    "user_id": "@test-user:localhost:8480"
+}
+
    +
    5. +
+

You should now be able to use the returned access token to query the client API.

+ +
+ + +
+
+ + + +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file -- cgit 1.5.1