Merge branch 'feature_10941_user_management_enhancements' into 'master'

# OSM platform configuration

## Role-based Access Control (RBAC)

## Explanation about OSM Role-based Access Control (RBAC)

Role-Based Access Control (RBAC) is available in OSM to bring different users and projects a controlled access to resources. Authorization is granted if a user has the necessary role to perform an action.

For achieving this, two backends are available:

The configuration can be extended to cover more users, projects and role combinations, following the next sections.

## User management

## OSM User Management

### Explanation about OSM User Management

Users can be managed through the UI, by selecting Admin --> Users on the menu to the left, or using the OSM CLI:

  REMOVE_PROJECT: deleting mappings for project/role(s)

  ADD_PROJECT_ROLE: adding mappings for project/role(s)

  REMOVE_PROJECT_ROLE: removing mappings for project/role(s)

  CURRENT_PASSWORD: user current password to change

  NEW_PASSWORD: user new password to update in expiry condition

  UNLOCK: unlock user

  RENEW: renew user

Options:

  --password TEXT             user password

  --remove-project TEXT       removes project from user: 'project'

  --add-project-role TEXT     adds project,role(s) mapping: 'project,role1,role2,...'

  --remove-project-role TEXT  removes project,role(s) mapping: 'project,role1,role2,...'

  --current_password TEXT     user current password

  --new_password TEXT         user new password to update in expiry condition

  --unlock                    unlock user

  --renew                     renew user

  -h, --help                  Show this message and exit.

```

## Project management

### How to enable user management enhancements to enforce password best practices

If a user logins into OSM for the first time or a user account is not accessed after several days, you might want OSM to request the user to change its password.

By default, user management enhancements to enforce password best practices is enabled in OSM. It includes the following best practices:

- Password expires after 30 days, and it will have to be renewed.

- Account expires after 90 days after the user is created, and it will have to be renewed by a system admin.

- The number of consecutive failed login attempts in OSM is 5. After that, if a user fails to login, the account will be locked.

If you want to enable/disable this behaviour, just set environment variable `OSMNBI_USER_MANAGEMENT` as `True` or `False` in the nbi configmap file using the following command:

```bash

kubectl -n osm edit configmap nbi

```

```yaml

OSMNBI_USER_MANAGEMENT: True|False

```

![OSM RBAC Options](assets/800px-OSM_User_Management.png)

### How to check that user management enhancements are applied

Ensure RBAC permissions for the user include rbac: `users:id:patch` permission.

```

osm user-show <USER_NAME>

osm role-show <ROLE_NAME>

# The role should include the permission "users:id:patch" set to true

```

### How to manage user password updates and user locks

- To change the default password or expired password of a user, execute the following command through CLI.

  ```bash

  osm --user <username> --password <password> user-update <username> --current_password <password> --new_password <new_password>

  ```

  Example:

  ```bash

  osm --user test_user --password Test@123 user-update test_user --current_password Test@123 --new_password New@1234

  ```

- If the user account is locked after exceeding the count of multiple tries, execute the following command to unlock the user through CLI

  ```bash

  osm user-update <username> --unlock

  ```

  Example:

  ```bash

  osm user-update test_user --unlock

  ```

- If the user account is expired, execute the following command to renew the user account through CLI

  ```bash

  osm user-update <username> --renew

  ```

  Example:

  ```bash

  osm user-update test_user --renew

  ```

**Important note:**

- User Management check is excluded for the default "admin" user

- Only a user with system_admin role persmission will have the privilege to perform unlock and renew actions

## OSM Project management

Projects can be managed through the UI, by selecting Admin --> Projects on the menu to the left, or using the OSM CLI:

  - Add role R1, projects P1: `'{add_project_role_mappings: [{project: role: R1}, ...]}'`

  - Remove role R1, project P1 from user: `{remove_project_role_mappings: [{project: P1, role: R1}]}'`

  - Remove a project 'P1' (all roles) from user: `{remove_project_role_mappings: [{project: P1}]}'`

  - Enforce password change on first login or password expiry: `'{old_password: <old_pass>, password: <new_pass>}'`

  - Unlock user: `'{system_admin_id: <system_admin_id>, unlock: true}'`

  - Renew user: `'{system_admin_id: <system_admin_id>, renew: true}'`

- DELETE: Removes user.