Authentication in the dashboard¶

Single-user and multi-user modes¶

The dashboard supports 2 modes: single-user and multi-user.

The single-user mode is available by default when the gujian-backend instance is first started. There is only one user admin@gujian.local in the system with the super administrator role without a password (default user).

Using this mode prohibits the use of tokens and the following functionality:

Working with authentication, as well as the necessary checks of the LDAP server;
Creating a new user (POST /api/users);
Updating the data of the user (PATCH /api/users/:id);
Activating a user by ID (PUT /api/users/:id/activate);
Activating a user by email (PUT /api/users/:email/activate);
Activating users (PUT /api/users/activate);
Deleting a user (DELETE /api/users/:id).

The multi-user mode is activated after setting the default password for the user (PUT /api/users/current/password). This mode unlocks all the functionality described above.

The multi-user mode implies the work of multiple users, as well as the work of these users in various organizations. Each organization has its own tenant, which has access to a certain visibility of resources (its own targets, scans, etc.).

Each user has a specific role:

Role	Identifier	Description
Unknown	`unknown`	The user is not activated.
User	`user`	Basic functionality. The user can create scans and targets.
Administrator	`admin`	Advanced functionality. The administrator has access to the all available functionality in his tenant.
Super administrator	`superAdmin`	Maximum available functionality. It can only belong to the users from the default tenant (for example, the default user).

Authentication methods¶

The dashboard supports 2 authentication methods: standard and LDAP.

The standard authentication involves the use of email and password for verification.
LDAP authentication involves the use of login and password of the LDAP server user for verification.

If the standard authentication is available by default, then all other methods are configured separately. Each of the authentication methods can be enabled, disabled, or deleted (if not the only active one), however, the standard authentication cannot be created or deleted (it is the only one).

HTTP API for managing authentication methods:

Request	User role	Description
`POST /api/auth`	`superAdmin`	Creating an authentication method.
`PATCH /api/auth/:id`	`superAdmin`	Updating an authentication method.
`GET /api/auth`	`superAdmin`	Getting available authentication methods.
`GET /api/auth/:id`	`superAdmin`	Getting a specific authentication method by ID.
`DELETE /api/auth/:id`	`superAdmin`	Deleting a specific authentication method by ID.
`GET /api/auth/available`	Authentication is not required	Getting information about the available authentication methods with a minimum set of data

An example of deactivating the authentication method PATCH /api/auth/:id:

{
  "disabled": true
}

Activation is performed in a similar way, but with the "disabled": false parameter.

The deactivation of any authentication method will lead to the termination of all its users' sessions and denial of access.

If standard authentication is disabled, and access, for example, to the only configured LDAP authentication is lost for some reason, then access to standard authentication cannot be restored by regular means.

Creating LDAP authentication¶

An example of creating LDAP authentication POST /api/auth:

{
  "type": "LDAP",
  "parameters": {
    "label": "ldap",
    "host": "example.test",
    "port": 636,
    "baseDN": "ou=users,dc=example,dc=test",
    "uid": "uid",
    "defaultAttributes": true,
    "tls": true,
    "roles": {
      "superAdmin": "objectClass=inetOrgPerson"
    }
  }
}

The parameters field from the example above is responsible for the LDAP authentication parameters. The full list:

Parameter	Type	Is required	Default	Description
`label`	`string`	yes	not specified	The label of the LDAP authentication setting.
`host`	`string`	yes	not specified	The host of the LDAP server.
`port`	`uint32`	yes	not specified	The LDAP server port.
`baseDN`	`string`	yes	not specified	The search database. A directory object that specifies where users are stored.
`uid`	`string`	yes	not specified	An attribute that indicates the unique user ID used when logging in. For example, if `"uid": "uid"` like in the case above: `uid=exampleUserLogin`. If `"uid": "sAMAccountName"` then: `sAMAccountName=exampleUserLogin`.
`login`	`string`	no	not specified	The default user login on behalf of which users will be authenticated (search, matching, etc.). If there is no user, authentication is considered anonymous by default.
`password`	`string`	no	not specified	The default user password. It is used in conjunction with the `login` parameter.
`emptyPassword`	`string`	no	not specified	The parameter that regulates the use of an empty password for the default user. It is used in conjunction with the `login` parameter when the `password` parameter is empty.
`filter`	`string`	no	not specified	User filter. For example: `&(uid=exampleUserLogin)(exampleUserFilter)`, where the value of `exampleUserFilter` is the filter.
`attributes`	`object`	no	see below	Additional attributes of the user.
`defaultAttributes`	`boolean`	no	`false`	A parameter that regulates the use of additional attributes by default.
`tls`	`boolean`	no	`false`	A parameter that regulates the use of the TLS protocol.
`roles`	`object`	no	not specified	A parameter that maps local user roles to LDAP server user roles. From the example above it is clear that the LDAP server user must belong to the `inetOrgPerson` class to obtain the local `superAdmin` role (compiled in the form of filters).

`attributes` object¶

Field	Type	Default value (when `defaultAttributes`: true)	Description
`email`	`[]string`	`mail, email, userPrincipalName`	The attribute that will be used to receive the user's email.
`name`	`[]string`	`cn, displayName`	The attribute that will be used to receive the user's name.
`firstName`	`[]string`	`givenName`	The attribute that will be used to receive the user's name (when the `name` attribute is absent).
`lastName`	`[]string`	`sn`	The attribute that will be used to receive the user's lastname (when the `firstName` attribute is present and the `name` attribute is not). If both the `firstName` and `lastName` attributes are specified and received, the final user name will be a combination of them.

It is possible to assign LDAP authentication to a specific tenant. After authentication, the user will be assigned to the corresponding tenant.

Example:

{
    "type": "LDAP",
    "tenantName": "ldapTenant",
    "parameters": {
       ...
    }
}

The tenantName parameter specifies which tenant the LDAP authentication is assigned to.

Importaint

A user with the superAdmin role can only exist in the default tenant. If a role filter is configured for this user, but the authentication method is not assigned to the tenant by default, then user's authentication will not be performed.

Authentication in the dashboard¶

Single-user and multi-user modes¶

Authentication methods¶

Creating LDAP authentication¶

attributes object¶

`attributes` object¶