Tenants, users and access

A tenant is one organisation's workspace. It owns its projects, scans, findings, users, scan policy and settings, and nothing in it is visible from another tenant. One installation can hold many tenants.

#Who is who


Operator (platform administrator)	The account created at install time. Creates tenants and can enter any tenant to help. Not subject to a tenant's sign-in rules. This is the `SUPERADMIN_EMAIL` account
Tenant owner	The first account of a tenant. Full control of that tenant
Member	A user with a role in a tenant

A person can belong to several tenants, with a different role in each. They choose between them with the workspace switcher in the top bar.

#Roles

Roles are ordered. Each includes everything below it.

Role	Can
`viewer`	See projects, scans and findings; download reports
`analyst`	Start scans, register projects, triage findings. This is the role a pipeline needs
`admin`	Manage users, integrations, scan policy and settings
`owner`	Everything, including deleting the tenant's data

#Creating a tenant for a new workplace

The operator does this in the console under Settings, Customers (New customer), or through the API:

curl -X POST https://api.dpndncy.example.com/api/admin/tenants \
  -H "Authorization: Bearer <operator API token>" \
  -H "Content-Type: application/json" \
  -d '{
        "name": "Acme Corp",
        "ownerEmail": "[email protected]",
        "ownerName": "Alex Owner",
        "ownerPassword": "a-long-initial-password"
      }'

name is required. slug (the short identifier) is derived from it if you do not give one.
With ownerEmail the first owner is created and joined to the tenant. If an account with that email already exists it is reused.
With SMTP configured and no ownerPassword, the owner receives an invitation to set their own password. Without SMTP no email is sent, so give an ownerPassword and pass it on yourself; the owner should change it at first sign-in.

The owner then signs in and does the rest from the console.

#What the owner does first

Turn on two-step verification for their own account (Settings).
Enforce it for everyone (Settings, Sign-in security). Members who have not enrolled can sign in only to enrol. Single sign-on users and operators are exempt.
Invite or create users (Settings, Users) and give each a role.
Choose the scan policy (Scan policies).
Create a service account for pipelines: a user with the analyst role, used only by CI. Sign in as that user, create an API token (Settings, API Tokens), and store it as a CI secret. Tokens act with the role of the user at the moment they are used, and are revoked by deleting the token or the user.
Optionally restrict which projects a member sees (Project access).

#Single sign-on

OpenID Connect and SAML 2.0 are built in. Configure them on the server (Configuration reference). Single sign-on proves who someone is; it does not place them in a tenant. Add each person to the tenant first (Settings, Users, using the email address their identity provider returns) and give them a role. A person who signs in with no membership is refused with "Tenant membership is required". Operator accounts always sign in locally. Local accounts and two-step verification keep working alongside single sign-on.

#API tokens

Settings, API Tokens. A token belongs to one user and one tenant, and carries that user's role. The default life is 365 days; choose a shorter one for personal use or 0 for none. A user can hold 10. The server can cap the life with API_TOKEN_MAX_DAYS, which cuts longer requests and "never expires" down to the cap so tokens must be replaced on a schedule. Tokens survive server restarts and the automatic rotation of the signing key. They stop working if the token is deleted, expires, the user is removed from the tenant, or the signing key is rotated with the emergency option (Running dpndncY).

#Removing a tenant

The operator can delete a tenant and everything in it (Settings, Customers). The operator's own tenant cannot be deleted while they are working in it, and the slug must be typed to confirm. There is no undo; take a backup first (Running dpndncY).

← Previous

The console

Project access