SysAdmin


Accessible only in tagtog OnPremises, the SysAdmin page lets you manage tasks at the system level.

How to access

Go to your root domain set for tagtog (either an IP or a custom domain) and access the /-sysadmin relative path; for example: https://tagtog.example.org/-sysadmin. You will be prompted with a basic authentication panel, to enter the fields:

Username: use the subscription license name

Password: use the subscription license key

User Management

User panel

The user panel displays a list of the users registered in the instance. You can:

Create new accounts: you can add a user account directly in the sysadmin panel.

Edit accounts: edit the users’ accounts main information. Edit a user from the system by clicking on the edit button

Remove accounts: remove users that for example do not use anymore the application. Remove a user from the system by clicking on the remove button .

Fields in the table

Count: index of the user.

Username

Email

Creation date: date the user account was created.

Can create projects: flag to indicate whether the user can create projects or not.

Has password: accounts with Basic authentication have password. Single sign-on accounts don’t have password within the application.

User panel

Create a new user

To create a new user using the sysadmin user panel, click on + Add new user. A form will show up with the following fields:

Account type: Basic authentication (regular tagtog account with username and password) or Single sign-on (documentation).
In the user panel, accounts with Basic authentication with the flag Has Password

Username: the username of the new user.

Email: the email of the new user.

Password: the password of the new user. The user can later change the password. This field is only required for accounts with Basic authentication.

Can create projects: a flag to indicate whether the new user can create tagtog projects or not. Users who cannot create projects, can only work in projects they are invited to.

Create a new user by registration link

You can generate a registration link to share with others or to use oneself. Anyone who has this link and access to the system, can create a regular user account signing up in the application.

Revoke auth tokens

Remove all existing token-based logins and registration links. If you think your system’s security might have been compromised, you can revoke all auth tokens thus invalidating old token-based logins and registration invitations.

Roles and permissions

In the admin panel you can find a permission matrix where you can check & modify the permissions of existing roles or to create custom roles. After, these roles can be assigned to users at project level.

All the permissions are explained here: Multi-user annotation - permissions

By default there are three roles in the system: admin, supercurator and reader. The permissions for these default roles cannot be modified. Admin role cannot be removed (the creator of a project, the owner, will always have this role assigned). The roles supercurator and reader can be removed. If you want to modify their permissions, you should remove the role, and create a new role with the same name.

To create a new role simply click on Add new role. To change a permission, you should click on the corresponding checkbox. If you hover on the permission name or on a role name, a description of the permission or the role will show up.

For each role, you can perform three actions:

Edit its name/description

Remove it. If you remove a role, you should indicate which is the role that will be assigned to all the users once their original role is removed.

Change its permissions

Permission matrix. In this example, in addition to the default roles, there is a new role myNewRole

Single Sign-On (SSO)

OpenID Connect (OIDC)


🤠 The tagtog OpenID Connect feature is in beta. For most use cases, everything should work just fine. However, rough edges might exist. We much appreciate your feedback.


You can link to tagtog your OpenID Connect Provider (e.g. KeyCloak, Auth0, Okta, AWS Cognito, Microsoft, Salesforce.com, etc.). With this, your users will be able to login into tagtog seamlessly (with the authentication mechanism they already know).

OIDC: Setup

First of all, you must define a client for tagtog in your OIDC Provider:

  • Define the client id (e.g. “tagtog”).
  • Of course, set the root URL of the tagtog client as the domain of your tagtog OnPremises instance.
  • Enable the “Authorization Code Flow” (also called “standard”, or “server” authentication).
  • The access type should be “Confidential”.
  • The authentication method should be based on client id & secret.

Then, there are 3 variables that tagtog must know about your OIDC Provider and the client you just defined, namely:

  • wellknownDiscoveryUrl: this is the standard .well-known/openid-configuration endpoint URL of your OIDC Provider.
  • clientId: this is the name you give in your Provider to the tagtog client (e.g., again, “tagtog”).
  • clientSecret: the secret (password) associated to the tagtog client in your OIDC Provider.

Moreover, and optionally, you can also configure the following tagtog-specific variables:

  • usersThatCanBeCreatedAutomaticallyIfNotFoundInTagtog (OPTIONAL; default=""): tagtog OIDC integration lets you choose whether users of your authentication system should have a tagtog account created automatically or not (that is, when they login on your Provider but do not have a tagtog account yet). The possible values are:
    • "" (none): no users will be created automatically unless they exist already on tagtog.
    • "*" (all): all users of your OIDC system will be created automatically on tagtog if they log in and they have no associated tagtog account yet.
    • comma-separated list of emails (e.g. “John@example.org,Maria@example.org,Peter@example.org”): users’ emails in your OIDC system of users that can be created automatically on tagtog if they log in and they have no associated tagtog account yet.
  • usernameClaim (OPTIONAL; default=preferred_username or, if not existing, sub): the claim (attribute) of your OIDC provider that you want to use for your users’ usernames. In practice, this parameter is only relevant if you let your users’ accounts to be created automatically if they don’t exist on tagtog yet (see: usersThatCanBeCreatedAutomaticallyIfNotFoundInTagtog). If the accounts already exist on tagtog, they are primarily identified by their email address (see below). In this case, the usernames can take any value (with some restrictions). Note that you, as the sysadmin, can create the users first manually, associating them the email address registered in your OIDC Provider, and giving them an arbitrary username. Also note that, if you rely on this variable, you can use any custom attribute/claim of your OIDC Provider.
  • redirectTagtogRootUri (OPTIONAL; default=originating host): by default when users successfully login on your OIDC Provider, they are redirected back to the originating host, which should be your tagtog OnPremises domain. Therefore, in most cases you should not set this variable. However, sometimes, due to redirections and having “docker-in-between” the originating host might not be read properly, or otherwise be wrongly set to the localhost. For these cases, use this variable. It should be the domain of your tagtog OnPremises domain; e.g. https://tagtog.example.org (please do not write a trailing forward slash, “/”).

Finally, the way you pass these variables to tagtog is by using java dynamic properties. Example:

export TAGTOG_JAVA_OPTS="${TAGTOG_JAVA_OPTS} \
-Dapplication.auth.openid.default.wellknownDiscoveryUrl=https://mySSO:8443/auth/realms/master/.well-known/openid-configuration \
-Dapplication.auth.openid.default.clientId=tagtog \
-Dapplication.auth.openid.default.clientSecret=64934247-ea33-4ec7-8e86-197ea9be3417 \
-Dapplication.auth.openid.default.usersThatCanBeCreatedAutomaticallyIfNotFoundInTagtog= \
-Dapplication.auth.openid.default.usernameClaim=myCustomAttribute \
"

# Then, restart tagtog as normally
./tagtog_on_premises restart latest $TAGTOG_HOME

OIDC: Important to know

These are relevant aspects of the tagtog OIDC integration:

  • Scopes & claims: tagtog’s OIDC client (Relying Party) asks your OIDC Provider for only these 3 standard scopes: openid, email, profile.

    In particular, we only ask for the scope profile to get access to the preferred_username claim, might it be present. From the scope email, we only access the claims email and email_verified (if present).

    Only mandatory are the claims sub (from the scope openid) and email.

  • Users primary identification is by their email. This means that the mapping between your users in your OIDC Provider and the tagtog registered users is based on the email claim/attribute. In pratical terms, this means that a user on tagtog with, for instance, username “A” and email “A@example.org”, and a user on your Provider with different username “A-alt” but same email “A@example.org”, represent the very same user.

  • Valid usernames follow the regex: [a-zA-Z][a-zA-Z0-9-]{0,39}. Trying to add users with an invalid username, either manually or “automatically” (upon user OIDC login), will throw an error. If you have good reasons to make the username regex more flexible, please let us know.

OIDC: How to use

Once you set up your OIDC integration, the tagtog login page (/-login), shows an extra option to “Log in with OpenID”. Moreover, when a non-logged-yet user goes to a tagtog page that requires authentication, the user will be always redirected to the same login page:

Screenshot: Login with OpenID Connect

tagtog login box when OpenID Connect is enabled on your tagtog OnPremises instance.

When the user clicks on the OpenID link, the user is redirected to the authentication mechanism of your OIDC Provider. Upon a successful authentication, the user’s data is sent back to tagtog. Two things can then happen:

  • a) If the user’s email is already associated to a tagtog user, the login is completed, and the user is redirected to the default page after login.

  • b) If the user’s email is not yet associated to any tagtog user, but the usersThatCanBeCreatedAutomaticallyIfNotFoundInTagtog setting allows it, tagtog creates automatically a user account on tagtog. Then the login is completed, the user can access tagtog, and is redirected to the default page. Note that such users created automatically have no associated password, and therefore (unless you later set a password), cannot login on tagtog with basic authentication.

Upon a successful login, a new tagtog user session begins, and everything else is the same and transparent to the user.

Of course, if the login is not successful on the end of the OIDC Provider, or if the user does not exist yet on tagtog and cannot be created automatically, tagtog will not allow any access and will throw a “Forbidden” error.

Finally, if the user logs out on tagtog, the user session ends with respect to tagtog. Note that tagtog does not log out the user with respect to the external OIDC Provider.

Auth Tokens

An alternative SSO system on tagtog is based on authentication tokens. These can only be generated by the sysadmin (via API). The sysadmin can then have injected, in a simple reverse proxy server or just simple URL redirections, the corresponding authentication token that distinctively grant one user to login. The sysadmin can keep an internal map of reusable tokens or generate them on-demand programmatically any time a login access is required (see below the useOnce API parameter). All auth tokens can easily be deleted at any time (see above: Revoke all auth tokens).

API to request auth token

Endpoint /-sysadmin/request-auth-token
Method POST
Output String, the auth token

Input Parameters

Defined as JSON parameters:

Name Default Example Description
toUsername (String) - yourUsername The user's username you grant the authentication to.
expirationHours (Int) -1 (meaning, no expiration) 24 The expiration in hours for the token to still be usable. Leave undefined or otherwise write a negative number to not have any expiration (meaning the token is valid until removed).
useOnce (Boolean) false true Besides the expiration, with this parameter you can decide whether the token can be used only once (true) or not (false, i.e., multiple times until the token is removed or expires).

Coding examples

curl -u LICENSE_NAME:LICENSE_KEY -X POST -H "Content-Type: application/json" 'https://www.tagtog.net/-sysadmin/request-auth-token' \
-d '{"toUsername": "yourUsername", "useOnce": true, "expirationHours": 48}'
# Example output: bbfd-33878148-6062-4934-a507-af4962753c8f
http --auth LICENSE_NAME:LICENSE_KEY POST 'https://www.tagtog.net/-sysadmin/request-auth-token' toUsername=yourUsername useOnce:=false
# Example output: 6f0d-90c2386a-8a33-4ad1-bd19-d4d35ad06f96

How to use an auth token

Once you have an auth token, use it in a simple GET request to login with the associated-granted user. To the request also add a redirectTo (url-encoded) parameter to indicate where to redirect to. You must add these parameters to the / (root endpoint) of your tagtog’s installation domain.

Example: https://www.tagtog.net/?redirectTo=https%3A%2F%2Fwww.tagtog.net%2F-datasets&token=bbfd-33878148-6062-4934-a507-af4962753c8f

Tighter authorization

Sometimes you want to have a tighter control about what the users and visitors of your system are allowed to do. You can configure the following authorization controls using java dynamic properties. Specifically, you must set the environment variable TAGTOG_JAVA_OPTS with the desired configuration values as described for each point below.

Disallow visitors to create accounts

Sometimes you do not want to allow visitors to your tagtog installation creating accounts themselves. In such a case, the sysadmin is responsible to create the accounts for all the users.

Set application.canVisitorsCreateAccounts to false (the default is true). Example:

export TAGTOG_JAVA_OPTS="${TAGTOG_JAVA_OPTS} -Dapplication.canVisitorsCreateAccounts=false";
./tagtog_on_premises restart latest $TAGTOG_HOME

Disallow users to change their account details

In such a case, the sysadmin is responsible to edit the account details of the users.

Set application.canUsersEditTheirAccounts to false (the default is true). Example:

export TAGTOG_JAVA_OPTS="${TAGTOG_JAVA_OPTS} -Dapplication.canUsersEditTheirAccounts=false";
./tagtog_on_premises restart latest $TAGTOG_HOME

Disallow users to recover their passwords using the “Forgot Password?” email

In such a case, the sysadmin is entirely responsible for the users’ passwords.

Set application.canUsersRequestForgotPassword to false (the default is true). Example:

export TAGTOG_JAVA_OPTS="${TAGTOG_JAVA_OPTS} -Dapplication.canUsersRequestForgotPassword=false";
./tagtog_on_premises restart latest $TAGTOG_HOME