Creating a role

You can create a new role.

Method and URI

To create a new role, use a POST method and a URI:

POST    https://{hostname|IPv4}/api/security/role

Parameters

None.

Data

Data 1: name

The name of the role.

  • Example value: Visitor

  • Type: String. Required. Available in the web user interface.

Data 2: description

The description of the role.

  • Example value: (None)

  • Type: String.

Data 3: permissionIds

Specify pairs of a permission group and a permission item to enable. For example, to enable Application Server-View and Job-View, the permissionIds key should have the value ["appserver.view", "policy.view"]. These permission items apply to both the web user interface and the REST API.

Permission group

Key

Available values

Databases / Cloud Management / Containers / File Systems

application

view

Application Server

appserver

register, view, edit, deregister

Certificate

certificate

create, view, edit, delete

Object Storage

cloudprovider

register, view, edit, deregister

Hypervisor

hypervisor

register, view, edit, deregister, options

Identity and Keys

identity

create, view, edit, delete

LDAP

ldap

register, view, edit, deregister

Log

log

view

Job

policy

create, view, edit, run, delete

VADP Proxy

proxy

register, view, edit, deregister

Report

report

create, view, edit, delete

Resource Group

resourcepool

create, view, edit, delete

Role

role

create, view, edit, delete

Script

script

upload, view, edit, delete

Script Server

scriptserver

register, view, edit, deregister

Site

site

create, view, edit, delete

SMTP

smtp

register, view, edit, deregister

Backup Storage

storage

register, view, edit, deregister

SLA Policy

storageprofile

create, view, edit, delete

User

user

create, view, edit, delete

In the REST API, you can toggle the permission to view and use the web user interface. This setting is not available in the Role pane of the web user interface.

Permission group

Key

Available values

Web User Interface

screen

view

Tip

Every user may have multiple roles. For example, assume that the user Sarah was associated with two system roles: VM Admin and Application Admin. In this case, she has all permission items for both virtualized systems and application servers.

  • Example value:

[
    "report.create",
    "report.view",
    "report.edit",
    "screen.view"
]
  • Type: Array. Required. Available in the web user interface.

Example 1: Create a role that can view everything

Assume that you want to create a new role Visitor. You want to allow users that are associated with this role to view all permission groups, including Web User Interface. A Python snippet that is similar to the following example can be used to create the role:

_data = f'''{{
    "name":          "Visitor",
    "description":   "",
    "permissionIds": [
        "application.view",
        "appserver.view",
        "certificate.view",
        "cloudprovider.view",
        "hypervisor.view",
        "identity.view",
        "ldap.view",
        "log.view",
        "policy.view",
        "proxy.view",
        "report.view",
        "resourcepool.view",
        "role.view",
        "screen.view",
        "script.view",
        "scriptserver.view",
        "site.view",
        "smtp.view",
        "storage.view",
        "storageprofile.view",
        "user.view"
    ]
}}'''

requests.post('https://' + spp_ipv4 + '/api/security/role',
    headers={...}, data=_data, verify=...)
_images/reference_accounts_role_create2.png

Figure 84 The same action can be taken in the IBM Spectrum Protect Plus web user interface: In the Role pane, click Add Role. Enter the required fields, specify permission groups, and click Create Role.

The request prompts a response that is structured as shown, with the HTTP status of 201 (Created). Review the response to ensure that the role Visitor was added. The response body is similar to the JSON object, as shown in Example 2: Get information about a specific role.

Example 2: Create a role that is permitted to only use the REST API

Assume that you want to create a role that has all permission items for Site, but the role must not use the web user interface.

As mentioned, revoking the permission to use the web user interface can be done from the REST API only. A Python snippet that is similar to the following example can be used to create such a role:

_data = f'''{{
    "name":          "Screen Only",
    "description":   "",
    "permissionIds": [
        "site.create",
        "site.view",
        "site.edit",
        "site.delete"
    ]
}}'''

requests.post('https://' + spp_ipv4 + '/api/security/role',
    headers={...}, data=_data, verify=...)

If the user Sarah is only associated with this role, she can view, create, edit, and delete sites through the REST API, but she cannot see anything in the web user interface, including the Site page.

_images/reference_accounts_role_create3.png

Figure 85 Sarah cannot see anything in the web user interface. However, she can take permitted actions through the REST API.