Menu
When tokens are signed using public/private key pairs, the signature also certifies that only the party holding the private key is the one that signed it. When should you use JSON Web Tokens? Here are some scenarios where JSON Web Tokens are useful: Authorization: This is the most common scenario for using JWT. Once the user is logged in, each. Online JSON Web Token Builder, for creating signed test JWTs, including standard and custom claims; built by Jamie Kurtz Online JWT Builder - Jamie Kurtz Toggle navigation JSON Web Token.
This plugin implements Prosody authentication provider that verifies client connection based on JWT token described in RFC7519.It allows to use any external form of authentication with lib-jitsi-meet. Once your user authenticates you need togenerate the JWT token as described in the RFC and pass it to your client app. Once it connects with valid token is considered authenticated by jitsi-meet system.
During configuration you will need to provide the application ID that identifies the client and a secret shared by both server and JWT token generator. Like described in the RFC, secret is used to compute HMAC hash value which allows to authenticate generated token. There are many existing libraries which can be used to implement token generator. More info can be found here: http://jwt.io/#libraries-io
JWT token authentication currently works only with BOSH connections.
Token structure
The following JWT claims are used in authentication token:
- 'iss' specifies application ID which identifies the client app connecting to the server. It should be negotiated with the service provider before generating the token.
- 'room' contains the name of the room for which the token has been allocated. This is NOT full MUC room address. Example assuming that we have full MUC '[email protected]' then 'conference1' should be used here. Alternately, a '*' may be provided, allowing access to all rooms within the domain.
- 'exp' token expiration timestamp as defined in the RFC
- 'sub' contains the name of the domain used when authenticating with this token. By default assuming that we have full MUC '[email protected]' then 'server.net' should be used here.
- 'aud' application identifier. This value indicates what service is consuming the token. It should be negotiated with the service provider before generating the token.
Secret is used to compute HMAC hash value and verify the token for HS256 tokens.
Alternately the token may be signed by a private key and authorized via public keyserver using RS256 tokens. In this mode, the 'kid' header of the JWT must be set to the name of the public key. The backend server must be configured to fetch and confirm keys from a pre-configured public keyserver.
Token Identifiers
![Based Based](/uploads/1/2/6/3/126321343/617200841.png)
In addition to the basic claims used in authentication, the token can also provide user display information in the 'context' field within the JWT payload:
- 'group' is a string which specifies the group the user belongs to. Intended for use in reporting/analytics
- 'user' is an object which contains display information for the current user
- 'id' is a user identifier string. Intended for use in reporting/analytics
- 'name' is the display name of the user
- 'avatar' is the URL of the avatar for the user
- 'callee' is an optional object containing display information when launching a 1-1 video call with a single other participant. It used to display an overlay to the first user, before the second user joins.
- 'id' is a user identifier string. Intended for use in reporting/analytics
- 'name' is the display name of the 'callee' user
- 'avatar' is the URL of the avatar of the 'callee'
Access token identifiers / context
To access the data in lib-jitsi-meet you have to enable the prosody module
mod_presence_identity
in your config.The data is now available as the identity in the JitsiParticipant class. You can access them by e.g. listening to the
USER_JOINED
event.NOTE: The values in the token shall always be valid values. If you define e.g. the avatar as
null
it will throw an error.Example Token
Headers (using RS256 public key validation)
Payload
Token verification
JWT token is currently checked in 2 places:
- when user connects to Prosody through BOSH. Token value is passed as 'token' query paramater of BOSH URL. User uses XMPP anonymous authentication method.
- when MUC room is being created/joined Prosody compares 'room' claim with the actual name of the room. This prevents from abusing stolen token by unathorized users to allocate new conference rooms in the system. Admin users are not required to provide valid token which is used by Jicofo for example.
Lib-jitsi-meet options
When JWT authentication is used with lib-jitsi-meet the token is passed to JitsiConference constructor:
Jitsi-meet options
In order to start jitsi-meet conference with token you need to specify the token as URL param:
At current level of integration every user that joins the conference has to provide the token and not just the one whocreates the room. It should be possible to change that by using second anonymous domain, but that hasn't been testedyet.
Installing token plugin
Token authentication can be integrated automatically using Debian package install. Once you have jitsi-meet installedjust install 'jitsi-meet-tokens' on top of it. In order to have it configured automatically at least version 779 ofjitsi-meet is required which comes with special Prosody config template.
Proceed to 'Patching Prosody' section to finish configuration.
Patching Prosody
JWT token authentication requires prosody-trunk version at least 747.
You can download latest prosody-trunk packages from here. Then install it with the following command:
Make sure that /etc/prosody/prosody.cfg.lua contains the line below at the end to include meet host config. That's because Prosody nightly may come with slightly different default config:
Also check if client to server encryption is not enforced. Otherwise token authentication won't work:
Manual plugin configuration
Modify your Prosody config with these three steps:
1. Adjust plugin_paths to contain the path pointing to jitsi meet Prosody plugins location. That's where plugins are copied on jitsi-meet-token package install. This should be included in global config section(possibly at the beginning of your host config file).
Also optionally set the global settings for key authorization. Both these options default to the '*' parameter which means accept any issuer or audience string in incoming tokens
2. Under you domain config change authentication to 'token' and provide application ID, secret and optionally token lifetime:
Alternately instead of using a shared secret you can set an asap_key_server to the base URL where valid/accepted public keys can be found by taking a sha256() of the 'kid' field in the JWT token header, and appending .pem to the end
3. Enable room name token verification plugin in your MUC component config section:
2018-06-11T14:15:42Z
Posted by Miguel Grinberg under Authentication, Security, Python, Programming.
JSON Web Tokens offer a simple and powerful way to generate tokens for APIs. These tokens carry a payload that is cryptographically signed. While the payload itself is not encrypted, the signature protects it again tampering. In their most common format, a 'secret key' is used in the generation and verification of the signature. In this article I'm going to show you a less known mechanism to generate JWTs that have signatures that can be verified without having access to the secret key.
Quick Introduction to JSON Web Tokens (JWTs)
In case you are not familiar with JWTs, let me first show you how to work with them using Python with the pyjwt package. Create a virtual environment, and install
pyjwt
in it:Now let's say you want to create a token that gives a user with id 123 access to your application. After you verify that the user has provided the correct username and password, you can generate a token for the user:
The
jwt.encode()
function has three arguments of which the most important is the first, containing the token payload. This is the information that you want stored in the token. You can use anything that can be serialized to a JSON dictionary as a payload. The payload is where you record any information that identifies the user. In the simplest case this is just the user id like in the example above, but you can include other user information such as a username, user roles, permissions, etc. Here is a more complex token:As you can see, the more data you write in the payload, the longer the token is, because all that data is physically stored in the token. By looking at the resulting JWTs you may think that the data that you put in the tokens is encrypted, but this is actually incorrect. You should never write sensitive data in a JWT, because there is no encryption. This seemingly random sequence of characters that you see in these tokens is just generated with a simple base64 encoding.
In addition to user information, the payload of a JWT can include a few fields that apply to the token itself, and have a predefined meaning. The most useful of these is the
exp
field, which defines an expiration time for the token. The following example gives the token a validity period of 5 minutes (300 seconds):Other predefined fields that can be included in the JWT are
nbf
(not before), which defines a point in time in the future at which the token becomes valid, iss
(issuer), aud
(audience) and iat
(issued at). Consult the JWT specification if you want to learn more about these.The second argument to
jwt.encode()
is the secret key. This is a string that is used in the algorithm that generates the cryptographic signature for the token. The idea is that this key must be known only to the application, because anyone who is in possession of this key can generate new tokens with valid signatures. In a Flask or Django application, you can pass the configured SECRET_KEY
for this argument.The last argument in the
jwt.encode()
call is the signing algorithm. Most applications use the HS256
algorithm, which is short for HMAC-SHA256. The signing algorithm is what protects the payload of the JWT against tampering.The value returned by
jwt.encode()
is a byte sequence with the token. You can see in all the above examples that I decoded the token into a UTF-8 string, because a string is easier to handle.Once your application generates a token it must return it to the user, and from then on, the user can authenticate by passing the token back to the server, which prevents the user from having to constantly send stronger credentials such as username and password. Using JWTs for authentication is considered more secure than usernames and passwords, because you can set an appropriate expiration time, and in that way limit the damage that can be caused in the case of a leak.
When the application receives a JWT from the user it needs to make sure that it is a legitimate token that was generated by the application itself, which requires generating a new signature for the payload and making sure it matches the signature included with the token. Using the first of the example tokens above, this is how the verification step is done with pyjwt:
The
jwt.decode()
call also takes three arguments: the JWT token, the signing key, and the accepted signature algorithms. Note how in this call a list of algorithms is provided, since the application may want to accept tokens generated with more than one signing algorithm. Note that while the algorithms
argument is currently optional in pyjwt, there are potential vulnerabilities that can occur if you don't pass the list of algorithms explicitly. If you have applications that call jwt.decode()
and don't pass this argument, I strongly advise you to add this argument.The return value of the
jwt.decode()
call is the payload that is stored in the token as a dictionary ready to be used. If this function returns, it means that the token was determined to be valid, so the information in the payload can be trusted as legitimate.Let's try to decode the token from above that had an associated expiration time. I have generated that token more than five minutes ago, so even though it is a valid token, it is now rejected because it has expired:
It is also interesting to see what happens if I take one of the tokens above, make a change to any of the characters in the string and then try to decode it:
So as you see, if
jwt.decode()
returns back a dictionary, you can be sure that the data in that dictionary is legitimate and can be trusted (at least as much as you are sure your secret key is really secret).Using Public-Key Signatures with JWTs
A disadvantage of the popular HS256 signing algorithm is that the secret key needs to be accessible both when generating and validating tokens. For a monolithic application this isn't so much of a problem, but if you have a distributed system built out of multiple services running independently of each other, you basically have to choose between two really bad options:
- You can opt to have a dedicated service for token generation and verification. Any services that receive a token from a client need to make a call into the authentication service to have the token verified. For busy systems this creates a performance bottleneck on the authentication service.
- You can configure the secret key into all the services that receive tokens from clients, so that they can verify the tokens without having to make a call to the authentication service. But having the secret key in multiple locations increases the risk of it being compromised, and once it is compromised the attacker can generate valid tokens and impersonate any user in the system.
So for these types of applications, it would be better to have the signing key safely stored in the authentication service, and only used to generate keys, while all other services can verify those tokens without actually having access to the key. And this can actually be accomplished with public-key cryptography.
Public-key cryptography is based on encryption keys that have two components: a public key and a private key. As it name imples, the public key component can be shared freely. There are two workflows that can be accomplished with public-key cryptography:
- Message encryption: If I want to send an encrypted message to someone, I can use that person's public key to encrypt it. The encrypted message can only be decrypted with the person's private key.
- Message signing: If I want to sign a message to certify that it came from me, I can generate a signature with my own private key. Anybody interested in verifying the message can use my public key to confirm that the signature is valid.
There are signing algorithms for JWTs that implement the second scenario above. Tokens are signed with the server's private key, and then they can be verified by anyone using the server's public key, which is freely available to anyone who wants to have it. For the examples that follow I'm going to use the
RS256
signing algorithm, which is short for RSA-SHA256.The pyjwt package does not directly implement the cryptographic signing functions for the more advanced public-key signing algorithms, and instead depends on the
cryptography
package to provide those. So to use public-key signatures, this package needs to be installed:The next step is to generate a public/private key set (usually called a 'key pair') for the application to use. There are a few different ways to generate RSA keys, but one that I like is to use the
ssh-keygen
tool from openssh:The
-t
option to the ssh-keygen
command defines that I'm requesting an RSA key pair, and the -b
option specifies a key size of 4096 bits, which is considered a very secure key length. When you run the command you will be prompted to provide a filename for the key pair, and for this I used jwt-key
without any path, so that the key is written to the current directory. Then you will be prompted to enter a passphrase to protect the key, which needs to be left empty.When the command completes, you are left with two files in the current directory,
jwt-key
and jwt-key.pub
. The former is the private key, which will be used to generate token signature, so you should protect this very well. In particular, you should not commit your private key to your source control, and instead should install on your server directly (you should keep a well protected backup copy of it, in case you ever need to rebuild your server). The .pub file will be used to verify tokens. Since this file has no sensitive information, you can freely add a copy of it on any project that needs to verify tokens.The process to generate tokens with this key pair is fairly similar to what I showed you earlier. Let's first make a new token:
The main difference with the previous tokens is that I'm passing the RSA private key as the secret key argument. The value of this key is the entire contents of the
jwt-key
file. The other difference is that the algorithm requested is RS256
instead of HS256
. The resulting token is longer, but otherwise similar to those I generated previously. Like the previous tokens, the payload is not encrypted, so also for these tokens you should never put sensitive information in the payload.Now that I have the token, I can show you how it can be verified using the public key. If you are trying this with me, exit your Python session and start a new one, to make sure there is no trace of the private key in the Python context. Here is how you can verify the token above:
This example looks nearly identical to the previous ones, but the important fact is that we are ensuring this token is valid without access to any sensitive information. The server's public key presents no risk, so it can be freely shared with the world. And in fact, anybody would be able to verify the tokens that your application generates with this key. To prove this point, let me share with you my public key:
You can now take this public key and validate the token that I generated, and letting you validate the tokens does not introduce any security risks for me. I'm still the only person in the world that can generate new tokens.
Conclusion
Generate Jwt Token Based On Public Key Largo
I hope those of you who were using JWTs with the popular
HS256
algorithm are now ready to introduce RS256
or any of the other public-key signature options available.Let me know if you have any questions in the comment area below!
Hello, and thank you for visiting my blog! If you enjoyed this article, please consider supporting my work on this blog on Patreon!
41 comments
- #1Ars said 2018-06-11T19:42:22Z
- #2Miguel Grinberg said 2018-06-11T22:34:20Z
- #3JM said 2018-07-06T00:47:09Z
- #4Miguel Grinberg said 2018-07-06T05:37:07Z
- #5Abdul Wahab van Reenen said 2018-07-30T10:21:35Z
- #6Miguel Grinberg said 2018-07-30T21:02:35Z
- #7SG said 2018-08-07T00:35:35Z
- #8Miguel Grinberg said 2018-08-07T21:18:10Z
- #9Mitch said 2018-08-19T22:08:06Z
- #10stm said 2018-09-07T07:24:16Z
- #11Miguel Grinberg said 2018-09-13T20:51:35Z
- #12grex_e said 2018-10-17T23:52:59Z
- #13Miguel Grinberg said 2018-10-18T14:19:33Z
- #14grex_e said 2018-10-20T23:40:32Z
- #15Vladyslav said 2018-11-01T09:58:18Z
- #16yoni said 2018-11-10T00:18:03Z
- #17Akshay said 2018-12-11T21:12:23Z
- #18Miguel Grinberg said 2018-12-12T15:21:26Z
- #19simi403 said 2018-12-19T18:24:52Z
- #20Miguel Grinberg said 2018-12-19T22:19:59Z
- #21Kim said 2019-02-24T00:28:17Z
- #22Miguel Grinberg said 2019-02-24T19:47:17Z
- #23Saqib said 2019-04-12T10:10:24Z
- #24Miguel Grinberg said 2019-04-12T18:34:58Z
- #25Andy said 2019-08-17T13:19:30Z