# People and sign-in

> Add people, give permissions, set up two-step verification and single sign-on.

Source: https://docs.telesphorepo.com/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](/commands-and-settings/#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:

```sh
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:

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