Authenticating users with JWT tokens

User JWT tokens

Using JWT tokens provides the greater flexibility than "Sign in with Google" and other third party providers, but also requires some development work on the part of the event host. With tokens, the event host can support seamless authentication integration with their own platform where attendees are already logged in.

Public and private keys

In order to generate tokens, you will first need to generate a public/private RSA key pair. For example, if you are on Linux or Mac:

ssh-keygen -b 2048 -m PEM -t rsa -f frameable.key -q -N ""
openssl rsa -in frameable.key -pubout -outform PEM -out frameable.key.pub

In the Settings section of your Frameable event, paste your public key from frameable.key.pub. When you open the resulting file, it should look something like this:

-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAreHYPYvIDfoisOxcelL6
DBVnQOJjlMThKtq/Hmfo3kHXV2WY8RQ8AZ/7GiIN4Z4HnaPb3IdKOFoSpdun2pho
sPyFJMZNM37o3jPd5M9kiEADTiuIk35fk9dgQ+j2aBVp4cJSm8IJ4QxQ78vzM+h1
O0N3YzXY5GJLcH6JKl8+aveKCqn6rRHvZKMCXP+OFrQ3BLp06RFCREHdRH9H/n0r
jLGmos/YBgdnzzAD0u1lNWR1IPF1lxs/fzUvHOmN+BuDYPttloIIZ65nPMklG5w/
QxdupHKb6JVMQo6Jd2iqE+4lPhZZz+sIcScvgFhubqX0bqkHHQVxe6+9XApuPtD3
TQIDAQAB
-----END PUBLIC KEY-----

Generating the token

With keys generated, you can now create and sign user tokens. For example, with Node.js:

const jwt = require('jsonwebtoken');
const fs = require('fs');
 
const privateKey = fs.readFileSync('./frameable.key');
 
const token = jwt.sign({
  displayName: 'Larry David',
  email: 'larry@seinfeld.com',
  userProfile: [
    ['organization', 'Seinfield'],
    ['title', 'Producer'],
    ['interests', 'comedy']
  ]
});

Now, add this token in the event url:

https://<your-domain>.frameable.com/events/<your-event>?token=eyJhbGciOiJS...

Token properties

name type required? description
displayName string required Name to appear on the user's video stream
email string optional Email address shared only via opt-in contact sharing
avatarUrl string optional Publicly accessable avatar image url. If not provided, a default image will be generated from the initials from the given displayName
userProfile array optional List of keys and values entirely specified by you
roles array optional List of elevated roles which the user may perform, per below

User profile fields

User profiles are optional. If a user profile is sent, it should be in the form of a list of keys and values. The keys should match field names configured for your event in the event's admin interface. Only the fields configured for the event will be shown on user streams, even if extra fields are sent through the token. The first specifield field will show atop user streams by default, and the rest will be discoverable upon hovering over the stream.

A few field names are special. Specifically, if twitter, linkedin field names are configured, then those links will appear in the "You met with..." page after an attendee has left the event.

Roles

Roles may be specified in order to give a user extra privieleges.

name description
host A host can do all there is to be done
presenter A presenter may arrive early, and may put themselves on stage
transcriber A transcriber may provide live closed captioning
interpreter An interpreter may provide live audio foreign language translation

In order to use the transcription and interpretation capabilities, those features must be enabled for your organization, and for your event.

Best practices

It is most likely in your interest to generate tokens with a near-term (~300 seconds) expiration time. Ideally, when a user clicks a link on your platform intending to visit Frameable, it is at that point when you should dynamically generate the token, and send the user along to Frameable (e.g., via 302 redirect).

It is also possible to generate long-lived tokens, but remember that anyone who follows that link will be logged in as that user on frameable.com. So it is best to avoid directly including token links in formats like emails or chat channels; better to generate on the fly as needed.