
[[ga-role-user-management-roles]]
= Assign User Permissions
:description: How to assign user permissions in {page-component-title}: default security roles (admin, RTC, asset editor, etc.) and creating custom security roles.

You can control user permission levels by creating and assigning security roles.
These roles regulate access to the {page-component-title} web UI and the REST API to exchange monitoring and inventory information.
ifndef::opennms-prime[]

In a distributed installation, Minion instances require an account that is assigned the `ROLE_MINION` security role to interact with {page-component-title}.
You can create one account for all Minions to share, or one account per Minion.
endif::opennms-prime[]

[[built-in-security-roles]]
== Built-in security roles

The following security roles are built in to {page-component-title} by default.
Those marked with an asterisk are the most commonly used.

[caption=]
.Default {page-component-title} security roles
[cols="1,2"]
|===
| Security Role | Description

| ROLE_ADMIN *
| Permissions to create, read, update, and delete items via the web UI and the REST API (see `ROLE_FILESYSTEM_EDITOR` for exceptions).

| ROLE_ASSET_EDITOR
| Permissions only to update asset records from nodes.

| ROLE_FILESYSTEM_EDITOR
| Permissions only to view and update file configuration data via the REST API. +
Note that `ROLE_ADMIN` users cannot view or edit configurations unless they also have the `ROLE_FILESYSTEM_EDITOR` role.
Also, for a user with `ROLE_FILESYSTEM_EDITOR` to use the UI, they need `ROLE_USER` or a similar role.

| ROLE_DASHBOARD
| Permissions only to view the dashboard.

| ROLE_DELEGATE
| Permissions to perform actions (such as acknowledging an alarm) on behalf of another user.

| ROLE_DEVICE_CONFIG_BACKUP
| Permissions to view and trigger device configuration backups.

| ROLE_FLOW_MANAGER
| Permissions to edit flow classifications.

| ROLE_JMX
| Permissions to retrieve JMX metrics.
Does not allow the user to run {page-component-title} JVM MBeans, even if they return only simple values.
ifndef::opennms-prime[]

| ROLE_MINION
| Minimum permissions required for a Minion to operate.
endif::opennms-prime[]

| ROLE_MOBILE
| Permissions to use OpenNMS COMPASS mobile application to acknowledge alarms and notifications via the REST API.

| ROLE_PROVISION
| Permissions to use the provisioning system and configure SNMP in {page-component-title} to access management information from devices.

| ROLE_READONLY *
| Permissions only to read information in the web UI.
Does not allow user to change alarm states or notifications.

| ROLE_REPORT_DESIGNER
| Permissions to manage reports in the web UI and REST API.

| ROLE_REST
| Permissions to interact with the entire {page-component-title} REST API.

| ROLE_RTC *
| Permissions to exchange information with the {page-component-title} Real-Time Console for availability calculations.

| ROLE_USER *
| Default permissions for a new user to interact with the web UI.
Allows users to escalate and acknowledge alarms and notifications.
|===

== Assign security roles

Follow the steps below to assign security roles to user accounts:

. Click menu:User Management[Manage Users] in the side menu.
. Or, click menu:Administration[Configure OpenNMS] in the side menu, then under OpenNMS System, click menu:Configure Users, Groups and On-Call Roles[Configure Users].
. Find the user to whom you want to assign a security role and click *Modify* beside their name.
. Select the role to add to the user account from the *Available Roles* list, and click *Add*.
** Follow this step to add as many roles as necessary to the account.
. Click *Finish* to apply the changes.
. Log out of {page-component-title} and log back in to apply the new security role settings.

== Create custom security roles

To create a custom security role, you need to define its name and specify the permissions it will provide.
Follow the steps below to create a custom role:

. Create `$\{OPENNMS_HOME}/etc/security-roles.properties` in your OpenNMS directory.
. Add a `roles` property, and enter a comma-separated list of the custom security roles for its value:
+
.Example of a `roles` property
[source, properties]
roles=operator,stage

. Save the file.

NOTE: To define permissions associated with a custom security role, you must manually update the Spiring security application context in `$\{OPENNMS_HOME}/jetty-webapps/opennms/WEB-INF/applicationContext-spring-security.xml`.
