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