Authentication in Dexie Cloud
Zero config, registrationless, passwordless
Easy to replace with your own authentication
Long-lived sessions & cryptographically protected tokens
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:
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
- User goes to your webapp the very first time (as authentication lasts for months by default)
- User is prompted for email address.
- User get an email containing a one-time password such as
- User enters the OTP.
- 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.
Every Dexie Cloud Database has a token endpoint that gives out tokens for client applications. A successful OTP authentication will result in a new token returned. Dexie Cloud Tokens are software keys used to sign requests towards the server. We use the best security standards available in modern clients to store the tokens encrypted and never ever send the token over the wire but instead sign requests using the tokens. This makes them resistable to replay attacks and gives the tokens as a better protection than typical JWT tokens can offer.
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 be securely stored on the client.
Since Dexie Cloud tokens are long-lived, we need to handle them with a better security mechanism than just plain JWT tokens. We could have been using refresh tokens, but since there is a better way when utilizing IndexedDB and webcrypto in 90% of modern web clients, we have decided to go for signed requests to gain a deeper protection of the transport security.
The secure flow of retrieving and storing tokens
- Request token from Dexie Cloud (using OTP auth OR via server-to-server requests (custom auth))
- Client generates a new local non-exportable encryption key and stores it in IndexedDB.
- Token is encrypted using the new local key and stored as a secure cookie (to take advantage of the security in browser’s cookie storage). Now, in order to decipher the token you need both access to the IDB key and the secure cookie.
The secure flow of authenticating requests
- Client decrypts the token temporary into memory.
- Client signs the request and the current timestamp with it
- Client sends the sync request with the current timestamp used to the server with the signature in it.
- Server verifies that signature is valid
- Server verifies that the client’s timestamp is within a grace period (+/- one minute) If timestamp verification fails, server sends a challenge containing its own current time and expects the client to adjust its time with the diff between server and client and re-send the request.
- Sync request is processed successfully.
Why is this better than server-generated JWT tokens?
Normal server-generated JWT tokens need to be passed to the server in every API request from the clients to the server. Even though all API calls are TLS encrypted, you will not control the the clients that can access your server unlike server-server communication where you can really rely on the TSL channel as you control the API client. An attacher could copy a JWT from a user if having access to the client somehow, if not using a trojan hourse or malware, it could be copied just using the chrome debugger. If that happens, it is of great value that the JWT is as short-lived as possible.
The tokens that Dexie Cloud use are dependent on a CryptoKey in IndexedDB and not sent over the wire. The CryptoKey is further protected by a secret stored in a secure cookie - to utilize the browser-native protection of secure cookies on hard disk. By signing API requests instead of attaching a plain JWT an attacker will not be able to steal the token from network requests using neither chrome debugger, fake installed CA certs or similar methods.
2 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 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.
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.