Configuring authentication

One of the first things you should do when embedding Weavy in your application is enabling Single Sign-On (SSO) to provide users with a seamless login experience. 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

Creating the JSON Web Token

When a user has been authenticated in your application, you should create a JWT with user claims and pass it to the Weavy client SDK.

The token you create must include a claim that references a client in Weavy. This is done by setting the iss or client_id claim to the client id of the Weavy client you are using. Lastly, the token must be signed with the secret that is defined on the Weavy client.

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())    
    .AddClaim("exp", DateTimeOffset.UtcNow.AddSeconds(60).ToUnixTimeSeconds())    
    .AddClaim("iss", "unique_application_id")
    .AddClaim("sub", "unique_user_id")
    .AddClaim("client_id", "my_client_id")
    .WithSecret("my_client_secret")
    .Encode();

The example above would require that there is a Weavy client with client id = my_client_id and client secret = my_client_secret

The token you create must have the following required claims:

Additionally you can also include the following optional claims:

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>

Signing out a user

Signing in another user will automatically sign out the previous user, but it is also possible to explicitly sign out the current user by calling the signOut() function.

<script>
    var weavy = new Weavy();
    weavy.authentication.signOut();
</script>