# Managing users and permissions

Security and access control is a very important aspect of any infrastructure. MetalSoft uses two concepts for permission management:
* **RBAC** for admin operations
* **Delegation** for user operations

Separately, MetalSoft uses multiple forms of authentication:
1. Built-in
2. LDAP-based
3. SAML-based

More than one form can be active at any given time. Use Global `Configuration` > `Authentication` to manage them. 

Consult [Authentication Overview](/content/configuration/users_and_permissions/authentication_overview) for more details.

## User accounts

Users that interact with the MetalCloud must have an "account" identified by email and password, API key and - if enabled - protected by 2FA. Accounts can also be created in an external ID provider such as Active Directory, Okta, Auth0. MetalSoft supports LDAP, SAML and Oauth2.

## Role based access control (RBAC)


MetalSoft accounts all have a **Role** associated with them.  Roles are then associated with permissions that enable or disable certain features of MetalSoft. The list is constantly changing, checkout the 

MetalSoft provides several built-in roles that cannot be edited:
* Root - highest level. 
* Full Admin - Similar to Root but cannot put the system into maintenance and cannot edit prices
* Basic Admin - Primarily read only across all admin resources
* User - Access only to infrastructures and the user interface

Custom roles can also be created.  In general, the permissions follow the Admin UI providing with `read` and `write` to the respective resources. For example the `workflow_read` will allow a read-only view of the *Workflows* section. Having `workflow_write` will allow you to edit the workflows.

The following is the current list of permissions:


## Users related permissions

* **users_read** - Allows the read details about a user such as name
* **users_write** - Allows the change details about a user such as name
* **users_and_permissions_read** - Allows the read of user's role, limits and credentials access
* **users_and_permissions_write** - Allows the change of a user's role, limits and credentials access
* **users_2fa_disable** - Allows the disabling of a user's 2FA setting
* **skip_user_limits** - Permission to be set on role when user utilization limits should not be checked by the system.
* **skip_authenticator** - Permission to be set on role if 2FA authentication is optional.
* **metalcloud_access** - Default permission for user role

### Network profiles
* **network_profiles_read** - Allows a read operation on public network profile objects.
* **network_profiles_write** - Allows a write operation on public network profile objects.
* **network_profiles_allowed_for_user_read** -  Allows a write operation on specific user's network profile objects.
* **network_profiles_allowed_for_user_write** - Allows a write operation on specific user's network profile objects.
* **network_profiles_allow_specific_vlan_ids** - Allow a specific VLAN rather than automatically allocated ones. This has security implications as it allows the use of VLANs that might be in use by other users.

## Licenses related permissions
* **Licenses read** - Allows the read of licensing details
* **Licenses write** - Allows the change of licensing details such as adding a new license key.

## Firmware related permissions
* **firmware_upgrade_read** - Allows the user to read firmware-related objects such as baselines.
* **firmware_upgrade_read** - Allows the user to create and edit firmware-related objects such as baselines.
* **firmware_baselines_read** - (not used)
* **firmware_baselines_write** - (not used)

##  Datacenter related permissions

* **datacenter_read** - Datacenter Read
* **datacenter_write** - Datacenter Write

## Servers 
* **servers_read** - Allows read of server object details.
* **servers_write** - Allows change and edit of server object details such as tags.
* **server_types_read** - Allows read of server type object details such as tags.
* **server_type_utilization_report_read** - Allows read of server type utilization report.

## Switches
* **switches_read** - Allows read of switch object.
* **switches_write** - Allows creation, edit and delete of switch object.

## Storage
* **storage_read** - Allows read of storage objects.
* **storage_write** - Allows creation,edit and delete of storage objects.

## IPAM Subnets
* **subnets_read** - Allows read of subnet objects.
* **subnets_write** - Allows creation, edit and delete of subnet objects.

## Infrastructures
* **infrastructures_read** - Allows the read of infrastructures details of other users
* **infrastructures_write** - Allows the user to delete or change other user's infrastructures. 

## OS Templates
* **templates_read** - Allows the creation of templates
* **templates_write** - Allows the user to create, edit and delete templates


## Events & jobs
* **events_read** - Allows the listing of events
* **events_write** - (Not used)
* **job_queue_read** - Allows the listing of jobs
* **job_queue_write** - Allows operations on jobs such as resume.

## Workflows
* **workflows_read** - Allows listing and details view of workflow objects.
* **workflows_write** - Allows creation, change and delete of workflow objects.
* **variables_and_secrets_read** - Allows listing of variables and secrets and view of only the variables object but not that of secrets.
* **variables_and_secrets_write** - Allows the creation, edit and delete of variables.

## Prices & Subscriptions
* **prices_read** - Allows user to read prices objects for resources (deprecated)
* **prices_write** - Allows user to set prices for resources (deprecated)
* **subscriptions_read** - Allows listing of reservations of all users.
* **subscriptions_write** - Allows creation, edit and delete of reservations for other users.

## Reports
* **utilization_reports_read** - Allows read of other user's utilization reports

## Utility
* **admin_access** - Allows access to the admin interface
* **suspend_reasons_read** - Allows user to see suspend reasons
* **suspend_reasons_write** - Allows user to suspend other users and add reasons
* **global_configurations_write** - Global Configurations Write
* **global_configurations_read** - Global Configurations Read
* **maintenance_read** - Allows the user to view the user interface maintenance flag (deprecated)
* **maintenance_write** - Allows the user to change the user interface maintenance flag (deprecated)
* **admin_maintenance_read** - Allows the user to view the admin interface maintenance flag (deprecated)
* **admin_maintenance_write** - Allows the user to view the admin interface maintenance flag (deprecated)


## Deprecated permissions, do not use 
* **cluster_read** - (deprecated)
* **cluster_write** - (deprecated)
* **container_platform_read** - (deprecated)
* **container_platform_write** -  (deprecated)
* **datalake_read** - (deprecated)
* **datalake_write** - (deprecated)
* **dataset_read** - (deprecated)
* **dataset_write** - (deprecated)
* **cloudinit_read** - (deprecated)
* **cloudinit_write** - (deprecated)
* **datastore_read** - (deprecated)
* **datastore_write** - (deprecated)
* **franchises_write** - (deprecated)
* **threshold_write** - (deprecated)
* **threshold_read** - (deprecated)
* **monitoring_agent_read** -(deprecated)
* **monitoring_agent_write** - (deprecated)
* **emails_write** - (deprecated)
* **resources_write** - (deprecated)


## Resource ownership

Many resources have an owner associated with them. In that case some resources (such as OS templates and Workflows) will not be visible to the other admins until they are published. This is controlled by a property called visibility. Set the visibility to 'public' to share the resource with other users.


## The "Billable" account

Only infrastructures that are owned by a `Billable` account can be deployed. Normally in an organization only one account will have Billing activated such as by adding a credit card. This flag can also be used by an external Billing system to determine who needs to be invoiced.


## Credentials access - **DEPRECATED** 

All credentials in MetalSoft are encrypted. A special set of permissions are needed to allow an account access to the various credentials for equipment or client instances. Use the **Users & Permissions/<user>/Credentials Access** section to enable or disable access to certain credentials.

Note that in future versions of our software this feature will be combined with the RBAC feature and normal permissions will be created.


## User limits

Accounts also have various limits associated with them such as the maximum number of servers an account can provision. These are added to prevent abuse or Denial-of-Service type attacks. Use the **Users & Permissions/<user>/Limits** section to change these limits.

## Suspend and unsuspend a user

Sometimes it is required to suspend a user temporarily. This is useful in service provider scenarios for users with billing or security issues.

A suspended user:
- All infrastructures's servers will be disconnected from WAN networks.  Servers are still kept powered on.
- Can access the infrastructure editor and has access to credentials although they cannot be used to access the server normally except via the remote console.
- Cannot deploy infrastructures of type create or edit
- Can delete infrastructures
- Cannot create reservations
- Can access the API but the above operations are not possible

To suspend a user go to the **Users & Permissions** > **user's details page** > **Advanced** > **Suspend**. A form will pop-up asking for a suspend reason.
A user can be suspended for multiple reasons and all suspend reasons will need to be cleared before the account is re-enabled fully. An admin can add "suspend reasons" from the same Advanced tab for the user.

To unsuspend a user go to **Users & Permissions** > **user's details page** > **Advanced** > **Unsuspend**.

## Block and unblock user

In certain rare situations a user needs to be completely blocked from accessing an environment but kept visible to admins. This is usually due to a serious security issue.
- Access to the API is restricted
- Access tot the UI is restricted
- Remote console access to serves is restricted

:::{Warning}
The servers and internet connections are untouched! Note that if the servers need to be blocked you need to use the suspend function! And/or suspend the server.
:::

To block a user go to: **Users & Permissions** > **user's details page** > **Advanced** > **Block**
To unblock a user go to: **Users & Permissions** > **user's details page** > **Advanced** > **Unblock**

## Archiving an user
> Available since 6.2.1
Users cannot be deleted for security reasons. They may have associated audit log events, deleted infrastructure records, utilization records.  Instead they are "archived":
- Hidden from the Admin UI
- Access to the API is restricted
- Access tot the UI is restricted

Note that if the same email address is used again or same account is used again the old account needs to be un-archived. 
To block a user go to: **Users & Permissions** > **user's details page** > **Advanced** > **Archive**
To unblock a user go to: **Users & Permissions** > **Search the user by name or email** > **user's details page** > **Advanced** > **Unarchive**


## Delegation


* Account delegate of another user
* Infrastructure delegate


### Example scenario

To help understand delegation consider consider the following scenario:
1. **A billing account** (finance@company.com) is created using an email that will reach the department in charge with paying the invoices. The department will not actually manage infrastructures but will receive invoices.
2. **An OPS account** (ops@company.com) is added by the finance department as an account delegate of the finance account. 
4. The ops account is now able to create infrastructures: **A Web Infrastructure** for the marketing department, a **Hadoop infrastructure** for the BI department and an **ERP infrastructure** for the Logistics department
5. The Ops user then invites user mktg@company.com form the marketing department to the Web infrastructure using infrastructure delegation.
6. The Ops user also invites user logistics@company.com form the logistics department to the ERP infrastructure using infrastructure delegation.
7. Lastly, the Ops user invites user bi@company.com form the BI department to the Hadoop and the ERP infrastructures using infrastructure delegation.

![](/assets/user/guides/managing_users_and_permissions_1.svg)

The result of this setup is that:
* OPS has the ability to oversee and manage all infrastructures
* Marketing and logistics departments each manage their own infrastructures only
* BI team has access to it's infrastructure (the hadoop infrastructure) but also to the ERP infrastructure
* The Finance team then receives invoices for all infrastructures.

* The detailed infrastructure utilization report will provide a breakdown of consumption for each individual department which enables charge-back to the respective departments. 


### Managing account delegation

Many organizations opt to have a finance/procurement department user as the billable user and have a second user as the technical user that actually performs operations "on-behalf-of" the organization. This relationship is called "account delegation".

If enabled this second user will have all rights that the owner of the infrastructures has.

Any number of users can be account delegates.

To add an account delegate access **Account Settings** (Infrastructure Editor > Account Settings)

![](/assets/user/guides/managing_users_and_permissions_2.png)

Click on **Account sharing** (Infrastructure Editor > Account Settings > Account Sharing)

![](/assets/user/guides/managing_users_and_permissions_3.png)

Add the email address of the delegated user that the user uses to login to manage the Metalcloud.

![](/assets/user/guides/managing_users_and_permissions_4.png)

As a delegated account, from this page you can also **Impersonate**  a user in order to perform payments or change credit card information on his/hers behalf.

This mechanism can be used if the primary account is a technical one somebody else needs to perform manual payment, download invoices etc.

### Managing infrastructure delegation

A user can be "invited" by an owner or account delegate of an infrastructure to have access only to that respective infrastructure. This is used in situations where internal users or clients of a company reselling MetalCloud services need to have access to a specific infrastructure. 

Users will have full access to manage that infrastructure but the billable account that is the owner of the infrastructure will receive the invoices.

To add a delegate on an infrastructure access the **Infrastructure properties** dialog by clicking the the cogwheel:

![](/assets/user/guides/managing_users_and_permissions_5.png)

Click on the **Sharing** tab and enter the login email of the user that is to be granted permissions.  The user will receive an invite email on that address.

![](/assets/user/guides/managing_users_and_permissions_6.png)

If the user doesn't have a MetalCloud account he will be invited to create one but no CC information will be required.


Where to go from here:
* [Retrieving the utilization report](/content/user/retrieving_the_utilization_report)