Skip to content

Authentication and permissions

Zoey teaching with a network diagram on a whiteboard

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.
config.yml
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.

The admin login is enabled by default. Set the credentials in the server’s environment:

.env
SB_ADMIN_USERNAME=admin
SB_ADMIN_PASSWORD=change-me

The 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:

config.yml
auth:
methods: [openid]
  1. 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 groups claim with the user’s group names. Antimony only requests the openid scope, 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.
  2. Configure Antimony:

    config.yml
    auth:
    methods: [admin, openid]
    openIdIssuer: https://sso.example.com/realms/antimony
    openIdClientId: antimony
    openIdRedirectHost: https://antimony.example.com/api
    openIdAdminGroups: ["antimony-admin"]
    .env
    SB_OIDC_SECRET=<client secret>

    openIdRedirectHost is the public address of the API, including the /api prefix of the reverse proxy. Antimony appends /users/login/success to it.

  3. 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.

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 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.

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:

  1. Create a group in your identity provider, for example hs25-cn1, and add the students.
  2. As an administrator, create a collection with the same name in the topology editor.
  3. Add the topologies the students should work with.

The admin login has only the administrator account, so per-collection access needs OpenID Connect.

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

After signing in, the browser holds two tokens:

  • a refresh token (authToken cookie, valid for 30 days), which only the server can read
  • an access token (accessToken cookie, 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.