Use the Dome9 API to setup Roles and Permissions for an account

In this topic:

    This note 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)

    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).

    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 internal Dome9 prefix / code for AWS. There are other types of codes (e.g.: Azure, GCP) which are not covered here.

    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'

    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

    When we do not longer need a role we can delete it by sending delete http request to the relevant resource id.

    Request

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

    Response

    204