Vanilla offers several client libraries that you can use on your site if you are implementing jsConnect. If you have a site that is programmed in a different language or you can't use one of Vanilla's libraries, this article will tell you how to implement the protocol.
What You'll Need
In order to implement jsConnect, you'll need to create an authentication page on your site that gives details of the currently signed in user. The jsConnect v3 protocol uses JSON Web Tokens (JWT) to secure the SSO. We highly recommend using an existing JWT library to verify and create JWTs. Vanilla currently uses the HMAC SHA256 algorithm to sign tokens so you need to have a library that can implement that hash algorithm at a minimum.
Authentication Page Process
Your authentication page will do the following:
- Verify the jsConnect request from Vanilla.
- Generate a JWT with your response and the current user's information.
- Redirect back to Vanilla with your response.
Verify the jsConnect request from Vanilla
Vanilla sends its request in the querystring under the jwt parameter. The value of the parameter is a JWT and you need to verify it with the following process:
- Verify the JWT with your library. The secret is the one you configured in Vanilla under the jsConnect connection.
- Make sure the JWT has an
rurl claim. This claim is the URL that you need to redirect back to.
Generate a JWT with your response
Your response should have the following fields:
// header
{
"kid": "jsConnect client ID"
}
// payload
{
"v": "lang:1.0", // version information
"iss": 1586349451, // current unix timestamp
"exp": 1586350051, // expiry, no more than 10 minutes from now
"u": {}, // your user or an empty object if not signed in
"st": {}, // this is the "st" field from the request
}
The User Field
Your user information goes in the u field of your JWT's payload. It can contain the following standard fields:
{
"id": "12345", // database ID that identifies your user
"name": "username", // username of your user
"email": "user@example.com", // email address
"photoUrl": "https://example.com/avatar.jpg", // avatar
"roles": [] // array of role names or IDs
}
Only the id field is required, but usually you want to pass some or all of the other fields.
If there is no user signed into your system, just put an empty object in the user field.
The State Field
The state goes in the st field of your JWT's payload. This field comes from the request and is necessary to secure the SSO.
The Version Field
The version goes in the v field of your JWT's payload. We like to use the convention language:version for this field to give both the language the library was written in and its specific version number. Adding a version greatly helps with troubleshooting so we highly recommend you add it.
Redirect back to Vanilla with your response
Once you've verified the request and generated your response token you need to 302 redirect back to Vanilla. Your redirect URL takes the following format:
<redirect url>#jwt=<response jwt>
For the redirect URL, you need to use the rurl that came in the payload from the request. Do not hard code this URL as it may change in the future.
For the response JWT, you use the JWT that you generated in step 2 above.
Note that for the response, the JWT is transmitted in the fragment rather than the querystring. This is to provide another layer of security so that specific authentication tokens don't show up in server logs.
Reference Implementation
This article gives you instructions on how to implement jsConnect v3. If you learn better by reading code we recommend you reference our PHP implementation.