---

This page describes the default authentication in Dexie Cloud, how to replace it with your own authentication and how we protect our access tokens using the latest security standards in web browsers.

If you are new to Dexie Cloud, please visit the Dexie Cloud landing page.

If you prefer to jump right in to samples, here some shortcuts:

• Example zero config setup
• Example auth integration

Introduction

Dexie Cloud is for writing offline capable applications, which means that the typical use case is long-lived authentication sessions that lasts for months or until the user actively logs out from it.

In the default setup, users will only need to authenticate the very first time they visit your app. There is no registration step for your users and they won’t need to create any password, as authentication is performed over passwordless email OTP. The authentication step will result in a securely stored, non-exportable crypto key in your indexedDB that can reathenticate future sync calls automatically without having to require further user interaction.

Zero config setup

If you just enable dexie-cloud-addon the way it is explained on the landing page you will be using the default authentication and you will not need your own server endpoint. Your app can be hosted on any site, such as a static site on GitHub Pages or similar and yet be able to authenticate users and sync data with your cloud database.

Default Authentication from a user’s perspective

1. User goes to your webapp the very first time (as authentication lasts for months by default)
2. User is prompted for email address.
3. User get an email containing a one-time password such as ABC123.
4. User enters the OTP.
5. User is in.

After this initial step, user does not need to reauthenticate for months unless he or she actively logs out from your app. The long session timeout is designed for typical offline-first applications that require this.

Encrypting your offline data

For more sensitive applications, instead of limiting the session timeout (which by design should be long for offline first apps), your app could choose to encrypt sensitive data and require a password from your user for decryption. There are two dexie compatible open source libraries that adds encryption to Dexie: dexie-encrypted and dexie-easy-encrypt. By encrypting the sensisitve parts of the offline data you protect the data much better than short session timeouts, that would require resync more often.

Replace authentication with custom authentication

The transport security will still be the same if you replace the default authentication - tokens will still be protected by CryptoKeys. The difference is only how the authentication takes place - the step that is required for Dexie Cloud to negotiate the token flow.

To replace authentication, see the following sample.

Tokens

Every Dexie Cloud Database has a token endpoint that gives out tokens for client applications. A successful authentication will result in a new token returned. Dexie Cloud also gives out refresh tokens. Refresh tokens are accompanied with an RSA keypair stored on the client. The private key is protected from being copied - stored as a CryptoKey instance in IndexedDB. Dexie cloud will only accept refresh tokens if they are accompanied with a valid signature from the client’s private key - a signature of the refresh token content concatenated with current timestamp.

No matter if you have integrated your own authentication system, or use the built-in OTP authentication, security tokens will be generated by Dexie Cloud and their refresh tokens will be securely protected on the client by the RSA keypair. This is important as the refresh token is long-lived and must not be possible to copy over to another device.

The secure flow of retrieving and storing tokens

1. Client generates a new local non-exportable RSA keypair and stores it in IndexedDB.
2. Client request token from Dexie Cloud (using OTP auth OR via server-to-server requests (custom auth)). The token request is accompanied with the public key from the local keypair.
3. Server generates a short-lived access token and a long lived refresh token.

The secure flow of refreshing tokens

1. Client requests a new access token from Dexie Cloud by sending the refresh token together with the current timestamp + signature of (refresh token + current timestamp).
2. Server verifies that signature is valid and that the timestamp is within current time +/- a margin for clock differences.
3. Server generates new access token from the claims in the refresh token.

3 ways of obtaining the tokens

Every Dexie Cloud database URL has a token endpoint that can give out tokens for a client. In order to do so, it will either require an authorization code from a successful authorization flow, OR a signed refresh-token, or accept a client_id and client_secret together with the email and name claims. The latter way is the way to use when you want to integrate an existing authentication solution to be able to authenticate users to use Dexie Cloud.

Default OTP Autentication

When the Dexie Cloud server endpoint verifies the user’s email itself, you will not need a server for your own app - it is enough that the client talks directly to the Dexie Cloud server endpoint in order to establish a secure OTP flow and get the security token from it.

Custom Authentication

When you have an existing authentication solution using a server-side framework and programming language of your own choice, and you want to integrate that solution to authenticate users for your Dexie Cloud application, you will need to write a new endpoint into your existing server-side authentication server that, using your client_id and client_secret can request token from Dexie Cloud for the user you have already authenticated.

See Example auth integration.