1. Reference
  2. UIKit JS
  3. Authentication

UIKit JS authentication

For single-sign-on (SSO) and seamless authentication between your app and Weavy, the JS 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 environment.

Token factory

When initializing the UIKit JS, 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 Weavy.

const getAccessToken = async (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 UIKit JS is first initialized, your function will be called with refresh=false. The UIKit JS 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 environment.

Implementing the token factory

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

Weavy.url = "{WEAVY_ENVIRONMENT_URL}"
Weavy.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;
}

You may alternatively configure Weavy using a HTML tag:

<weavy-environment url="{WEAVY_ENVIRONMENT_URL}" token-factory="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 environment 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 environment
    _httpClient.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", _config["weavy_api_key"]);
    var response = await _httpClient.PostAsync($"{_config["weavy_environment_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.

Weavy.environment.authentication.signOut().then(() => {
  console.log("The user was signed out from Weavy");
});
Weavy Docs