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:

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',
  avatarUrl: 'https://cdn/avartar/person.png',
  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.