Enable Programmatic Access

1. Enable programmatic access.

   • Select Tenant in the Cloud NGFW Tenant console.
   • Under General, click the Programmatic Access slider.
   • Click Enable to confirm.

2. Create a new role with custom trust policy.

   The following is an example of a custom trust policy:

   {
     "Version": "2012-10-17",
     "Statement": [
       {
         "Effect": "Allow",
         "Principal": {
           "AWS": "arn:aws:iam::111122223333:root"
         },
         "Action": "sts:AssumeRole"
       }
     ]
   }
   

   The trust relation example noted above with principal root could provide access to more principals than intended. The Principal and Condition elements can be used to restrict access to the role for specific principals. For more information, see How to use trust policies with IAM roles. You can also create this role in one AWS account and delegate specific permissions to another account using cross-account access. To define a trust policy with cross-account access, see the examples provided here.
3. Add the Amazon APIGatewayInvokeFullAccess permission policy to invoke APIs. Click here for more information.
4. Add the following tags (consisting of a key and value) to the IAM role to provide permission policies as needed.

   Usage	TagKey	TagValue
   Create and manage firewalls	CloudNGFWFirewallAdmin	Yes
   Create and manage local rulestacks	CloudNGFWRulestackAdmin	Yes
   Create and manage global rulestacks	CloudNGFWGlobalRulestackAdmin	Yes
   Onboard AWS account	CloudNGFWAccountAdmin	Yes

   You can assign multiple tags to the same role. These tags can be used to access different Cloud NGFW programmatic access role tokens.
5. (Skip steps 7-9 if you choose to use the Cloud NGFW programmatic access examples) Use the examples in the API and CFT folders under the Git repository to access programmatic access tool and CFTs respectively.

   Download the entire programmatic_access directory to run examples provided by Palo Alto Networks.

   The tool internally assumes the role and generates access key and secret key for your role, and generates a SigV4 header. It also calls the specific endpoint role to get programmatic access token for Cloud NGFW.
6. Assume roles with the tag key-pair values mentioned in step 5 as needed using the AWS CLI.

   $ aws sts assume-role --role-arn arn:aws:iam::<AWS-ACCOUNT-ID>:role/<ROLE-NAME> --profile <AWS-PROFILE-TO-ASSUME> --role-session-name <SESSION-NAME>
   
   {
    "Credentials": {
     "AccessKeyId": "<ACCESS-KEY>",
     "SecretAccessKey": "<SECRET-ACCESS-KEY>",
     "SessionToken": "<SESSION-TOKEN>",
     "Expiration": "<CREDENTIALS-EXPIRATION>"
    },
    "AssumedRoleUser": {
     "AssumedRoleId": "<ROLE-ID>:<SESSION-NAME>",
     "Arn": "arn:aws:iam::<AWS-ACCOUNT-ID>:role/<ROLE-NAME>/<SESSION-NAME>"
    }
   }

   When you assume the role, a temporary access key and secret key are generated for your account. For more information, see assume roles that have a specific tag.
7. Generate the SigV4 (signature version 4) header using the temporary credentials obtained in step 7. For more information, see signing AWS requests with SigV4.

   The following is an example of an AWS SigV4 signed header.

   AWS4-HMAC-SHA256 Credential=<ACCESS-KEY>/20220421/<REGION>/execute-api/aws4_request, SignedHeaders=host;x-amz-date;x-amz-security-token, Signature=<SIGNATURE>

8. Generate SubcriptionKey and TokenID.

   To access Cloud NGFW using REST APIs, use this path before the API call—api.<region-name>.aws.cloudngfw.paloaltonetworks.com. For more information, see API documentation.

   • For cloud firewall admin role—GET https://api.<region-name>.aws.cloudngfw.paloaltonetworks.com/v1/mgmt/tokens/cloudfirewalladmin
   • For cloud rulestack admin role—GET https://api.<region-name>.aws.cloudngfw.paloaltonetworks.com/v1/mgmt/tokens/cloudrulestackadmin
   • For cloud global rulestack admin role—GET https://api.<region-name>.aws.cloudngfw.paloaltonetworks.com/v1/mgmt/tokens/cloudglobalrulestackadmin

   Get a Token

   Following is an example of the cURL command to get token.

   $ curl --location --request GET 'https://api.us-east-1.aws.cloudngfw.paloaltonetworks.com/v1/mgmt/tokens/cloudfirewalladmin' \
   > --header 'X-Amz-Security-Token: <SESSION-TOKEN>' \
   > --header 'X-Amz-Date: <CREDENTIALS-EXPIRATION-AMZ-DATE-FORMAT>' \
   > --header 'Authorization: <AWS-V4-SIGNED-HEADER>'

   Response

   {"Response": {"TokenId": "<CLOUD-NGFW-PROGRAMMATIC-ACCESS-TOKEN>", "SubscriptionKey": "<SUBSCRIPTION-KEY>", "ExpiryTime": 30, "Enabled": true}, "ResponseStatus": {"ErrorCode": 0}}

9. Add the response data to the Header section in the Cloud NGFW console.

   Header	Value
   Authorization	<TokenID>
   x-api-key	<SubscriptionKey>

   The following is a sample Cloud NGFW API call.

   curl --location --request GET 'https://api.us-east-1.aws.cloudngfw.paloaltonetworks.com/v1/config/rulestacks/rs-1' \
   > --header 'Authorization: <CLOUD-NGFW-PROGRAMMATIC-ACCESS-TOKEN>' \
   > --data-raw ''

   Response

   {"Response": {"RuleStackName": "rs-1", "RuleStackCandidate": {"Scope": "Local", "MinAppIdVersion": "8433-6838", "Profiles": {"AntiSpywareProfile": "BestPractice", "AntiVirusProfile": "BestPractice", "VulnerabilityProfile": "BestPractice", "URLFilteringProfile": "None", "FileBlockingProfile": "BestPractice"}, "UpdateToken": "1"}, "RuleStackState": "Uncommitted"}, "ResponseStatus": {"ErrorCode": 0}}

10. To revoke programmatic access, use the Access Key, Secret Key, and Subscription Key to call the Token API—DELETE https://:<region-name>.aws.cloudngfw.paloaltonetworks.comv1/mgmt/tokens/{TokenID}.

    Access Key and Secret Key are temporary. Generate new Access Key and Secret Key if they expire.