User Management

TokTagger supports many users at the same time. An identity provider keeps the accounts and the passwords. TokTagger does not store passwords. TokTagger keeps the project roles and the annotations.

Identity Providers

TokTagger signs users in with OpenID Connect. Set auth.provider to choose the identity provider.

Both modes use the same sign-in flow. In canaille mode, TokTagger also creates and starts the identity provider.

User Roles

TokTagger has two layers of roles.

Global roles (account-level)

The identity provider sets the global role. A user is an admin when the user belongs to the group toktagger-admins. TokTagger reads the groups at sign-in, and again during the session. To change a global role, change the group membership in the identity provider.

A browser session reads the account from the identity provider again after auth.session_refresh_seconds (default 5 minutes). Thus a change to the groups, or a disabled account, takes effect in the browser within this time. If the identity provider ends its session, the user must sign in again. A session with no requests ends after auth.session_idle_timeout_seconds (default 24 hours). A deactivation in TokTagger takes effect immediately.

TokTagger does not read the role from an access token that a script sends. Only a sign-in in the browser changes the role.

Project roles (per-project membership)

The project configuration decides which samples a project contains. Only a project admin can add or delete samples. In the UI, the Add Samples, Clear Samples and per-row Delete buttons are grey for annotators and viewers.

A global admin has full access to all projects, whatever the project role is.

First Start With Canaille

On the first start, TokTagger creates the local identity provider. It prints the address and the password of the first administrator:

First start: a local identity provider (Canaille) was created.
  Address:  http://localhost:8003
  Username: admin
  Password: <random password>
Change the password at http://localhost:8003/profile/admin

TokTagger prints the password one time only. Write it down. Then open the address and change the password.

TokTagger keeps the Canaille data in the canaille folder of the server cache_dir. A restart uses the same data and prints no password.

Add a user

1. Sign in to Canaille at http://localhost:8003 as admin.
2. Open Users and click Add a user.
3. Enter the user name, the email address and a password.
4. To make the user a TokTagger admin, add the user to the group toktagger-admins. Refer to Update a user.

The user can now sign in to TokTagger.

Update a user

1. Sign in to Canaille at http://localhost:8003 as admin.
2. Open Users and click the user name.
3. Open the Account settings tab.
4. Change the user details. To make the user a TokTagger admin, add toktagger-admins in the Groups field. To remove the admin role, remove toktagger-admins from the field.
5. Click Edit to save the changes.

Use Keycloak or Another Identity Provider

To use an identity provider, add an [auth] section to the toktagger.toml file in your working directory. Set provider to oidc and give TokTagger the details of your provider:

# toktagger.toml
[auth]
provider = "oidc"
issuer_url = "https://auth.example.com/realms/toktagger"
client_id = "toktagger"
client_secret = "<client secret>"
public_url = "https://toktagger.example.com"
roles_claim = "groups"
admin_group = "toktagger-admins"

In the identity provider, create a confidential client for TokTagger. Use this checklist:

1. Flow: Enable the authorization code flow with PKCE (method S256) and refresh tokens. Disable the other flows. TokTagger uses the refresh token to read the groups of the user again during the session.
2. Redirect URI: Set <public_url>/auth/callback.
3. Sign-out redirect URI: Set <public_url>/ui/login.
4. Groups claim: Add a mapper that puts the groups of the user in the userinfo. Set roles_claim to the name of the claim. For a nested claim, use a dotted path, for example realm_access.roles. During a session, TokTagger reads the groups from the userinfo only.
5. Admin group: Create the group named in admin_group. Add the TokTagger admins to it. TokTagger removes a leading / from group names.
6. Audience: Add the client ID to the audience of access tokens. TokTagger needs this to accept access tokens from scripts.

Signing In

Open http://<host>:<port>/ui/login (or the root URL). Click Sign in. The identity provider shows its sign-in page. After you sign in, you return to TokTagger.

TokTagger creates its own record for a user at the first sign-in. The record contains the user name, the email address and the display name. TokTagger takes the user name from the identity provider claim preferred_username. If that name is already in use, TokTagger adds a number. TokTagger never changes a user name after the first sign-in, because annotations store it.

To sign out, use Sign out in TokTagger. TokTagger then opens the sign-out page of the identity provider.

Admin Panel

The admin panel is on the Admin Panel button on the Projects page. Only admin users see it.

Viewing Users

The panel lists all users that signed in at least one time. It shows the user name, the email address, the global role and the active status.

TokTagger shows the global role as read-only. Change it in the identity provider.

Deactivating and Reactivating a User

Click Deactivate (or Activate) next to the user. A deactivated user cannot use TokTagger. The identity provider cannot override this setting. TokTagger keeps the annotations of the user. You cannot deactivate your own account. You cannot deactivate the last active admin.

If a deactivated user tries to sign in, TokTagger shows an error. When the user clicks Sign In again, the identity provider asks for credentials again. The user can then sign in with a different account.

Deleting a User

Click Delete next to the user and confirm. This deletes the TokTagger record and the project memberships of the user. It does not delete the account in the identity provider. The user can sign in again and TokTagger creates a new record. You cannot delete the last active admin.

Profile Page

Each signed-in user can open Profile from the Projects page. The page shows the user name, the email address and the display name.

Project Membership

Access to a project is set for each project. On the project Samples page, an admin clicks Members to add or remove users.

Only members and admins can view samples and submit annotations. If you open the URL of a project you are not a member of, the page shows 403 - Forbidden. Ask a project admin to add you.

Scripts

A script can call the API with a Bearer token. Send the token in the header Authorization: Bearer <token>. TokTagger then uses the same rules as for a browser user.

Personal API tokens

Use a personal API token for scripts. To create a token:

1. Sign in to TokTagger.
2. Open Profile from the Projects page.
3. In API tokens, enter a name for the token and select when the token expires.
4. Click Create token.
5. Copy the token. TokTagger shows the token one time only.

A token has the same access as your account. Keep it secret. If a person gets your token, revoke it immediately: click the Revoke button next to the token.

A token stops working when:

• it expires
• you revoke it
• an admin deactivates or deletes your account.

You cannot use an API token to create or revoke API tokens. Use a browser session for this.

The longest lifetime of a token is auth.api_token_max_lifetime_days (default 365 days).

The scripts scripts/setup.py and scripts/create_mock_data.py read the token from the environment variable TOKTAGGER_API_TOKEN:

export TOKTAGGER_API_TOKEN=<API token>
python scripts/setup.py

Identity provider access tokens

A script can also send an access token of the identity provider. TokTagger checks the signature, the issuer, the expiry and the audience of the token. The identity provider must let the script get an access token. The default TokTagger clients in Canaille and in the Keycloak development realm do not do this.

Multi-User Deployment

For team use, run the API with more than one worker. Then the server can serve many requests at the same time:

# Command-line (installed package)
toktagger --workers 4 --host 0.0.0.0 --port 8002

Use the toktagger command or python -m toktagger.api.run for more than one worker. These commands start the identity provider and the shared services one time, before the workers start. Do not start toktagger.api.asgi:app directly with auth.provider = "canaille".

Set AUTH_SECRET_KEY so that all workers sign sessions with the same key.

A single Uvicorn worker (the default) is enough for personal use. It handles one request at a time, so many annotators will see delays.