> Source: [sk147835](https://support.checkpoint.com/results/sk/sk147835) # sk147835 - Use the CloudGuard API to set up Account Roles and Permissions | Property | Value | |----------|-------| | Solution ID | sk147835 | | Date Created | 2019-02-24 | | Last Modified | 2023-03-28 | | Technical Level | General | | Products | Cloud Firewall | | Versions | R82.10, R81.20, R82 | ## Solution This article illustrates how to automate the configuration of roles and permissions for your CloudGuard account using the CloudGuard API. Resources used: * **Role** - this is used to add and update a new role to the CloudGuard account (see [Role](https://docs.cloudguard.dome9.com/reference/role)) * **CloudAccount** - this is used to obtain the CloudGuard account id (see [CloudAccounts](https://docs.cloudguard.dome9.com/reference/aws-cloud-account)) * **OrganizationalUnit** - this is used to obtain the CloudGuard id for an Org Unit (see [OrganizationalUnit](https://docs.cloudguard.dome9.com/reference/awsorganizations_getorganizations_get_v2awsorganizationorganizations)) Prerequisites ------------- * You need the API Key and Secret for your CloudGuard account. These are used as the username \& password to access your account with the API, using [Basic Authentication](https://docs.cloudguard.dome9.com/reference/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 : \ -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 : \ -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|` *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 CloudGuard 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 CloudGuard account id from the AWS account number --------------------------------------------------------------- The permissions array in the request block for updating (post) roles requires the internal CloudGuard account id. To obtain this, we will use the `cloudaccounts` resource to resolve the AWS account number to the CloudGuard ID. **Request** GET https://api.dome9.com/v2/CloudAccounts **Response** The response shows details for the CloudGuard account. The **id** field in the response is the internal CloudGuard 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 : \ -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 : \ -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 --- # Agent Instructions This content is from the Check Point Support Center (https://support.checkpoint.com), the official knowledge base for Check Point cybersecurity products. ## Navigating This Knowledge Base - **Complete index**: [llms.txt](https://support.checkpoint.com/llms.txt) - **All SK articles**: [SecureKnowledge Sitemap](https://support.checkpoint.com/sitemaps/secureknowledge-sitemap-index.xml) - **SK article URL pattern**: `https://support.checkpoint.com/results/sk/{skId}` - **Markdown responses**: AI bot User-Agents automatically receive `text/markdown` content