Single Sign-On
Weavy offers a Single Sign-On (SSO) authentication flow to seamlessly allow users in your application to be signed in into Weavy. This is done by creating and passing a JSON Web Token (JWT) from your backend system to the Weavy client SDK.
JWT is an open standard (RFC 7519) for securely transmitting information between parties as a JSON object. This information can be verified and trusted because it is digitally signed. JWTs can be signed using a secret with the HMAC algorithm or a public/private key pair using RSA or ECDSA. 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.
Read more about JSON Web Tokens at jwt.io
Authentication Flow
The authentication flow for SSO with JWT is descibed below:
- For every request in the host system where Weavy is loaded and initialized, you need to create a JWT.
- Supply the JWT to the Weavy client as an option, either as a string with the actual token or as a function that returns a javascript promise that eventually resolves with the token.
- When the Weavy instance is loaded and initialized, the JWT is sent along with other options to the Weavy server.
- The JWT is validated using the Weavy client that has a client id that matches the
client_id
claim, or if that claim is not present theiss
claim. - Using the claims found in the JWT, Weavy looks for an existing user account.
- If a user is found, the user is authenticated.
- If a user is not found, a user account and a login is created, the user is then authenticated.
- The user in the host system is now signed in into Weavy.
Creating the JSON Web Token
The token you create must include a claim that references a client in Weavy. This is done by adding the client_id
claim and
setting its value to be identical to the client id of the Weavy client you are using.
Lastly, the token must be signed with the same secret that is defined on the Weavy client.
For every page in your application where Weavy is loaded and initialized, you should create a JWT with user claims and pass it to the Weavy client SDK. Depending on what technologies your application is based on, there are numerous libraries to help you with the creation of a JWT. Take a look at the Libraries section on jwt.io for some examples.
If, for instance, your application is based on .NET you could use JWT.net to create a token as in the example below:
var token = new JwtBuilder()
.WithAlgorithm(new HMACSHA256Algorithm())
.WithSecret("mysecretstring")
.AddClaim("exp", DateTimeOffset.UtcNow.AddSeconds(60).ToUnixTimeSeconds())
.AddClaim("iss", "unique_application_id")
.AddClaim("sub", "unique_user_id")
.AddClaim("client_id", "my-clientid")
.Encode();
The token you create must have the following required claims:
Claim | Description |
---|---|
exp |
The expiration time of the token. This should preferably be set to a short time for security reasons. |
iss |
A name or id that uniquely identifies your application. If you don't add the client_id claim this claim needs to be the client id of the Weavy client you are using to create the token. |
sub |
A unique identifier for the user in your application, usually the user id. |
Additionally you can also include the following optional claims:
Claim | Description |
---|---|
client_id |
The client id of the Weavy client that you are using to create the token. |
dir |
Id or name of user directory where the user belongs. |
email |
Email address. If present, this is used to check if a user already exists in Weavy or if a new user account should be created. |
name |
Display name of user (Firstname Lastname). |
picture |
User profile picture. Either an url to an image that is publicly accessible or a base64 encoded data URL (data:image/...) |
username |
Preferred username. |
Passing the JWT to Weavy
Tokens can be passed to Weavy either as a string or as a function that returns a javascript promise containing the JWT. An advantage with specifying a function is that it will make it possible to refresh the JWT by calling the function throughout the life cycle of the page.
As a function
Define your own function that should be called when a new token is needed. The only prerequisite is that the function returns a javascript Promise that is awaitable. Your function could for example perform calls to your backend to retrieve a fresh token, then resolve or reject the promise once the result is processed.
Enter the name of your function as the jwt
option in the client.
<script>
var getToken = function () {
return new Promise(function (resolve, reject) {
// could for instance call backend to generate a valid token
var token = getTokenFromSomewhere();
if (token) {
resolve(token);
} else {
reject("Failed to retrieve token");
}
});
}
var weavy = new Weavy({
jwt: getToken
});
</script>
As a string
You can pass the JWT to Weavy by specifying the jwt
option in the client.
<script>
var weavy = new Weavy({
jwt: "server_generated_token"
});
</script>
Validate token
In order for Weavy to validate your JWT, the client_id
(or iss
) claim must be identical to the client id of an existing, active Weavy client. Also, the token must be signed with the same secret that the Weavy client is using.
Shared secret
If your JWT was signed using a secret (with the HMAC algorithm), you should configure the Weavy client with that same secret string as ClientSecret.
Public/private key pair
If your JWT was signed with a private key using RSA or ECDSA, you should configure the Weavy client with the corresponding public key as ClientSecret
-----BEGIN PUBLIC KEY-----
and -----END PUBLIC KEY-----
on separate lines.
Test
Try out the Single Sign-On feature by navigating to a page in your host system where Weavy is used. If the JSON Web Token is created and passed in correctly, your users should automatically be signed in to Weavy.