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.authentication-endpoint" value="https://www.example.com/authenticate" />
</appSettings>
...
<system.web>
  <authentication mode="None" />
</system.web>

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

Your authentication enpoint must use the https:// protocol, otherwise you will receive a configuration error.

Authentication Endpoint

With an authentication endpoint configured, Weavy will POST the username and password to the endpoint when a user submits the sign in form.

POST https://www.example.com/authenticate HTTP/1.1
Content-Length: 35
Content-type: application/x-www-form-urlencoded

username=username&password=password

Example authentication request that Weavy will send to your authentication endpoint

Your api endpoint should authenticate the user and send back a status 200 OK with a valid JWT. The JWT should have the same claims as required when using SSO with the client SDK. 

HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8
Content-Length: 171

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJXZWF2eSIsInN1YiI6MSwiZXhwIjoxNTkwNTcyOTAwLCJlbWFpbCI6Im5hbWVAZXhhbXBsZS5jb20ifQ.ugkvnb6i9u_tZf1FxJ-ULO8XA2M9WmhZDwMS-XkWHJ0

Example reponse from authentication endpoint.

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

Single Sign-On

It's recommended to combine external authentication with SSO in the client SDK. This provides a way for users to seamlessly get signed in into Weavy as long as they are signed in to your application.