Authentication and permissions
Antimony supports these ways to sign in, listed in auth.methods in config.yml:
| Method | Who signs in |
|---|---|
admin |
A single administrator account whose username and password come from environment variables. Good for local installations and small teams. |
openid |
Users of your organisation’s identity provider, such as Keycloak, Microsoft Entra ID or authentik. Their group memberships decide what they can access. This is the way to run Antimony for a class or a team. |
desktop |
Antimony Desktop, which starts its own server and signs in with a token it generates. You don’t set this up yourself. |
auth: methods: [admin, openid]Without auth.methods, only admin is enabled. With admin and openid together, the login screen shows the username and password form and a Continue with OpenID Connect button. With an empty list, nobody can sign in.
Admin login
Section titled “Admin login”The admin login is enabled by default. Set the credentials in the server’s environment:
SB_ADMIN_USERNAME=adminSB_ADMIN_PASSWORD=change-meThe account is always an administrator. If admin is enabled but the username or password is empty, the server doesn’t start.
To turn the admin login off, for example once OpenID Connect works:
auth: methods: [openid]OpenID Connect
Section titled “OpenID Connect”-
Register a client in your identity provider:
- Client type: confidential, with a client secret.
- Redirect URI:
https://antimony.example.com/api/users/login/success - The userinfo response must contain a
groupsclaim with the user’s group names. Antimony only requests theopenidscope, so configure the provider to include groups for that scope. In Keycloak, add a “Group Membership” mapper with Full group path turned off and Add to userinfo turned on.
-
Configure Antimony:
config.yml auth:methods: [admin, openid]openIdIssuer: https://sso.example.com/realms/antimonyopenIdClientId: antimonyopenIdRedirectHost: https://antimony.example.com/apiopenIdAdminGroups: ["antimony-admin"].env SB_OIDC_SECRET=<client secret>openIdRedirectHostis the public address of the API, including the/apiprefix of the reverse proxy. Antimony appends/users/login/successto it. -
Restart the server and sign in with Continue with OpenID Connect.
On the first login, Antimony creates a user from the sub claim and uses the e-mail address as the display name.
Permissions
Section titled “Permissions”Antimony’s permissions are built on collections: folders of topologies, usually one per course, class or team. Every topology belongs to exactly one collection, and every lab is deployed from a topology.
Administrators
Section titled “Administrators”Administrators can do everything: create and manage collections, and edit, deploy and delete any topology and lab. A user is an administrator if:
- they signed in with the admin account or Antimony Desktop, or
- one of their OpenID groups is listed in
auth.openIdAdminGroups.
Collection access comes from group names
Section titled “Collection access comes from group names”A user has access to a collection when one of their OpenID groups has exactly the same name as the collection. There’s no separate membership list in Antimony.
For example, a student in the groups hs25-cn1 and students sees the collection hs25-cn1, but not hs25-cn2.
Collection names can contain letters, digits, spaces, ., _ and -, must start with a letter or digit and can be at most 64 characters long. Only groups whose names follow these rules can give access to a collection.
To give a class its own space:
- Create a group in your identity provider, for example
hs25-cn1, and add the students. - As an administrator, create a collection with the same name in the topology editor.
- Add the topologies the students should work with.
The admin login has only the administrator account, so per-collection access needs OpenID Connect.
What members can do
Section titled “What members can do”Members of a collection can always see its topologies and labs. Two switches on each collection grant more:
| Collection setting | Members can |
|---|---|
| Anyone can deploy | Create labs from the collection’s topologies. |
| Anyone can edit | Add new topologies to the collection, and change or delete the ones they created. |
Most changes are limited to what a user created themselves:
| Action | Who |
|---|---|
| Create, rename or delete a collection | Administrators. The creator of a collection can also edit or delete it. |
| Edit or delete a topology, manage its bind files | The topology’s creator, while the collection has Anyone can edit and they’re a member of it, or an administrator |
| Edit, reschedule or delete a lab | The lab’s creator, or an administrator |
| Deploy, destroy or redeploy a lab; start, stop or restart its nodes | The lab’s creator, or an administrator |
| Open a terminal on a node | Anyone with access to the lab’s collection |
| Use, resize or close a terminal | Only the user who opened it, not even an administrator |
Sessions
Section titled “Sessions”After signing in, the browser holds two tokens:
- a refresh token (
authTokencookie, valid for 30 days), which only the server can read - an access token (
accessTokencookie, valid for 30 minutes), which the interface renews automatically
Tokens are signed with SB_JWT_SECRET. If that variable isn’t set, the server picks a random secret at every start, and everyone has to sign in again after a restart.
See Authentication flow for the details.