Configuring assume-role access to AWS API

PrivX Authentication to AWS Services via assume-role

This first example tells you how to configure PrivX to fetch temporary AWS API credentials via assume-role. Assume role credential validity period can be configured between 15 minutes and 12 hours (AWS restriction).

Values greater than 1 hour need to be configured in AWS target role settings:

Set up AWS users and roles for delegating AWS-service permissions, then grant these roles to PrivX users:

1. In your AWS management interface, create an IAM user for obtaining AWS roles.
   Provide the IAM user with the following permission policies:

   {
       "Version": "2012-10-17",
       "Statement": [
           {
               "Effect": "Allow",
               "Action": "sts:AssumeRole",
               "Resource": [ "*" ]
           }
       ]
   }

   You can further restrict the access by defining the target account role ARN as allowed resource:
   "Resource": [ "arn:aws:iam::****:role/****" ]

   PrivX uses this AWS user to import and delegate AWS roles. For this reason you must also create Security Credentials/Access Keys for the user. Copy the Access Key ID and the Secret Access Key of the user, which are required later for configuring PrivX AWS Directory.

2. In your AWS management interface, create AWS role(s) that grant access to AWS services. This role does not need to be in the same AWS account, it can also belong to a third party.
   The AWS role(s) should have permissions like the following (replace the example Actions with services and actions this role should allow access to).:

   {
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "ec2:Describe*",
                "iam:ListRoles"
            ],
            "Resource": [
                "*"
            ]
        }
    ]
   }

   ec2:Describe* -IAM permissions are required for AWS host scanning.
   iam:ListRoles -permission is required by PrivX for role federation, for fetching a list of AWS roles for administrator to map PrivX roles against.

Also set the trust relationships of the AWS role similar to the following (replace <iam_user_arn> with the ARN of the previously-created IAM user):

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "AWS": "<iam_user_arn>"
            },
            "Action": "sts:AssumeRole",
            "Condition": {}
        }
    ]
}

This allows PrivX AWS user to take control of this role to do host scanning or to get AWS API temporary credentials.

For additional security, you can also configure an External ID requirement for your trust policy, restricting assume-role access to PrivX AWS directory and PrivX user(s) using the AWS API:

{
"Version": "2012-10-17",
"Statement": [
 {
   "Effect": "Allow",
   "Principal": {
     "AWS": "<privx_iam_user_arn>"
   },
    "Action": "sts:AssumeRole",
    "Condition": {
      "StringEquals": {
         "sts:ExternalId": [ 
             "yourExternalIdInPrivXDirectoryConfig", "yourPrivXUserPrincipalUsingAWSAPI" 
         ]
      }
    }
 }
]
}

"yourExternalIdInPrivXDirectoryConfig" is the value of ExternalID setting, defined in your PrivX directory configuration. This external ID would be used when PrivX is doing AWS host discovery or fetching a list of AWS roles.
"yourPrivXUserPrincipalUsingAWSAPI" is the Principal name of the user, who is fetching temporary credentials for accessing AWS API.
If accessing AWS API via AWS CLI using PrivX Agent, this would be the user Principal name of your PrivX user, for example "john.doe@yourcompany.com" for AD accounts.
If using scripted access, this would be the API Client principal name in PrivX users listing, for example "27981ef9-68b3-4e75-4fc6-5181fbd2da38".

You can also grant the assume-role permissions via Create role wizard in AWS console,. although you need to modify the settings afterwards to include more externalIDs:

Configuring PrivX AWS directory to use role federation

1. On the Settings→Directories page of the PrivX GUI, add a directory of the type Amazon Web Services. Provide the Access key ID and Secret Access Key of the previously-created IAM user.

   Also under Advanced AWS settings, select Enable AWS Role Federation. If you only want to import roles under a certain path, set this path to AWS Role Path Prefix for Federated Roles.
   Optionally, you can use AWS Role name filter to identify the roles you want to give PrivX an access. Wildcards are allowed.

   Save the directory configuration. To verify that roles were imported successfully, ensure that the previously-configured AWS roles are visible on the page Settings→Deployment→Configure Amazon Web Service role grants.

2. Grant AWS roles to PrivX roles. To do this, go to the page Settings→Deployment→Configure Amazon Web Service role grants, and Edit the AWS roles. PrivX users belonging to specified roles can now gain access according to any AWS roles granted to them.