# Security Groups

> Give each user read, write, or admin access to each resource. Covers the owner, groups, and what changed.

Source: https://docs.centinelanalytica.com/admin/security-groups

## Overview

Access in the dashboard comes from one system. Each organisation has exactly one **owner**, who
can do everything. Every other user gets access only from the **security groups** the user is in.

A security group is a name, a list of permissions, and a list of users. A permission gives one
level of access to one resource. A group can only give access. It cannot take access away.

You manage groups on the
[Security groups page](https://dash.centinelanalytica.com/organisation/security-groups), which is
in the sidebar under **Organisation**. You put users into groups on the
[Team & Security page](https://dash.centinelanalytica.com/organisation/team).

If every user needs full access, the default groups are sufficient. You do not need the rest of
this page.

## Who has access

| Who                | Access                                                       |
| ------------------ | ------------------------------------------------------------ |
| Owner              | Everything in the organisation. No group is necessary.       |
| Any other user     | The sum of the permissions of the groups the user is in.     |
| A user in no group | No resource. The user can sign in and open the account page. |

When two groups give different levels on the same resource, the user gets the higher level.

Centinel support staff who work in an internal view do not use group permissions. That path is
outside your organisation and nothing on this page changes it.

## Vocabulary

* **Owner**: the one user who holds every permission. See [The owner](#the-owner).
* **Resource**: an area of the dashboard. See [Resources and levels](#resources-and-levels).
* **Level**: `read`, `write`, or `admin`. A higher level includes the lower levels.
* **Permission**: one resource with one level, for example `write` on `policy_rules`.

## The owner

* An organisation has exactly one owner. The first user who joins a new organisation becomes the
  owner.
* The owner holds every permission and does not have to be in a group. The team list shows an
  **Owner** badge.
* Nobody can remove the owner or change the owner's access. Because of this, an organisation
  cannot lock itself out.
* The owner leaves the position only when the ownership moves to a different user.

### Transfer the ownership

Only the owner can transfer the ownership. If the owner is not available, contact Centinel
support.

1. Open [Team & Security](https://dash.centinelanalytica.com/organisation/team).

2. Open the **⋯** menu of the user who becomes the owner and select **Transfer ownership**.

3. Confirm. The previous owner stays in the organisation, in the **Admins** group.

The transfer is recorded on the **Activity** page.

## Default groups

Each organisation has two default groups. Centinel creates them with the organisation.

* **Admins**: `admin` on every resource.
* **Members**: `read` on analytics, crawlers, and policy rules. Members does not give `read` on
  `members`, so a user who is only in Members does not see the team list.

You can edit the two default groups. You cannot delete them. A user can be in the two groups at
the same time. That user has the access of Admins.

## Resources and levels

| Resource          | What it covers                                                                         | Levels in use            |
| ----------------- | -------------------------------------------------------------------------------------- | ------------------------ |
| `analytics`       | Traffic and threat data.                                                               | `read`                   |
| `crawlers`        | The crawler lists and the robots.txt monitor.                                          | `read`, `write`          |
| `policy_rules`    | The [Policy rules](https://docs.centinelanalytica.com/admin/policy.md) editor.         | `read`, `write`, `admin` |
| `members`         | The team list, invitations, and removal of users.                                      | `read`, `admin`          |
| `settings`        | Organisation settings, the integration keys, deletion.                                 | `read`, `write`, `admin` |
| `security_groups` | The security groups and who is in them.                                                | `admin`                  |
| `passports`       | The [passports](https://docs.centinelanalytica.com/admin/passports.md) and their keys. | `admin`                  |
| `api_keys`        | The API keys that read analytics.                                                      | `admin`                  |

The group editor shows only the levels that the dashboard checks. For each resource you select
**None**, or one of the levels in the table.

> **\`security\_groups: admin\` is the highest permission:** A user with `admin` on `security_groups` can edit any group, and can thus give themselves every
> other permission. Only the ownership stays out of reach. Give this permission only to users you
> trust with the full organisation.

## Custom groups

Select **New group** on the Security groups page. Give the group a name and a description, and
select a template. You can change each permission after you create the group.

| Template              | Permissions                                                      |
| --------------------- | ---------------------------------------------------------------- |
| **Blank**             | None.                                                            |
| **Read-only auditor** | `read` on every resource that has a `read` level.                |
| **Member manager**    | `admin` on `members`.                                            |
| **Policy editor**     | `write` on `policy_rules`, `read` on `analytics` and `crawlers`. |

A group applies to the full organisation.

## Put a user in a group

**When you invite the user.** On Team & Security, select **Invite member**. **Default group**
sets the group the new user joins: Members or Admins. **Additional groups** lists your custom
groups. The user joins the selected groups when the user accepts the invitation.

An invitation link expires 30 days after you create it. Create a new link after that.

**For a user who is in the team.** Open the **⋯** menu of the user and select **Manage groups**.
Select the groups and save.

To give a user full access, put the user in the Admins group. To stop that access, remove the
user from the group.

| Action                                                                      | Permissions necessary                         |
| --------------------------------------------------------------------------- | --------------------------------------------- |
| Invite a user into the Members group, or remove a user who is not in Admins | `members: admin`                              |
| Put a user in Admins or in a custom group, or remove the user from it       | `members: admin` and `security_groups: admin` |
| Remove a user who is in Admins from the organisation                        | `members: admin` and `security_groups: admin` |

The second permission stops a user who only manages the team from giving access that the user
does not hold.

## See the access of a user

Open the **⋯** menu of a user on Team & Security and select **View access**. The view shows the
level the user has on each resource and the group that gives it. Use it for an access review.

**View access** is available to users with `security_groups: admin`.

Each change to a group, a permission, or a group membership is recorded with its state before
and after, and shown on the **Activity** page.

## Where the permissions are checked

The server checks the permission for each action. The sidebar shows only the pages that the
user's permissions cover. The dashboard hides a control that the user cannot use. The server
refuses the action if someone sends it anyway.

| Action                                                                                               | Permission necessary                    |
| ---------------------------------------------------------------------------------------------------- | --------------------------------------- |
| View traffic and threat data                                                                         | `analytics: read`                       |
| Edit a crawler list or the robots.txt monitor                                                        | `crawlers: write`                       |
| Edit policy rules                                                                                    | `policy_rules: write`                   |
| View the settings history or the Activity page                                                       | `settings: read`                        |
| Save the challenge page or the block page                                                            | `settings: write`                       |
| Create or revoke an API key                                                                          | `api_keys: admin` and `analytics: read` |
| Create an API key that can write                                                                     | Those two and `policy_rules: admin`     |
| Issue or revoke a [passport](https://docs.centinelanalytica.com/admin/passports.md), or read its key | `passports: admin`                      |
| Rename the organisation, see or regenerate the integration keys, restore earlier settings            | `settings: admin`                       |
| View the team list                                                                                   | `members: read`                         |
| Invite or remove users                                                                               | `members: admin`                        |
| Open the Security groups page, create or edit a group                                                | `security_groups: admin`                |

## Examples

### Auditor who sees everything and changes nothing

Invite the user with **Default group** set to Members. Then put the user in a group made from
the **Read-only auditor** template. The user can then also read the team list, the settings, the
settings history, and the Activity page. The user cannot change anything.

### Policy editor who does not see traffic data

Make a custom group:

```text
Resource      Level
policy_rules  write
crawlers      read
```

Put the user in this group only. Remove the user from Members, because Members gives `read` on
`analytics`.

### Team manager

Make a group from the **Member manager** template. The user can invite users into Members and
remove them. The user cannot put another user in Admins.

## What changed

Before, the dashboard had two systems: a role for each user (`owner`, `admin`, `member`) and the
security groups. Now it has one.

|                                 | Before                                    | Now                                                   |
| ------------------------------- | ----------------------------------------- | ----------------------------------------------------- |
| Source of access                | A role and the security groups            | The security groups. The owner is the only exception. |
| Roles                           | `owner`, `admin`, `member`                | Owner, and everybody else                             |
| Owners in an organisation       | None, one, or more                        | Exactly one                                           |
| Full access                     | The `admin` role                          | The Admins group                                      |
| Group effects                   | `allow` and `deny`                        | `allow` only                                          |
| Limit a user                    | Add a `deny` permission                   | Remove the user from the group that gives the access  |
| Role selection on an invitation | Sets the role                             | Sets the default group                                |
| A user in no group              | Gets the access of the role               | Gets no access                                        |
| Admins and Members              | A user is in one of the two               | A user can be in the two                              |
| Change of the owner             | Not controlled                            | Ownership transfer only, recorded                     |
| Passports and API keys          | Included in `settings` and `policy_rules` | Each has its own resource                             |

The **Restricted (read-only override)** template is removed, because it used `deny`.

## Common mistakes

* **A user with no group.** That user sees nothing. Put the user in Members or in a custom group.
* **A user in Admins and in a smaller group.** The smaller group limits nothing, because the user
  gets the higher level. Remove the user from Admins.
* **`security_groups: admin` in a group for users without full access.** See the warning in
  [Resources and levels](#resources-and-levels).

## Related

* [Policy rules](https://docs.centinelanalytica.com/admin/policy.md): The rule engine that decides which requests to allow, block, or rate-limit.
* [Dashboard](https://docs.centinelanalytica.com/install/dashboard.md): API keys, and where to find the security groups page.