Skip to content

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 login1. Interface to Antimony server: POST /users/login/native. 2. Antimony server to Antimony server: check credentials. 3. Antimony server to Interface: set authToken, accessToken.InterfaceAntimony server1. POST /users/login/native2. check credentials3. set authToken, accessToken
The admin account signs in with the credentials from the server's environment.

The server compares the username and password with SB_ADMIN_USERNAME and SB_ADMIN_PASSWORD and sets both cookies.

OpenID Connect login1. Browser to Antimony server: GET /users/login/openid. 2. Antimony server to Browser: redirect to provider. 3. Browser to OpenID provider: sign in. 4. OpenID provider to Browser: redirect with code. 5. Browser to Antimony server: GET /users/login/success. 6. Antimony server to OpenID provider: exchange code. 7. Antimony server to OpenID provider: read userinfo. 8. Antimony server to Antimony server: create or update user. 9. Antimony server to Browser: set cookies, redirect back.BrowserAntimony serverOpenID provider1. GET /users/login/openid2. redirect to provider3. sign in4. redirect with code5. GET /users/login/success6. exchange code7. read userinfo8. create or update user9. set cookies, redirect back
The server handles the whole OpenID exchange. The provider's tokens never reach the browser.
  1. The interface sends the browser to /users/login/openid. The server remembers the page you came from and redirects to the provider.
  2. After you sign in, the provider redirects to /users/login/success with an authorization code.
  3. The server exchanges the code for a token and reads sub, email and groups from the provider’s userinfo endpoint.
  4. It creates or updates the user, sets authToken, accessToken and authOidc, 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.

Desktop login1. Antimony Desktop to Antimony server: POST /users/login/desktop. 2. Antimony server to Antimony server: check the desktop token. 3. Antimony server to Antimony Desktop: access token in the response.Antimony DesktopAntimony server1. POST /users/login/desktop2. check the desktop token3. access token in the response
Antimony Desktop signs in with the token it gave the server it started.

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.

Token refresh1. Interface to Antimony server: request with accessToken. 2. Antimony server to Interface: 498 Invalid Token. 3. Interface to Antimony server: GET /users/login/refresh. 4. Antimony server to Interface: new accessToken. 5. Interface to Antimony server: retry the request.InterfaceAntimony server1. request with accessToken2. 498 Invalid Token3. GET /users/login/refresh4. new accessToken5. retry the request
  • REST requests are authenticated with the accessToken cookie, or with an Authorization: Bearer <access token> header. A missing cookie gives 401; an invalid or expired token gives 498.
  • 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 authOidc cookie is set) and the refresh token is no longer valid, the interface sends them through the OpenID login again.

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.