# eb-security

Part of **EB**

# EventBridge Security

## Capabilities Overview

| Sub-capability | Calling Mode | Description |
|----------------|--------------|-------------|
| Authenticate API Request | Synchronous | Implement signature mechanism for API request authentication. |
| Manage EventBridge Resources | Synchronous | Configure RAM policies for EventBridge resource management. |
| Monitor KMS Events | Synchronous | Monitor Key Management Service events. |

## API Calling Patterns

### Authentication
The primary authentication method for EventBridge APIs is **HMAC-SHA1 signature-based authentication** using AccessKey credentials.

- Include the `Authorization` header in the format:  
  `Authorization: acs <AccessKeyId>:<Signature>`
- Set required signature headers:
  - `x-acs-signature-method: HMAC-SHA1`
  - `x-acs-signature-version: 1.0`
  - `x-acs-signature-nonce: <unique_random_string>`
  - `Date: <GMT_timestamp>`
- Use environment variables to store credentials securely:
  - `ALIBABA_CLOUD_ACCESS_KEY_ID`
  - `ALIBABA_CLOUD_ACCESS_KEY_SECRET`

> **Note**: While some documentation references bearer tokens, the canonical and required method for EventBridge API calls is HMAC signature authentication as defined in the "Request signatures" guide.

### Service Endpoint
EventBridge APIs use region-specific endpoints with the following pattern:

```text
https://eventbridge.<region>.aliyuncs.com
```

Common regions include:
- `cn-hangzhou`
- `cn-shanghai`
- `cn-beijing`

The exact endpoint depends on the region where your EventBridge resources are deployed.

### Synchronous API Pattern
All documented security-related operations in EventBridge use a synchronous request-response pattern:

1. Construct the HTTP request with all required headers (including signature headers).
2. Compute the signature using HMAC-SHA1 over the canonicalized request string.
3. Send the signed request to the appropriate regional endpoint.
4. Receive an immediate JSON or XML response (based on the `Accept` header).

No asynchronous polling or streaming is used for these security functions.

## Parameter Reference

### Authenticate API Request

| Parameter | Type | Required | Default | Constraints | Description |
|----------|------|----------|---------|-------------|-------------|
| Authorization | string | true | — | Format: `acs AccessKeyId:Signature` | The authorization header containing the AccessKey ID and signature. |
| Accept | string | false | application/json | One of: `application/json`, `application/xml` | The format of the return value. |
| Content-MD5 | string | false | — | Base64-encoded 128-bit MD5 hash | The Base64-encoded MD5 hash of the HTTP message body. |
| Content-Type | string | false | application/x-www-form-urlencoded;charset=utf-8 | — | The content type of the HTTP request as defined in RFC 2616. |
| Date | string | true | — | Format: `Wed, 05 Sep 2012 23:00:00 GMT` | The time in GMT as specified in the HTTP 1.1 protocol. |
| x-acs-signature-nonce | string | true | — | Unique per request | A unique random number used to prevent network replay attacks. |
| x-acs-signature-method | string | true | HMAC-SHA1 | Must be `HMAC-SHA1` | The signature algorithm. |
| x-acs-signature-version | string | true | 1.0 | Must be `1.0` | The signature version. |
| x-eventbridge-version | string | true | — | — | The API version number (e.g., `2020-04-01`). |

## Code Examples

### API Request with HMAC Signature - HTTP - All Regions

```http
POST /stacks?name=test_alert&status=COMPLETE HTTP/1.1
Host: eventbridge.cn-hangzhou.aliyuncs.com
Accept: application/json
Content-MD5: ChDfdfwC+Tn87******w7Q==
Content-Type: application/x-www-form-urlencoded;charset=utf-8
Date: Thu, 22 Feb 2018 07:46:12 GMT 
x-acs-signature-nonce: 550e8400-e29b-41d4-a716-44665544****
x-acs-signature-method: HMAC-SHA1
x-acs-signature-version: 1.0
x-eventbridge-version: 2020-04-01
Authorization: acs AccessKeyId:Signature
```

### Event Bus Management Policy - JSON - All Regions

```json
{
    "Statement":[
        {
            "Effect":"Allow",
            "Action":[
                "eventbridge:CreateEventBus",
                "eventbridge:GetEventBus",
                "eventbridge:DeleteEventBus",
                "eventbridge:ListEventBuses"
            ],
            "Resource":"acs:eventbridge:*:*:eventbus/*"
        }
    ],
    "Version":"1"
}
```

### Event Streaming Management Policy - JSON - All Regions

```json
{
    "Version": "1",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "eventbridge:CreateEventStreaming",
                "eventbridge:StartEventStreaming",
                "eventbridge:GetEventStreaming",
                "eventbridge:DeleteEventStreaming",
                "eventbridge:ListEventStreamings",
                "eventbridge:UpdateEventStreaming",
                "eventbridge:PauseEventStreaming"
            ],
            "Resource": "acs:eventbridge:*:*:eventstreaming/*"
        }
    ]
}
```

### Python Signature Helper (Conceptual) - Python - All Regions

```python
import hmac
import hashlib
import base64
import uuid
from datetime import datetime

def build_authorization_header(access_key_id, access_key_secret, http_method, headers, resource_path):
    # Construct StringToSign (simplified)
    date = headers.get('Date')
    content_md5 = headers.get('Content-MD5', '')
    content_type = headers.get('Content-Type', '')
    
    string_to_sign = f"{http_method}\n{content_md5}\n{content_type}\n{date}\n"
    
    # Add canonicalized headers and resource
    # (Full implementation requires canonicalization logic per docs)
    
    signature = base64.b64encode(
        hmac.new(
            access_key_secret.encode('utf-8'),
            string_to_sign.encode('utf-8'),
            hashlib.sha1
        ).digest()
    ).decode('utf-8')
    
    return f"acs {access_key_id}:{signature}"
```

## Error Handling

| Error Code | Description | Recommended Action |
|------------|-------------|---------------------|
| 403 | Access denied due to invalid or missing signature. Verify that the Authorization header is correctly formatted and the AccessKey secret matches. | Recompute the signature ensuring correct canonicalization of headers and resource path. Validate AccessKey secret. |
| 400 | Bad request due to malformed signature or incorrect parameter formatting. Check the StringToSign construction and canonicalization steps. | Review the signature generation process against the official documentation. Ensure all required headers are included in the canonical string. |
| 401 | Unauthorized access. Ensure the AccessKey ID is valid and not expired. | Confirm the AccessKey ID exists and is active in the Alibaba Cloud console. Check account status and permissions. |

## FAQ

Q: How do I generate the HMAC-SHA1 signature for EventBridge API requests?
A: You must construct a canonicalized string from the HTTP method, headers (Content-MD5, Content-Type, Date), and resource path, then sign it using your AccessKey secret with HMAC-SHA1. The resulting signature is base64-encoded and placed in the Authorization header.

Q: Can I use RAM roles instead of AccessKeys for programmatic access?
A: Yes, you can assume a RAM role that has the necessary EventBridge permissions and use the temporary security token (STS) to sign requests. The signing process remains the same, but you use the temporary AccessKey and secret from the STS response.

Q: What permissions are needed to manage EventBridge resources?
A: You need RAM policies that grant specific actions like `eventbridge:CreateEventBus` or `eventbridge:ListEventStreamings` on the appropriate resource ARNs (e.g., `acs:eventbridge:*:*:eventbus/*`). Use the provided policy examples as templates.

Q: Are KMS events automatically sent to EventBridge?
A: Yes, KMS publishes events for API calls, console operations, secret rotations, and configuration changes to EventBridge by default. You can create rules to route these events to targets for monitoring or automation.

Q: Is there a way to test my signature without making real API calls?
A: While there's no dedicated sandbox, you can use the `GetService` or `ListEventBuses` APIs (which have minimal side effects) to validate your signature implementation. A successful 200 response confirms correct authentication.

## Pricing & Billing

### Billing Model
Billing is based on **per-request** usage for API calls and **per-event** for event publishing.

### Price Reference

| Tier | Input Price | Output Price | Other Fees |
|------|-------------|--------------|-----------|
| default | 0.001 / | 0.001 / | — |
| KMS events | |

### Free Tier
- EventBridge API calls: 100 free requests per month
- KMS event publishing: 1000 free events per month

### Usage Limits
- EventBridge API: 100 QPS
- KMS events: 100 events per second per account

### Billing Notes
- All operations (including queries and deletions) count toward API request billing.
- RAM policy creation and management are free; only EventBridge service usage incurs costs.
- Event publishing fees apply only to the act of sending events to EventBridge, not to downstream processing.