People and sign-in

Add people and give permissions

1. Open Settings › People, and click New account.

2. Enter a username and a password, and click Create account.

3. On the page of the person, under Repositories, click Give access.

4. Tick the repositories, and tick Download or Publish.

5. Click Give access to 1 repository.

The other repository permissions are Delete files, Edit settings, Manage access and Manage CI pipelines.

To add people from the command line, see user add.

Server permissions

Under Server permissions on the page of the person, choose a role:

• Member: no server permissions. The person uses only the repositories they are given.
• Administrator: every server permission.
• Custom: one switch per permission, each with what it opens.

Then click Save, and Save permissions. You can give only the permissions that you hold.

Two-step verification

These people need a second step:

• To sign in: anyone with a permission other than Download and Publish.
• To approve a computer or make a publish token: everyone.

1. Open Settings › Sign-in and security.

2. Click Add on the Authenticator app row or the Passkey row.

3. Under Recovery codes, click Generate codes. Keep the codes in a safe place.

A single sign-on account has no second step. It approves a computer with a new single sign-on.

Single sign-on

People can sign in with an OpenID Connect provider, such as Keycloak, Entra ID, Okta or Google. Anyone at the provider can sign in. The first sign-in makes an account with no permissions.

1. At your provider, add an app with the return address https://repo.example.com/api/auth/oidc/callback.

2. Open Settings › Sign-in options.

3. Under Connect your provider, enter the Provider address, the App ID and the App secret.

4. Click Test connection.

5. Click Save.

Then you give permissions on the People page, as for any account.

Permissions from the provider

To let the provider decide the server permissions:

1. At your provider, make a group for each role, such as repo-admins. Put the groups in a field of the ID token, such as groups.

2. On Sign-in options, enter that field in Group field.

3. Under Permissions by group, click Add a group.

4. Enter the group, choose its role, and click Add group.

5. Click Save.

Each sign-in then sets the server permissions of the person from their groups. The People page shows them read-only. Repository permissions stay on the server.

Make managers use single sign-on

Set Password sign-in to Only people who publish; people who manage use single sign-on.

People who only download and publish keep their password. Sign in once with single sign-on first.

If something goes wrong

Someone lost every second factor

On the machine of the server:

docker exec -it telesphorepo /telesphorepo-server user reset-2fa alice

The person sets up a new factor at the next sign-in.

Someone forgot the password

On the page of the person, click Reset password. Or on the machine of the server:

docker exec -it telesphorepo /telesphorepo-server user passwd alice

Passkeys stopped working

A passkey belongs to the host of the server address. When the host changes, each person adds a new passkey. Set the Public base URL on Settings › General before people add passkeys.

Single sign-on broke, and managers cannot sign in

Start the server with -e TR_SIGNIN_PASSWORD_LOGIN=all. Every local account can then sign in with a password again.

Keycloak: the groups field

Add a Group Membership mapper to the client scope. Turn off Full group path, so the value is repo-admins and not /repo-admins. Enter groups in Group field.

For Keycloak realm roles, enter realm_access.roles instead.