Drop-in UI authentication

For single-sign-on (SSO) and seamless authentication between your app and Weavy, the drop-in UI should act on behalf of your authenticated user. This is known as user-to-server communication and requires an access_token for communication with the Weavy backend.

Token factory

When initializing the drop-in UI, you must pass in a tokenFactory. The token factory should be an async function returning an access_token string for your authenticated user. A boolean refresh parameter is provided to let you now if a fresh token is needed from the backend.

async function getAccessToken(refresh) {
  // Typically implemented as an API call to your application backend
  // which returns an access_token for the authenticated user.

  // If refresh is true, you need to get a new access_token in your backend.
  
  // Returning a string access token from your backend
  return token;
}

When the drop-in UI is first initialized, your function will be called with refresh=false. The drop-in UI will use the access_token your return as long as it is valid, but if the token expires or is revoked your function will be called again with refresh=true. This allows your code to clear the invalid token from your application’s storage and request a new token from the Weavy backend.

Implementing the token factory

You will typically implement the tokenFactory function with an API call to your backend as in the following example:

const weavy = new Weavy({
 url: "{WEAVY_BACKEND_URL}",
 tokenFactory: async (refresh) => {
   // fetch access_token for the authenticated user with an api call to your application backend
   var response = await fetch('/token?refresh=' + refresh);
   var token = await response.text();
   return token;
 }
});

Your backend then requests an access_token from the Weavy backend with a server-to-server request as explained in the API authentication article. In the example below we show what a typical implementation of the /token endpoint would look like if you have a .NET/C# backend. As seen in the example, we recommend you store and reuse tokens. This avoids unnecessary roundtrips and reduces your application's attack surface.

[HttpGet("~/token")]
public async Task<IActionResult> GetToken(bool refresh = false) {
    // get uid for the authenticated user
    var uid = User.Identity.Name;

    // check local token store for access_token
    if (!refresh && _tokenStore.TryGetValue(uid, out var accessToken)) {
        // return token from store
        return Content(accessToken);
    }

    // no token in store or invalid token -> request a new access_token from the Weavy backend
    _httpClient.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", _config["weavy_api_key"]);
    var response = await _httpClient.PostAsync($"{_config["weavy_backend_url"]}/api/users/{HttpUtility.UrlEncode(uid)}/tokens", null);
    if (response.IsSuccessStatusCode) {
        // store token
        var resp = await response.Content.ReadFromJsonAsync<TokenResponse>();
        _tokenStore[uid] = resp.AccessToken;
        // return token
        return Content(resp.AccessToken);
    }

    return BadRequest();
}

Signing out a user

If needed, you can explicitly sign out a user by calling the signOut() function. The function returns a Promise, so you can wait for the process to complete before doing other things.

const weavy = new Weavy();
weavy.authentication.signOut().then(function () {
    console.log("The user was signed out from Weavy");
});

Weavy Docs