4.24   Roles

This section describes behavior of the Role resource in MWS. The role resource is used to control access to MWS resources based on the proxy-user. Each role is attached to a principal and contains a list of proxy-user permissions that the group can use in MWS. This section describes the URLs, request bodies, and responses delivered to and from MWS.

The 8.4.21 Fields: Roles reference section contains the type and description of all fields in the Role object. It also contains details regarding which fields are valid during PUT and POST actions.

Supported Methods

Resource GET PUT POST DELETE
/rest/roles

Get All Roles

Get Default Permissions on Default Roles

-- Create Single Role --
/rest/roles/<id>

Get Single Role

Modify Single Role

Reset Role Permissions

-- Deleting Roles
/rest/roles/<name> Get Single Role

Modify Single Role

Reset Role Permissions

-- Delete Single Role

In this section:

4.24.1 Getting Roles

The HTTP GET method is used to retrieve Role information. You can query all objects or a single object.

Quick Reference

GET https://localhost:8080/mws/rest/roles?api-version=3[&query={"field":"value"}&sort={"field":<1|-1>}]
GET https://localhost:8080/mws/rest/roles/<id>?api-version=3
GET https://localhost:8080/mws/rest/roles/<name>?api-version=3

4.24.1.A  Get All Roles

URLs and Parameters

GET https://localhost:8080/mws/rest/roles?api-version=3[&query={"field":"value"}&sort={"field":<1|-1>}]
Parameter Required Type Value Description Example
query No JSON --

Queries for specific results.

It is possible to query roles by one or more fields based on MongoDB query syntax.

 query={"name":"Acme-User-Role"}
sort No JSON --

Sort the results. Use 1 for ascending and -1 for descending.

 sort={"name":-1}

See 3.3  Global URL Parameters for available URL parameters.

Sample Response

GET https://localhost:8080/mws/rest/roles?api-version=3&fields=id,name
------------------------------------

{
  "totalCount": 1,
  "resultCount": 1,
  "results": [  {
    "id": "4fa197e68ca30fc605dd1cf0",
    "name": "Acme-User-Role"
  }]
}

Sorting and Querying

See the sorting and querying sections of 3.3  Global URL Parameters.

4.24.1.B  Get Default Permissions on Default Roles

The defaults parameter is used to list the default permissions that are attached to the default roles.

URLs and Parameters

GET https://localhost:8080/mws/rest/roles?api-version=3&defaults=true

See 3.3  Global URL Parameters for available URL parameters.

Sample Response

JSON response
------------------------------------
{
  "totalCount": 2,
  "resultCount": 2,
  "results":   [
        {
      "name": "HPCUser",
      "description": "Basic user, with permission to create and manage their own jobs",
      "scope": "GLOBAL",
      "permissions":       [
                {
          "action": "read",
          "administrator": false,
          "description": "Read nodes",
          "fieldPath": "*",
          "id": "5612b526e4b0b5b9bc0db341",
          "label": "read-nodes",
          "resource": "nodes",
          "resourceFilter": null,
          "scope": "GLOBAL",
          "type": "domain",
          "version": 0
        },
                {
          "action": "create",
          "administrator": false,
          "description": "Create jobs",
          "fieldPath": null,
          "id": "5612b526e4b0b5b9bc0db345",
          "label": "create-jobs",
          "resource": "jobs",
          "resourceFilter": null,
          "scope": "GLOBAL",
          "type": "domain",
          "version": 0
        },
		...
      ]
    },
        {
      "name": "HPCAdmin",
      "description": "Administrative user, with privileges for all features and jobs",
      "scope": "GLOBAL",
      "permissions":       [
                {
          "action": "read",
          "administrator": false,
          "description": "Read nodes",
          "fieldPath": "*",
          "id": "5612b526e4b0b5b9bc0db341",
          "label": "read-nodes",
          "resource": "nodes",
          "resourceFilter": null,
          "scope": "GLOBAL",
          "type": "domain",
          "version": 0
        },
		...
      ]
    }
  ]
}

4.24.1.C  Get Single Role

URLs and Parameters

GET https://localhost:8080/mws/rest/roles/<id>?api-version=3
GET https://localhost:8080/mws/rest/roles/<name>?api-version=3
Parameter Required Type Value Description
id Yes String -- The unique identifier of the Role.
name Yes String -- The name of the Role.

You must specify either id or name, but you do not have to specify both.

See 3.3  Global URL Parameters for available URL parameters.

Sample Response

GET https://localhost:8080/mws/rest/roles/Acme-User-Role?api-version=3
------------------------------------

{
	"description" : "This is a role for normal users in the Acme BU Group.",
	"id" : "5022e695e4b073f54e47c28d",
	"name" : "Acme-User-Role",
	"permissions" : [ {
		"action" : "create",
		"administrator" : null,
		"description" : "The permission to create all charts.",
		"id" : "5022e695e4b073f54e47c28e",
		"label" : "Create Chart",
		"resource" : "chart",
		"resourceFilter" : null,
		"type" : "custom",
		"scope" : "GLOBAL",
		"version" : 0
	}, {
		"action" : "read",
		"administrator" : null,
		"description" : "The permission to view all charts.",
		"id" : "5022e695e4b073f54e47c28f",
		"label" : "View Chart",
		"resource" : "chart",
		"resourceFilter" : null,
		"type" : "custom",
		"scope" : "GLOBAL",
		"version" : 0
	}, {
		"action" : "update",
		"administrator" : null,
		"description" : "The permission to modify the africa chart.",
		"id" : "5022e695e4b073f54e47c290",
		"label" : "Modify Africa Chart",
		"resource" : "chart",
		"resourceFilter" : {
			"name" : "africa"
		},
		"type" : "custom",
		"scope" : "GLOBAL",
		"version" : 0
	}, {
		"action" : "read",
		"administrator" : null,
		"description" : "The permissions to view John's services.",
		"id" : "5022e695e4b073f54e47c291",
		"label" : "Read John's services",
		"resource" : "services",
		"resourceFilter" : {
			"user":"john"
		},
		"type" : "api",
		"scope" : "GLOBAL",
		"version" : 0
	} ],
	"version" : 2
}

4.24.2 Creating Roles

The HTTP POST method is used to submit Roles.

Quick Reference

POST https://localhost:8080/mws/rest/roles?api-version=3

4.24.2.A  Create Single Role

URLs and Parameters

POST https://localhost:8080/mws/rest/roles?api-version=3

See 3.3  Global URL Parameters for available URL parameters.

Request Body

The name field is required and must contain only letters, digits, periods, dashes, and underscores.

The following is an example of a request body to create a role:

POST https://localhost:8080/mws/rest/roles?api-version=3
------------------------------------

{
	"name" : "Acme-User-Role",
	"description" : "This is a role for normal users in the Acme BU Group.",
	"permissions" :
	[
		{
		"id" : "4fa197e68ca30fc605dd1cf0"
		},
		{
		"id" : "4fa197e68ca30fc605dd1df2"
		}
	]
}

Sample Response

If the request was successful, the response body is the new role that was created, exactly as shown in section 4.24.1.C  Get Single Role. On failure, the response is an error message.

Samples

The permissions field only expects an array of permission IDs, as shown in the following example:

Example payload of role with 2 permissions
------------------------------------

{
	"name" : "Acme-User-Role",
	"description" : "This is a role for normal users in the Acme BU Group.",
	"permissions" :
	[
		{
		"id" : "4fa197e68ca30fc605dd1cf0"
		}
	]
}

4.24.3 Modifying Roles

The HTTP PUT method is used to modify Roles.

Quick Reference

PUT https://localhost:8080/mws/rest/roles/<id>?api-version=3
PUT https://localhost:8080/mws/rest/roles/<name>?api-version=3

4.24.3.A  Modify Single Role

URLs and Parameters

PUT https://localhost:8080/mws/rest/roles/<id>?api-version=3
PUT https://localhost:8080/mws/rest/roles/<name>?api-version=3
Parameter Required Type Value Description
id Yes String -- The unique identifier of the Role.
name Yes String --

The name of the Role.

The name field must contain only letters, digits, periods, dashes, and underscores.
change-mode No String

add

remove

set (default)

If add, adds the given permissions to the permissions that already exist.

If remove, deletes the given permissions from the permissions that already exist.

If set, adds the given permissions and deletes the permissions that already exist.

You must specify either id or name, but you do not have to specify both.

See 3.3  Global URL Parameters for available URL parameters.

Example Request

PUT https://locahost/mws/rest/role/Acme-User-Role?change-mode=add?api-version=3
------------------------------------

{
	"permissions":[{"id":"4fa197e68ca30fc605dd1cf0"} ]
}

Sample Response

If the request was successful, the response body is the modified role as shown in section 4.24.1.C  Get Single Role. On failure, the response is an error message.

4.24.3.B  Reset Role Permissions

The reset-permissions parameter is used to reset the permissions on a role to match the permissions of one of the default roles.

URLs and Parameters

PUT https://localhost:8080/mws/rest/roles/<role>?api-version=3&reset-permissions=<default-role>
Parameter Required Type Value Description
role Yes String --- The role to be modified.
default-role Yes String --- The name of the default role whose permissions will be applied to the <role>.

See 3.3  Global URL Parameters for available URL parameters.

Request Body

JSON request body (required)
------------------------------------

{}

Sample Response

{
  "description": "Basic user, with permission to create and manage their own jobs",
  "id": "5612b526e4b0b5b9bc0db389",
  "name": "HPCUser",
  "permissions":   [
        {
      "action": "read",
      "administrator": false,
      "description": "Read nodes",
      "fieldPath": "*",
      "id": "5612b526e4b0b5b9bc0db341",
      "label": "read-nodes",
      "resource": "nodes",
      "resourceFilter": null,
      "scope": "GLOBAL",
      "type": "domain",
      "version": 0
    },
        {
      "action": "create",
      "administrator": false,
      "description": "Create jobs",
      "fieldPath": null,
      "id": "5612b526e4b0b5b9bc0db345",
      "label": "create-jobs",
      "resource": "jobs",
      "resourceFilter": null,
      "scope": "GLOBAL",
      "type": "domain",
      "version": 0
    },
	...
  ],
  "scope": "GLOBAL",
  "version": 2
}

4.24.4 Deleting Roles

The HTTP DELETE method is used to delete Roles.

Quick Reference

DELETE https://localhost:8080/mws/rest/roles/<id>?api-version=3
DELETE https://localhost:8080/mws/rest/roles/<name>?api-version=3

4.24.4.A  Delete Single Role

URLs and Parameters

DELETE https://localhost:8080/mws/rest/roles/<id>?api-version=3
DELETE https://localhost:8080/mws/rest/roles/<name>?api-version=3
Parameter Required Type Value Description
id Yes String -- The unique identifier of the Role.
name Yes String -- The name of the Role.

You must specify either id or name, but you do not have to specify both.

See 3.3  Global URL Parameters for available URL parameters.

Sample Response

JSON response
------------------------------------

{}

Related Topics