Groups

A group is a way to organize users in a system. We can also give roles to groups instead of users.

Basic Operations

Basic operations of Create, List, Update and Destroy are available for groups

List all Groups

Call to /authorization/group to get all groups.

Request Object

+ URL
  /api/v2/authorization/group

+ Method
  GET

+ Headers
  Content-Type: application/json
  token: ThisIsNotARealTokenGenerateYourOwnToken

+ Body
  {}

Response Object

Sending this should get you back a valid response, an array with each group in the system.

+ Headers
  X-Powered-By: OpenDrives
  Access-Control-Allow-Origin: *
  Content-Type: application/json; charset=utf-8

+ Body
  [
    {
      "groupname": "root",
      "password": "x",
      "gid": 0,
      "users": []
    },
    {
      "groupname": "sudo",
      "password": "x",
      "gid": 27,
      "users": [
        "open"
      ]
    },
    {
      "groupname": "games",
      "password": "x",
      "gid": 60,
      "users": []
    },
    {
      "groupname": "nogroup",
      "password": "x",
      "gid": 65534,
      "users": []
    },
    {
      "groupname": "ssl-cert",
      "password": "x",
      "gid": 113,
      "users": [
        "postgres"
      ]
    },
    {
      "groupname": "users",
      "password": "x",
      "gid": 997,
      "users": []
    },
    {
      "groupname": "asdf",
      "password": "x",
      "gid": 1000,
      "users": []
    },
    {
      "groupname": "gitlab-runner",
      "password": "x",
      "gid": 995,
      "users": []
    }
  ]

Get one Group

Call to /authorization/group/$GROUPNAME/details to get details on a specific group.

Request Object

+ URL
  /api/v2/authorization/group/$GROUPNAME/details

+ Method
  GET

+ Parameters
  group name (string, required, URL param) - the name of the group you'd like to get details about

+ Headers
  Content-Type: application/json
  token: ThisIsNotARealTokenGenerateYourOwnToken

+ Body
  {}

Response Object

Sending this should get you back a valid response, an array with the group you requested.

+ Headers
  X-Powered-By: OpenDrives
  Access-Control-Allow-Origin: *
  Content-Type: application/json; charset=utf-8

+ Body
  {
    "groupname": "asdf",
    "password": "x",
    "gid": 1000,
    "users": [],
    "roles": [],
    "permissions": []
  }

Create a Group

Creating a group takes a groupname, as well as any desired role ids to be assigned to members of that group.

Request Object

+ URL
  /api/v2/authorization/group/create

+ Method
  POST

+ Parameters
  groupname (string, required, Body) - The name to be assigned to this group
  rids (string, optional, Body) - A comma delimited list of role ids.

+ Headers
  Content-Type: application/json
  token: ThisIsNotARealTokenGenerateYourOwnToken

+ Body
  {
    "groupname": "testing",
    "rids": "3"
  }

Response Object

Sending this should get you back a valid response, an array with the group you created.

+ Headers
  X-Powered-By: OpenDrives
  Access-Control-Allow-Origin: *
  Content-Type: application/json; charset=utf-8

+ Body
  {
    "groupname": "testing",
    "password": "x",
    "gid": 1001,
    "users": [],
    "rids": [
        "3"
    ]
  }

Update a Group

You may change the groupname, gid, and rids of any group you have created.

Request Object

+ URL
  /api/v2/authorization/group/$GROUPNAME/update

+ Method
  POST

+ Parameters
  groupname (string, required, URL param) - The current name of this group
  name (string, optional, Body) - The name to be assigned to this group after this update
  gid (number, optional, Body) - The gid to assign to this group
  rids (string, optional, Body) - A comma delimited list of role ids.

+ Headers
  Content-Type: application/json
  token: ThisIsNotARealTokenGenerateYourOwnToken

+ Body
  {
    "name": "testing_again",
    "gid": 1122,
    "rids": "1,2"
  }

Response Object

Sending this should get you back a valid response, an array with the group you updated.

+ Headers
  X-Powered-By: OpenDrives
  Access-Control-Allow-Origin: *
  Content-Type: application/json; charset=utf-8

+ Body
  {
    "groupname": "testing_again",
    "password": "x",
    "gid": 1122,
    "users": [],
    "rids": [
        "1",
        "2"
    ]
  }

Destroy a Group

Destroying a group removes the group from the system, but will not destroy the users assigned to that group.

Request Object

+ URL
  /api/v2/authorization/group/$GROUPNAME/destroy

+ Method
  GET

+ Parameters
  group name (string, required, URL param) - the name of the group you'd like to destroy

+ Headers
  Content-Type: application/json
  token: ThisIsNotARealTokenGenerateYourOwnToken

+ Body
  {}

Response Object

Upon destroying the group, you will receive back the id the group formerly occupied.

+ Headers
  X-Powered-By: OpenDrives
  Access-Control-Allow-Origin: *
  Content-Type: application/json; charset=utf-8

+ Body
  {
    "id": 1122
  }

Group Roles

Instead of Updating groups with role information, you can manage group to role ties directly. This is useful for Active Directory or otherwise 3rd party managed authorization sources where you want to assign roles to groups not managed by the Atlas System

Basic operations of List, Assign, and Unassign are available for group roles.

List all Group to Role ties.

Listing all ties is very simple.

Request Object

+ URL
  /api/v2/authorization/group/role

+ Method
  GET

+ Headers
  Content-Type: application/json
  token: ThisIsNotARealTokenGenerateYourOwnToken

+ Body
  {}

Response Object

Sending this should get you back a valid response, an array with each group to role tie in the system.

+ Headers
  X-Powered-By: OpenDrives
  Access-Control-Allow-Origin: *
  Content-Type: application/json; charset=utf-8

+ Body
  [
    {
      "id": 1,
      "hostid": "09e3b2bd",
      "groupname": "sudo",
      "rid": 2,
      "createdAt": "2020-09-09T03:10:21.227Z",
      "updatedAt": "2020-09-09T03:10:21.227Z"
    },
    {
      "id": 10,
      "hostid": "09e3b2bd",
      "groupname": "testing_once_more",
      "rid": 1,
      "createdAt": "2020-09-28T18:56:27.493Z",
      "updatedAt": "2020-09-28T18:56:27.493Z"
    },
    {
      "id": 11,
      "hostid": "09e3b2bd",
      "groupname": "testing_once_more",
      "rid": 2,
      "createdAt": "2020-09-28T18:56:27.493Z",
      "updatedAt": "2020-09-28T18:56:27.493Z"
    },
    {
      "id": 12,
      "hostid": "09e3b2bd",
      "groupname": "testing_once_more",
      "rid": 3,
      "createdAt": "2020-09-28T18:56:27.494Z",
      "updatedAt": "2020-09-28T18:56:27.494Z"
    },
    {
      "id": 13,
      "hostid": "09e3b2bd",
      "groupname": "testing_once_more",
      "rid": 5,
      "createdAt": "2020-09-28T18:56:27.495Z",
      "updatedAt": "2020-09-28T18:56:27.495Z"
    }
  ]

Get Group Role ties for a Group

You can also get all role ties for a specific group

Request Object

+ URL
  /api/v2/authorization/group/role/details

+ Method
  POST

+ Parameters
  groupname (string, required, Body) - The name of the group to get ties for

+ Headers
  Content-Type: application/json
  token: ThisIsNotARealTokenGenerateYourOwnToken

+ Body
  {
    "groupname": "sudo"
  }

Response Object

Sending this should get you back a valid response, an array with each group to role tie in the system for your group.

+ Headers
  X-Powered-By: OpenDrives
  Access-Control-Allow-Origin: *
  Content-Type: application/json; charset=utf-8

+ Body
  [
    {
      "id": 1,
      "hostid": "09e3b2bd",
      "groupname": "sudo",
      "rid": 2,
      "createdAt": "2020-09-09T03:10:21.227Z",
      "updatedAt": "2020-09-09T03:10:21.227Z"
    }
  ]

Assign a Role to a Group

You can assign a role to a group rather simply

Request Object

+ URL
  /api/v2/authorization/group/role/assign

+ Method
  POST

+ Parameters
  groupname (string, required, Body) - The name of the group to assign
  rid (number, required, Body) - The role ID number to assign

+ Headers
  Content-Type: application/json
  token: ThisIsNotARealTokenGenerateYourOwnToken

+ Body
  {
    "groupname": "sudo",
    "rid": 4
  }

Response Object

You will be returned the newly created entry.

+ Headers
  X-Powered-By: OpenDrives
  Access-Control-Allow-Origin: *
  Content-Type: application/json; charset=utf-8

+ Body
  [
    {
      "id": 14,
      "hostid": "09e3b2bd",
      "groupname": "sudo",
      "rid": 4,
      "createdAt": "2020-09-28T19:02:18.282Z",
      "updatedAt": "2020-09-28T19:02:18.282Z"
    }
  ]

Unassign a Role from a Group

Similar to Assign, you may also un-assign.

Request Object

+ URL
  /api/v2/authorization/group/role/unassign

+ Method
  POST

+ Parameters
  groupname (string, required, Body) - The name of the group to unassign
  rid (number, required, Body) - The role ID number to unassign

+ Headers
  Content-Type: application/json
  token: ThisIsNotARealTokenGenerateYourOwnToken

+ Body
  {
    "groupname": "sudo",
    "rid": 4
  }

Response Object

You will be returned the id of the group-to-role tie that was used.

+ Headers
  X-Powered-By: OpenDrives
  Access-Control-Allow-Origin: *
  Content-Type: application/json; charset=utf-8

+ Body
  [
    14
  ]