AWS waf: Add connected account settlement docs and IAM permission requirements
Summary
Documents a new AI traffic monetization option for settling payments through a connected account with a third-party payment provider (Stripe) instead of self-managed crypto wallets. Adds the ConnectedAccountConfigs configuration schema and examples, prerequisites, validation rules and error codes, a new 'Settling payments with a connected account' section, a connected-account support column in the supported networks table, and notes that TEST mode is unsupported for connected accounts. Also reorders the quick-start steps (create protection pack before enabling Bot Control) and clarifies CurrencyMode TEST support.
Security assessment
The added content is feature documentation for payment settlement via connected accounts, not a fix for a vulnerability or incident. It does, however, document an authorization requirement: callers must hold the `payments:GetConnectedAccount` IAM permission on the connected account ARN, and the service enforces it by returning AccessDeniedException, plus validation errors (WAFInvalidOperationException, WAFNonexistentItemException, WAFInvalidParameterException) when the account is inactive or the partition is unsupported. This is security-relevant IAM/least-privilege guidance and operational hardening for a payment-related integration, hence medium severity rather than high.
Evidence
* Permission to use that connected account. The IAM permissions for creating and managing connected accounts are on the billing side; for those actions, see [Managing connected accounts](https://docs.aws.amazon.com/awsaccountbilling/latest/aboutv2/manage-connected-accounts.html) in the AWS Billing and Cost Management User Guide. To reference a connected account in a web ACL or rule group, you need the `payments:GetConnectedAccount` permission on the connected account ARN. If you don't have this permission, the request fails with `AccessDeniedException`.
Diff
diff --git a/waf/latest/developerguide/waf-ai-traffic-monetization-getting-started.md b/waf/latest/developerguide/waf-ai-traffic-monetization-getting-started.md index 7420abc..8be3c27 100644 --- a//waf/latest/developerguide/waf-ai-traffic-monetization-getting-started.md +++ b//waf/latest/developerguide/waf-ai-traffic-monetization-getting-started.md @@ -7 +7 @@ -PrerequisitesQuick startMonetizationConfig structureSupported payment networksTest modeNext steps +PrerequisitesQuick startMonetizationConfig structureSettling payments with a connected accountSupported payment networksTest modeNext steps @@ -19 +19 @@ You can now use the updated experience to access AWS WAF functionality anywhere - * A [USDC wallet address on Base, Solana, or both to receive payments](https://www.coinbase.com/developer-platform/wallets). + * One of the following to receive payments: a [USDC wallet address on Base, Solana, or both](https://www.coinbase.com/developer-platform/wallets), or a connected account with a supported payment provider that is enabled for settlement. To set up a connected account, see [Managing connected accounts](https://docs.aws.amazon.com/awsaccountbilling/latest/aboutv2/manage-connected-accounts.html) in the AWS Billing and Cost Management User Guide. @@ -28 +28 @@ You can now use the updated experience to access AWS WAF functionality anywhere - 1. **Enable Bot Control** – If not already enabled, [add the AWS WAF Bot Control managed rule group to your web ACL](https://docs.aws.amazon.com/waf/latest/developerguide/waf-using-managed-rule-group.html). + 1. **Create a protection pack (webACL)** – In the AWS WAF console, navigate to Protection packs (webACL) and [create a new pack scoped to CloudFront](https://docs.aws.amazon.com/waf/latest/developerguide/web-acl-creating.html) with your pricing, bot and agent policies, and payment configuration. AI traffic monetization requires a web ACL with CloudFront (global) scope. [Associate with a CloudFront distribution](https://docs.aws.amazon.com/waf/latest/developerguide/cloudfront-features.html). @@ -30 +30 @@ You can now use the updated experience to access AWS WAF functionality anywhere - 2. **Create a protection pack (webACL)** – In the AWS WAF console, navigate to Protection packs (webACL) in the Cloudfront (Global) region, and [create a new pack](https://docs.aws.amazon.com/waf/latest/developerguide/web-acl-creating.html) with your pricing, bot and agent policies, and payment configuration. [Associate with a CloudFront distribution](https://docs.aws.amazon.com/waf/latest/developerguide/cloudfront-features.html). + 2. **Enable Bot Control** – If not already enabled, [add the AWS WAF Bot Control managed rule group to your web ACL](https://docs.aws.amazon.com/waf/latest/developerguide/waf-using-managed-rule-group.html). @@ -39 +39 @@ The MonetizationConfig contains: - * **CurrencyMode** – `REAL` for production payments or `TEST` for test network payments. + * **CurrencyMode** – `REAL` for production payments or `TEST` for test network payments. `TEST` is supported only with `CryptoConfig` (self-managed wallets); it is not supported with a connected account configuration. @@ -42,0 +43,2 @@ The MonetizationConfig contains: + * **ConnectedAccountConfigs** – Configuration for settling payments through a connected account with a third-party payment provider (such as Stripe), as an alternative to managing your own wallet addresses. You reference the connected account by its ARN and set per-network pricing. + @@ -81,0 +84,129 @@ The `Amount` is specified in USDC as a decimal string with up to 3 decimal place +A MonetizationConfig can also contain a `ConnectedAccountConfigs` entry, either on its own or alongside `CryptoConfig`. When you combine the two, a given chain (BASE or SOLANA) can be used by only one of them. The following example settles BASE payments to a self-managed wallet and SOLANA payments through a connected account: + + + { + "MonetizationConfig": { + "CryptoConfig": { + "PaymentNetworks": [ + { + "Chain": "BASE", + "WalletAddress": "0x1234567890abcdef1234567890abcdef12345678", + "Prices": [ + { + "Amount": "0.001", + "Currency": "USDC" + } + ] + } + ] + }, + "ConnectedAccountConfigs": [ + { + "ConnectedAccountArn": "arn:aws:payments::123456789012:connectedaccount/my-account-aB3d47", + "PaymentNetworks": [ + { + "Chain": "SOLANA", + "Prices": [ + { + "Amount": "0.01", + "Currency": "USDC" + } + ] + } + ] + } + ] + } + } + +## Settling payments with a connected account + +In addition to managing your own crypto wallet addresses, you can also settle payments through a connected account with a supported third-party payment provider (Stripe). A connected account is an account that you set up with a supported payment provider and reference in your MonetizationConfig by its ARN. When you use a connected account, the per-network deposit addresses are provisioned and managed on your behalf, so you don't configure or maintain wallet addresses yourself. You can set a `MonetizationConfig`, including a `ConnectedAccountConfigs` entry, on a web ACL or a rule group; the requirements and validation described in this section apply to both. Connected accounts are available only in the commercial AWS partition. In other partitions, the request fails with `WAFInvalidParameterException`. + +You create and manage connected accounts in the AWS Billing and Cost Management console, under **Payment preferences** , **Connected accounts**. For the full setup procedure, see [Managing connected accounts](https://docs.aws.amazon.com/awsaccountbilling/latest/aboutv2/manage-connected-accounts.html) in the AWS Billing and Cost Management User Guide. + +This differs from self-managed wallets, where you provide a wallet address for each payment network in your `CryptoConfig` and payments settle directly to those addresses. + +###### Prerequisites + +To settle payments with a connected account, you need the following: + + * An active connected account with a supported payment provider (Stripe) that is enabled for payment settlement. + + * Permission to use that connected account. The IAM permissions for creating and managing connected accounts are on the billing side; for those actions, see [Managing connected accounts](https://docs.aws.amazon.com/awsaccountbilling/latest/aboutv2/manage-connected-accounts.html) in the AWS Billing and Cost Management User Guide. To reference a connected account in a web ACL or rule group, you need the `payments:GetConnectedAccount` permission on the connected account ARN. If you don't have this permission, the request fails with `AccessDeniedException`. + + * The ARN of the connected account. You create the connected account and obtain its ARN in the AWS Billing and Cost Management console, under **Payment preferences** , **Connected accounts** – not from the payment provider directly. The ARN has the format `arn:aws:payments::<account-id>:connectedaccount/<name>-<id>`. + + + + +To use a connected account, configure `ConnectedAccountConfigs` in your MonetizationConfig. Reference your connected account by its ARN and set per-network pricing for each chain you accept. The following example shows a MonetizationConfig that settles payments through a connected account: + + + { + "MonetizationConfig": { + "ConnectedAccountConfigs": [ + { + "ConnectedAccountArn": "arn:aws:payments::123456789012:connectedaccount/my-account-aB3d47", + "PaymentNetworks": [ + { + "Chain": "BASE", + "Prices": [ + { + "Amount": "0.01", + "Currency": "USDC" + } + ] + }, + { + "Chain": "SOLANA", + "Prices": [ + { + "Amount": "0.01", + "Currency": "USDC" + } + ] + } + ] + } + ] + } + } + +###### Note + +Unlike a `CryptoConfig` entry, a `ConnectedAccountConfigs` entry does not include a `WalletAddress`. The deposit addresses for each payment network are provisioned for your connected account. + +The following rules apply when you use a connected account: + +###### Important + +`CurrencyMode` `TEST` is not supported with a connected account configuration. + + * Connected accounts support production settlement only. + + * The supported chains are BASE and SOLANA. + + * Prices for a connected account range from `0.01` to `999999.99` USDC, with up to 2 decimal places. Sub-cent amounts are not supported. This differs from self-managed wallets, which support amounts as small as 0.001 USDC. + + * You can configure one connected account. + + * You can use `CryptoConfig` and `ConnectedAccountConfigs` together on the same web ACL. However, a given chain (BASE or SOLANA) can be used by only one of them, not both. + + * AWS WAF validates the connected account on every web ACL or rule group create or update request that references it, not only when you change the connected account configuration. The account is usable only when both its account status is **Active** and its crypto settlement capability is **Enabled**. If validation fails, AWS WAF rejects the request with one of the following errors: + + * Account or crypto settlement capability not active – `WAFInvalidOperationException` + + * The ARN no longer exists because the account was deleted and recreated – `WAFNonexistentItemException` + + * You don't have the `payments:GetConnectedAccount` permission – `AccessDeniedException` + + * Invalid ARN or unsupported partition – `WAFInvalidParameterException` + +The rejection error is actionable – it tells you to reconnect the account, or to enable crypto settlement for it. + + * Before you create or update a web ACL or rule group that references a connected account, verify in the AWS Billing and Cost Management console, under **Payment preferences** , **Connected accounts** , that **Account status** is **Active** and **Crypto settlement** is **Enabled**. If the status is `Pending` or `Inactive`, choose **Actions** , **Resume linking** to reactivate it; if crypto settlement needs attention, resolve it with your payment provider (for Stripe, in the Stripe Dashboard). For details, see the "Checking account status and crypto settlement capability" guidance in [Managing connected accounts](https://docs.aws.amazon.com/awsaccountbilling/latest/aboutv2/manage-connected-accounts.html). + + + + @@ -84,6 +215,6 @@ The `Amount` is specified in USDC as a decimal string with up to 3 decimal place -Chain | Network | Currency | Use Case ----|---|---|--- -BASE | Base mainnet (EVM L2) | USDC | Production Payments -SOLANA | Solana mainnet | USDC | Production Payments -BASE_SEPOLIA | Base Sepolia testnet | USDC | Test Mode -SOLANA_DEVNET | Solana Devnet | USDC | Test Mode +Chain | Network | Currency | Use Case | Connected account support +---|---|---|---|--- +BASE | Base mainnet (EVM L2) | USDC | Production Payments | Yes +SOLANA | Solana mainnet | USDC | Production Payments | Yes +BASE_SEPOLIA | Base Sepolia testnet | USDC | Test Mode | No +SOLANA_DEVNET | Solana Devnet | USDC | Test Mode | No @@ -102,0 +234,4 @@ Set `CurrencyMode` to `TEST` in your MonetizationConfig and configure test netwo +###### Note + +Test mode is supported only with `CryptoConfig` (self-managed wallets). Connected account configurations do not support `TEST` mode; they support production settlement only. +