Configuring JWT tokens

To enable authentication in Mobile apps and Microsoft Office WebDAV integration, you also need to configure server authentication. Server Authentication

The JSON Web Token (JWT)

JSON Web Token (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

Weavy uses JWT to enable External Authentication. This is a secure way to authorize a user since it certifies that only the party holding the private key (the host system) can be the one that signed the token.

The JWT 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 when creating the JWT but also on the Weavy server side when decoding the JWT. Hence, the secret that you decide to use must be specified in the Weavy web application's web.config. Or by specifying the secret as a setting in the Tenant SDK, either via the Dashboard or the API.

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

Create a JSON Web Token

When the user is authenticated in the external system (external endpoint), a JWT must be created and passed as content in the response. 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 libraries page at jwt.io for more information.

In this example, we are using a .NET library JWT.net to create the token.

public static class JWTHelper{

    const string Secret = "mysecretstring123!#";

    public static string GenerateJWT() {
        var userId = User.Identity.GetUserId();
        var userManager = HttpContext.GetOwinContext().GetUserManager<ApplicationUserManager>();
        var currentUser = userManager.FindById(userId);
    
        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", userId) 
                .AddClaim("email", currentUser.Email)
                .AddClaim("username", currentUser.UserName)
                .Build();    
    }
}

The token you create must have the following required claims:

Claim Description
exp The expiration time of the token. This should be set to a very short time for security reasons.
iss 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 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 already exists in Weavy or if the user should be created.

Additionally you can also include the following optional claims:

Claim Description
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/...
The token should never by created with client side scripting since that will risk exposing the secret string.

Setting up Single sign-on (SSO)

Once you have set up JWT tokens, you may use them for Single sign-on in the Client SDK. When the user is authenticated in your web app or web site where you have the Client SDK integrated, you simply pass a generated JWT token for that user to the client when creating a new Weavy() instance.

<script>
    var weavy = new Weavy({
        jwt: '{server_generated_jwt_token}'
    });
</script>