Support Center > Search Results > SecureKnowledge Details
Use the CloudGuard Dome9 API to setup Roles and Permissions for an account Technical Level
Solution

This article will illustrate how to automate the configuration of roles and permissions for your Dome9 account using the Dome9 API.

Resources used:

  • Role - this is used to add and update a new role to the Dome9 account (see Role)
  • CloudAccount - this is used to obtain the Dome9 account id (see CloudAccounts)
  • OrganizationalUnit - this is used to obtain the Dome9 id for an Org Unit (see OrganizationalUnit)

Prerequisites

  • you will need the API Key and Secret for your Dome9 account. These are used as the username & password to access your account with the API, using Basic Authentication.

Get all the roles in your account

Request

GET https://api.dome9.com/v2/Role

Response

The response gives all the roles currently defined for the account, with their permissions.

[  
   {  
      "id":76721,
      "name":"admin",
      "description":"admin",
      "permissions":{  
         "access":[  
            "1"
         ],
         "manage":[  
            "1"
         ],
         "create":[  
            "2"
         ],
         "view":[  
            ""
         ],
         "crossAccountAccess":[   ]
      }
   },
   {  
      "id":76641,
      "name":"Auditor",
      "description":"Auditor Role, Views all system resources",
      "permissions":{  
         "access":[  ],
         "manage":[  ],
         "create":[  ],
         "view":[  
            ""
         ],
         "crossAccountAccess":[  ]
      }
   },
   {  
      "id":76642,
      "name":"Super User",
      "description":"Super User Role, Manages all system resources",
      "permissions":{  
         "access":[  ],
         "manage":[  
            ""
         ],
         "create":[  
            "0",
            "2"
         ],
         "view":[  ],
         "crossAccountAccess":[  ]
      }
   }
]

 

Code sample

curl -X GET https://api.dome9.com/v2/Role/ \
  --basic -u <key-id>:<key-secret> \
  -H 'Accept: application/json'

Create a new role

Creating a new role is a 2 step process:

  • first we create (post) a new role with empty permissions
  • then we update (put) this role with the desired permissions

This is the JSON request block for the POST method:

{
	"name":"new-name",
	"description":"my-role-desc",
	"permissions": {
            "access": [],
            "manage": [],
            "create": [],
            "view": [],
            "crossAccountAccess": []
        }
}

Create a new role without permissions

Request

POST https://api.dome9.com/v2/Role

 {  
   "name":"new-role",
   "description":"my-role-desc",
   "permissions":{  
      "access":[  ],
      "manage":[  ],
      "create":[  ],
      "view":[  ],
      "crossAccountAccess":[  ]
   }
}

Response

The response shows the new role. The id, 94761, will be used to add permissions to the role.

 {  
   "id":94761,
   "name":"new-role",
   "description":"my-role-desc",
   "permissions":{  
      "access":[   ],
      "manage":[  ],
      "create":[   ],
      "view":[   ],
      "crossAccountAccess":[    ]
   }
}

Code sample

curl -X POST https://api.dome9.com/v2/Role \
  --basic -u <key-id>:<key-secret> \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json'
  -d '{
 "name":"new-name",
 "description":"my-role-desc",
 "permissions": {
 "access": [],
 "manage": [],
 "create": [],
 "view": [],
 "crossAccountAccess": []
 }
}'

 

Add permissions to the role

Construct the correct permissions object

The most relevant permissions are manage and view. Note that manage also includes the view permission so there is no need to add duplicates.

The resolution for our use-case will be either all accounts or a specific AWS account(s). You can also assign permissions to an Organizational Unit (a group of cloud accounts).

Permission for specific AWS accounts

In the (manage/view) property we'll construct an array of the form: 1|<Dome9 Cloud Account Id>

Example - permissions object for managing 2 AWS accounts:

"permissions": {
            "access": [],
            "manage": [
                "1|aaaaaaaaa-48b8-4f64-baa5-b70901fe56db",
                "1|bbbbbbbbb-48b8-4f64-baa5-b70901fe56db"
            ],
            "create": [],
            "view": [],
            "crossAccountAccess": []
        }

Note: "1" is the code for AWS.  For Azure, use "7", and for GCP, "8". For Organizational Units (groups of accounts), use "12". The value after "|" is the Dome9 id for the account (or Org Unit, see below, for details how to obtain this).

Permission for ALL resources (AWS account, Azure ,GCP and any other asset/policy)

In the (manage/view) property we'll add an entry with an empty string, which represents a 'catch all' filter.

Example - permissions object for viewing ALL AWSaccounts:

"permissions": {
            "access": [],
            "manage": [],
            "create": [],
            "view": [
                ""
            ],
            "crossAccountAccess": []
        }
``

Determine the Dome9 account id from the AWS account number

The permissions array in the request block for updating (post) roles requires the internal Dome9 account id. To obtain this, we will use the cloudaccounts resource to resolve the AWS account number to the Dome9 ID.

Request

GET https://api.dome9.com/v2/CloudAccounts

Response

The response shows details for the Dome9 account. The id field in the response is the internal Dome9 account id.

[  
   {  
      "id":"6*******-a***-4***-b***-c**********a",
      "vendor":"aws",
      "name":"AWS-1",
      "externalAccountNumber":"***********9",
      "error":null,
      "creationDate":"2018-08-27T12:58:25.443Z",
      "credentials":{      ...    },
      "iamSafe":null,
      "netSec":{  ...
      },
      "magellan":false,
      "fullProtection":false,
      "allowReadOnly":false
   }
]

Code sample

curl -X GET https://api.dome9.com/v2/CloudAccounts/ \
  --basic -u <key-id>:<key-secret> \
  -H 'Accept: application/json'


In a similar way, you can use GET https://api.dome9.com/v2/OrganizationalUnit to obtain a list of all Org Units,

and their ids.

Update a role with permissions

To add permissions to a role, we will put into the right resource id the new role object.

In this example we'll add a permission to manage a single AWS account, but we could make any permissions modification, such as removing old permissions or adding new permissions.

Notes:

  • This will overwrite the entire entity, so, if you wish to perform a partial update, make sure to get it first, apply your modification to the entire list, and then put the new state
  • Please review the resource URL that we are putting into (containing the role ID)

Request

PUT https://api.dome9.com/v2/Role/94761

{
	"id": 94761,
	"name":"new-role",
	"description":"auto-desc",
	"permissions": {
            "access": [],
            "manage": [
                "1|6*******-a***-4***-b***-c**********a"
            ],
            "create": [],
            "view": [],
            "crossAccountAccess": []
        }
}

Response

The response confirms the addition of the 'manage' permission to the role. 

{  
   "id":94761,
   "name":"new-role",
   "description":"auto-desc",
   "permissions":{  
      "access":[ ],
      "manage":[  
         "1|6*******-a***-4***-b***-c**********a"
      ],
      "create":[ ],
      "view":[ ],
      "crossAccountAccess":[ ]
   }
}

Code sample

curl -X GET https://api.dome9.com/v2/CloudAccounts/94761 \
  --basic -u <key-id>:<key-secret> \
  -H 'Accept: application/json'
  -d '{  
   "id":94761,
   "name":"new-role",
   "description":"auto-desc",
   "permissions":{  
      "access":[ ],
      "manage":[  
         "1|6*******-a***-4***-b***-c**********a"
      ],
      "create":[ ],
      "view":[ ],
      "crossAccountAccess":[ ]
   }
}'

Delete a role

Delete a role by sending the delete http request to the relevant resource id.

Request

DELETE https://api.dome9.com/v2/Role/94761

Response

204

Give us Feedback
Please rate this document
[1=Worst,5=Best]
Comment