External authentication

External authentication is perfect when you have an existing user database in another system. You can then configure Weavy to use your already existing user database for authentication.

Prerequisites

In order to configure external authentication the following things are required:

  • You have an existing user database.
  • You can implement and add an API endpoint (https) that Weavy can call for authentication.

Configuration

The following settings are required for Weavy to use external authentication.

Web server

The Weavy website in IIS must be configured with the following settings:

Anonymous Authentication = Enabled
Forms Authentication = Disabled
Windows Authentication = Disabled

Web.config

The web.config file should have the following configuration:

<appSettings>
    <add key="weavy.custom-authentication-endpoint" value="https://..." />
</appSettings>
...
<system.web>
    <authentication mode="None" />
</system.web>

The weavy.custom-authentication-endpoint should point to an url that implements the external authentication specification.

Authentication Endpoint

When a custom authentication endpoint is supplied, Weavy will try to call the endpoint when a user tries to sign in into Weavy.

POST https://www.myapp.com/authenticate HTTP/1.1
Content-Length: 45
Content-type: application/json; charset=utf-8

{username: "username", password: "password" }
Example authentication request that Weavy will send to your authentication endpoint

It’s up to the developer of the api endpoint to authorize and authenticate the user and send back a status 200 OK with a valid JSON Web Token.

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

<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();    
    }
}

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

Not Authorized

If the user was not found or authorized in the external application, the api should return corresponding status codes, i.e. 404 Not Found or 401 Unauthorized.