Skip to content

Commit 684dcd4

Browse files
arielb135arielb135
committed
Add README.md for JIT AWS Integration Automation module with detailed features, integration types, prerequisites, examples, and error handling.
1 parent 4f9e4ea commit 684dcd4

1 file changed

Lines changed: 242 additions & 0 deletions

File tree

  • src/integrations/aws_integration_automation

‎src/integrations/aws_integration_automation/README.md‎

Lines changed: 242 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,242 @@
1+
# JIT AWS Integration Automation
2+
3+
A Terraform module for automating AWS integration with JIT (Just-in-Time) security platform. This module supports both single AWS account and AWS Organization-wide integrations.
4+
5+
## Features
6+
7+
- **Dual Integration Types**: Support for both single account and organization-wide deployments
8+
- **Native Terraform**: Pure Terraform implementation using `data "http"` resources
9+
- **Create-Only State Token**: Implements proper create-only behavior for JIT oauth/state-token using Terraform state
10+
- **Multi-Region Support**: Monitor multiple AWS regions simultaneously
11+
- **US/EU API Support**: Compatible with both US and EU JIT API endpoints
12+
- **Error Handling**: Built-in validation and error handling with postconditions
13+
- **State Management**: Pure Terraform state management without local file dependencies
14+
15+
## Integration Types
16+
17+
### Single Account Integration
18+
Deploys JIT integration to a single AWS account using CloudFormation stack.
19+
20+
### Organization Integration
21+
Deploys JIT integration across an entire AWS Organization using CloudFormation StackSet, automatically including all current and future accounts in the organization.
22+
23+
## Prerequisites
24+
25+
1. **JIT API Credentials**: Client ID and Secret from JIT platform
26+
2. **AWS Permissions**: Appropriate AWS permissions for CloudFormation operations
27+
3. **Terraform**: Version 1.5 or higher
28+
4. **For Organization Integration**: AWS Organizations service must be enabled
29+
30+
## Quick Start
31+
32+
### Single Account Integration
33+
34+
```hcl
35+
module "jit_aws_integration" {
36+
source = "path/to/aws_integration_automation"
37+
38+
# JIT Configuration
39+
jit_client_id = var.jit_client_id
40+
jit_secret = var.jit_secret
41+
jit_region = "us"
42+
43+
# Integration Type
44+
integration_type = "account"
45+
46+
# AWS Regions to Monitor
47+
aws_regions_to_monitor = ["us-east-1", "us-west-2"]
48+
49+
# Optional Configuration
50+
stack_name = "JitAccountIntegration"
51+
account_name = "Production Account"
52+
resource_name_prefix = "JitProd"
53+
54+
tags = {
55+
Environment = "production"
56+
Owner = "security-team"
57+
}
58+
}
59+
```
60+
61+
### Organization Integration
62+
63+
```hcl
64+
module "jit_aws_org_integration" {
65+
source = "path/to/aws_integration_automation"
66+
67+
# JIT Configuration
68+
jit_client_id = var.jit_client_id
69+
jit_secret = var.jit_secret
70+
jit_region = "us"
71+
72+
# Integration Type
73+
integration_type = "org"
74+
75+
# Organization Configuration
76+
organization_root_id = "r-xxxxxxxxxxxx"
77+
should_include_root_account = true
78+
79+
# AWS Regions to Monitor
80+
aws_regions_to_monitor = ["us-east-1", "us-west-2", "eu-west-1"]
81+
82+
# Optional Configuration
83+
resource_name_prefix = "JitOrg"
84+
}
85+
```
86+
87+
## Input Variables
88+
89+
| Name | Description | Type | Default | Required |
90+
|------|-------------|------|---------|:--------:|
91+
| `jit_client_id` | Client ID for Jit API authentication | `string` | n/a | yes |
92+
| `jit_secret` | Secret for Jit API authentication | `string` | n/a | yes |
93+
| `integration_type` | Type of AWS integration (`account` or `org`) | `string` | n/a | yes |
94+
| `jit_region` | Jit API region (`us` or `eu`) | `string` | `"us"` | no |
95+
| `aws_regions_to_monitor` | List of AWS regions to monitor | `list(string)` | `["us-east-1"]` | no |
96+
| `stack_name` | Name for the CloudFormation stack or stackset | `string` | `"JitIntegrationStack"` | no |
97+
| `account_name` | Optional account name alias for Jit platform | `string` | `""` | no |
98+
| `resource_name_prefix` | Prefix for CloudFormation resources | `string` | `null` (auto: "Jit" for account, "JitOrg" for org) | no |
99+
| `organization_root_id` | AWS Organization Root ID (required for org type) | `string` | `""` | no |
100+
| `should_include_root_account` | Include root account in organization integration | `bool` | `false` | no |
101+
| `capabilities` | CloudFormation capabilities required | `list(string)` | `["CAPABILITY_NAMED_IAM"]` | no |
102+
| `tags` | Tags to apply to CloudFormation resources | `map(string)` | `{}` | no |
103+
104+
## Outputs
105+
106+
| Name | Description |
107+
|------|-------------|
108+
| `integration_type` | Type of integration deployed |
109+
| `jit_api_endpoint` | JIT API endpoint used |
110+
| `cloudformation_template_url` | CloudFormation template URL used |
111+
| `stack_name` | CloudFormation stack/stackset name |
112+
| `account_name` | Account name alias used in Jit platform |
113+
| `resource_name_prefix` | Prefix used for CloudFormation resources |
114+
| `aws_regions_monitored` | List of AWS regions being monitored |
115+
| `cloudformation_stack_id` | Stack ID (account integration only) |
116+
| `cloudformation_stack_arn` | Stack ARN (account integration only) |
117+
| `cloudformation_stackset_id` | StackSet ID (organization integration only) |
118+
| `cloudformation_stackset_arn` | StackSet ARN (organization integration only) |
119+
| `organization_root_id` | Organization Root ID (organization integration only) |
120+
| `state_token_created` | Whether a new state token was created |
121+
| `state_token_flag_created` | Whether state token flag is initialized in Terraform state |
122+
| `state_token_stored` | Whether state token is stored in Terraform state |
123+
124+
## State Token Management
125+
126+
This module implements a **create-only** behavior for the JIT oauth/state-token endpoint using Terraform state management:
127+
128+
1. **First Run**: Creates a new state token and stores it in Terraform state using `terraform_data` resource
129+
2. **Subsequent Runs**: Reuses the existing state token from Terraform state
130+
3. **No Updates**: The state token is never updated or regenerated unless the Terraform state is manually modified
131+
132+
### State Token Implementation
133+
134+
The module uses three key resources for state token management:
135+
136+
- `terraform_data.state_token_flag`: Tracks whether a token has been created
137+
- `data.http.jit_state_token`: Only executes when the flag indicates first creation
138+
- `terraform_data.state_token_storage`: Stores the actual token value in Terraform state
139+
140+
### Important Notes
141+
142+
- State token is managed entirely within Terraform state - no local files required
143+
- Token persists across Terraform runs and is only created once
144+
- To regenerate a state token, you must manually modify or destroy the relevant Terraform state resources
145+
146+
## CloudFormation Templates
147+
148+
The module automatically selects the appropriate CloudFormation template:
149+
150+
- **Account Integration**: `https://jit-aws-prod.s3.amazonaws.com/jit_aws_integration_stack.json`
151+
- **Organization Integration**: `https://jit-aws-prod.s3.amazonaws.com/jit_aws_org_integration_stack.json`
152+
153+
## Resource Name Prefix
154+
155+
The `resource_name_prefix` parameter controls the prefix used for CloudFormation resources:
156+
157+
- **Default for Account Integration**: "Jit"
158+
- **Default for Organization Integration**: "JitOrg"
159+
- **Custom Prefix**: Provide your own prefix (1-40 characters, alphanumeric, hyphens, underscores only)
160+
161+
## API Endpoints
162+
163+
The module supports both JIT API regions:
164+
165+
- **US Region**: `https://api.jit.io` (default)
166+
- **EU Region**: `https://api.eu.jit.io`
167+
168+
## Error Handling
169+
170+
The module includes comprehensive error handling:
171+
172+
- **Authentication Validation**: Ensures JIT API authentication succeeds
173+
- **State Token Validation**: Verifies state token creation
174+
- **Input Validation**: Validates required parameters and formats
175+
- **Lifecycle Management**: Prevents accidental destruction of resources
176+
177+
## Examples
178+
179+
See the `examples/` directory for complete working examples:
180+
181+
- [`examples/account_integration.tf`](examples/account_integration.tf) - Single account integration
182+
- [`examples/organization_integration.tf`](examples/organization_integration.tf) - Organization integration
183+
184+
## Security Considerations
185+
186+
1. **Sensitive Variables**: `jit_client_id` and `jit_secret` are marked as sensitive
187+
2. **State Files**: Ensure Terraform state files are stored securely (e.g., S3 with encryption)
188+
3. **State Token**: Stored in Terraform state - secure your state backend appropriately
189+
4. **IAM Permissions**: Follow principle of least privilege for AWS IAM permissions
190+
191+
## Troubleshooting
192+
193+
### Common Issues
194+
195+
1. **Authentication Failure**
196+
- Verify JIT client ID and secret are correct
197+
- Check if the correct JIT region is specified
198+
199+
2. **Organization Root ID Error**
200+
- Ensure the organization root ID is in the correct format (`r-xxxxxxxxxxxx`)
201+
- Verify AWS Organizations is enabled and accessible
202+
203+
3. **State Token Issues**
204+
- Check Terraform state for `terraform_data.state_token_storage` resource
205+
- Use `terraform state show` to inspect state token resources
206+
207+
4. **CloudFormation Failures**
208+
- Verify AWS permissions for CloudFormation operations
209+
- Check CloudFormation events in the AWS console for detailed error messages
210+
211+
5. **Parameter Validation Errors**
212+
- Verify `resource_name_prefix` meets length and character requirements
213+
- Check that `organization_root_id` follows the correct pattern for org integration
214+
215+
### Debug Information
216+
217+
Enable Terraform debug logging for detailed troubleshooting:
218+
219+
```bash
220+
export TF_LOG=DEBUG
221+
terraform apply
222+
```
223+
224+
## Requirements
225+
226+
| Name | Version |
227+
|------|---------|
228+
| terraform | >= 1.5 |
229+
| aws | >= 5.0 |
230+
| http | >= 3.0 |
231+
| local | >= 2.0 |
232+
233+
## Contributing
234+
235+
1. Follow existing code patterns and documentation standards
236+
2. Test changes with both integration types
237+
3. Update examples and documentation as needed
238+
4. Ensure all variables have proper validation where applicable
239+
240+
## License
241+
242+
This module is part of the JIT customer scripts repository. Please refer to the main repository license for usage terms.

0 commit comments

Comments
 (0)