Widget Single-Sign-On

Weavy offers a Single-Sign-On (SSO) authentication flow to seamlessly allow users in a host system to be signed in into Weavy. This is accomplished by creating and passing a JSON Web Token (JWT) to the widget script. JWT is an open standard (RFC 7519) for securely transmitting information between parties as a JSON object. To learn more about JSON Web Tokens, go to the jwt.io web site.

Authentication Flow

The authentication flow for SSO with JWT is descibed below:

  1. For every request in the host system where the Weavy Widget is loaded and initialized, you need to create a JWT.
  2. Supply the JWT to the Weavy Widget SSO plugin as an option.
  3. When the Widget is loaded and initialized, the JWT is sent along with other options to Weavy.
  4. If a JWT is found in the Weavy Widget option on the server side of Weavy, the JWT is decoded using the weavy.jwt-secret specified in app settings.
  5. Using the claims set in the JWT, Weavy looks for an existing local user account.
  6. If a user is found, the user is authenticated.
  7. If a user is not found, a local user and a login is created, the user is then authenticated.
  8. The user in the host system is now signed in into Weavy.

Configure a Shared Secret

The first thing to do is to decide for a secret string that should be used when signing the tokens. The secret is used by the host system when creating the JWT but also by Weavy when decoding the JWT. Hence, the secret that you decide to use must also be set in the weavy.jwt-secret application setting.

<appSettings>
    <add key="weavy.jwt-secret" value="mysecretstring123!#" />
</appSettings>

Create a JSON Web Token

For every request in the host system where the Weavy Widget is loaded and initialized, you should create a JWT and pass it as an option to the Weavy Widget SSO plugin. Depending on what technologies your host system is based on, there are numerous of libraries to help you with the creation of a JWT. Take a look at the jwt.io page for more information.

In this example, we are using JWT.Net library to create the token.

public static class JWTHelper{

    private const string Secret = "mysecretstring123!#";

    public static string GenerateJWT(User user) {
    
        return new JWT.Builder.JwtBuilder()
                .WithAlgorithm(new HMACSHA256Algorithm())
                .WithSecret(Secret)
                .AddClaim("exp", DateTimeOffset.UtcNow.AddSeconds(10).ToUnixTimeSeconds())
                .AddClaim("iss", "unique_host_system_id")
                .AddClaim("sub", user.Id) 
                .AddClaim("email", user.Email)
                .AddClaim("username", user.Username)
                .Build();    
    }
}
The token should never by created with client side scripting since that will risk exposing the secret string.

In the example above, a couple of required claims are added to the token. These are:

Claim Description
exp How long the token will be valid. This should be set to a very short time for security reasons.
iss This is a unique id for the host system. This id is used in Weavy to check if the user has an existing User Login for that system.
sub This is the user identifier. Should be a identifier for the user in the host system, usually the user id.
email The user's email in the host system. This is used to check if a user exists in Weavy or if the user login should be created.
username The user's username in the host system. This is used to check if a user exists in Weavy or if the user login should be created.

Initialize the Widget Script

When the token is created you should supply it to the Weavy Widget script. The token is added to the script with the sso plugin.

var weavy_options = {  
   plugins: {
      sso: {
         jwt: @JWTHelper.GenerateJWT()
      }
   }
};
var widget = new WeavyWidget(weavy_options);

Done!

Try out the Single Sign On feature by navigating to the page in your host system where the Weavy Widget is used. If the JSON Web Token is setup correctly, the user should automatically be signed in into Weavy.