Authentication flow
Antimony uses two JSON Web Tokens, signed with HS256 and the secret in SB_JWT_SECRET:
| Token | Cookie | Lifetime | Contents | Readable by the interface |
|---|---|---|---|---|
| Refresh token | authToken |
30 days | user ID | No (HttpOnly) |
| Access token | accessToken |
30 minutes | user ID, admin flag | Yes |
Only the access token grants access to resources. The refresh token’s only purpose is to get a new access token. That way the long-lived token is never exposed to scripts in the page, and a leaked access token expires quickly.
How you obtain the refresh token depends on the login method. Everything after that is the same.
Admin login
Section titled “Admin login”The server compares the username and password with SB_ADMIN_USERNAME and SB_ADMIN_PASSWORD and sets both cookies.
OpenID Connect
Section titled “OpenID Connect”- The interface sends the browser to
/users/login/openid. The server remembers the page you came from and redirects to the provider. - After you sign in, the provider redirects to
/users/login/successwith an authorization code. - The server exchanges the code for a token and reads
sub,emailandgroupsfrom the provider’s userinfo endpoint. - It creates or updates the user, sets
authToken,accessTokenandauthOidc, and redirects back to the page you came from.
The groups claim decides two things: whether the user is an administrator (auth.openIdAdminGroups) and which collections they can access (groups with the same name as a collection). See permissions.
Antimony Desktop
Section titled “Antimony Desktop”Antimony Desktop starts its own server with a random SB_DESKTOP_TOKEN and signs in by sending it as { "token": "<desktop token>" }. It signs in as the admin account. The app’s window is loaded from a file, where cookies don’t work, so the server returns the access token in the response instead of setting cookies, and the app sends it in an Authorization: Bearer <access token> header. There is no refresh token: when the access token expires, the app signs in again with the desktop token.
Using and refreshing the access token
Section titled “Using and refreshing the access token”- REST requests are authenticated with the
accessTokencookie, or with anAuthorization: Bearer <access token>header. A missing cookie gives401; an invalid or expired token gives498. - Socket.IO connections pass the access token in the handshake as
auth: { token: "<access token>" }. All namespaces require it. Some also check access to a lab or a terminal, once when the client connects: a client that loses access stays connected until it reconnects. See Socket.IO API. - Logging out (
POST /users/logout) clears all three cookies. - If the user signed in with OpenID (the
authOidccookie is set) and the refresh token is no longer valid, the interface sends them through the OpenID login again.
After a server restart
Section titled “After a server restart”The server keeps signed-in users in memory. After a restart, OpenID users are recognised again on their next login. The admin account is recreated at startup.
Tokens survive a restart only if SB_JWT_SECRET is set. Without it, the server generates a new secret at every start, and every existing token becomes invalid.