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 Weavy.

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 Weavy is loaded and initialized, you need to create a JWT.
  2. Supply the JWT to the Weavy client as an option.
  3. When Weavy instance is loaded and initialized, the JWT is sent along with other options to the Weavy server.
  4. If a JWT is found in the options, 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>

Creating a JSON Web Token

For every request in the host system where Weavy is loaded and initialized, you should create a JWT and pass it as an option to the 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.

The token should never by created with client side scripting since that will risk exposing the secret string.
It is however ok to create the token on the client side for demo purposes.

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

public static string GenerateJWT(User user) {
    return new JWT.Builder.JwtBuilder()
            .WithAlgorithm(new HMACSHA256Algorithm())
            .WithSecret("mysecretstring123!#")
            .AddClaim("iss", "unique_host_system_id")
            .AddClaim("sub", user.Id) 
            .AddClaim("email", user.Email)
            .AddClaim("exp", DateTime.UtcNow.AddSeconds(10).ToUnixTime().ToString())
            .Build();    
}

When creating a JWT, the following claims are recognized by Weavy (claims marked with an asterisk * are required).

Claim Description
iss * A unique id for the host system, e.g. the name of your product.
sub * The user identifier. Should be a unique 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.
exp * The expiration time of the token. For security reasons this should be set to a short time, e.g. 10 seconds.
name Display name of user (Firstname Lastname).
username Preferred username.
picture User profile picture. Either an url to an image that is publicly accessible or a base64 encoded image including data:image/...
* = required

Initialize Weavy

After the token has been created you should supply it to the Weavy script with the SSO plugin.

var weavy = new Weavy({
    jwt: "{generated_jwt_token}"
});

Done!

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