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 SSO plugin.

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 SSO plugin 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.

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

public static class JWTHelper{

    private const string SHARED_SECRET = "mysecretstring123!#";

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

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

Claim Description
iss This is a unique id for the host system. This id is used in Weavy to check if the user has an existing 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.
exp How long the token will be valid. For security reasons this should be set to a short time.

Initialize Weavy

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

var weavy = new Weavy({
  plugins: {
    sso: {
        jwt: "@JWTHelper.GenerateJWT()"
    }
  }
});

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.