Skip to content

Add data flow diagram with trust boundaries - #22

Merged
mengesb merged 12 commits into
mainfrom
docs/data-flow-diagram
Jul 2, 2026
Merged

Add data flow diagram with trust boundaries#22
mengesb merged 12 commits into
mainfrom
docs/data-flow-diagram

Conversation

@mengesb

@mengesb mengesb commented Jul 2, 2026 •
edited
Loading

Copy link
Copy Markdown
Owner

Summary

  • Add a data flow sequence diagram showing temporal message flow between participants across 4 phases of the vault-iam-auth process
  • Shows actual data shapes at each step (IMDS fields, JSON payload structure, Vault API requests/responses, STS credential format)
  • Phases: Authentication (IMDS + SigV4), Vault Login, Credential Issuance, Resource Management

Files

File Purpose
docs/diagrams/data-flow.mmd Mermaid sequence diagram source
docs/diagrams/data-flow.png Rendered PNG

Test plan

  • Verify PNG renders correctly in GitHub PR view
  • Confirm data shapes and API paths match the implementation

mengesb added 3 commits July 2, 2026 09:37
@mengesb
Add data flow diagram with trust boundary annotations
a0a1ec5 
Shows credential data transformation through each stage (raw IAM creds
-> AWS Sig v4 signed request -> base64 JSON payload -> Vault token ->
temporary STS credentials) with trust boundary crossings highlighted.
Includes Mermaid source, draw.io XML, and rendered PNGs.
@mengesb
Replace flowchart with sequence diagram for data flow
51501f0 
Use a sequence diagram (matching HSTCertMon style) showing temporal
message flow between participants across 4 phases:
- Authentication Phase: IMDS credential retrieval + AWS Sig v4 signing
- Vault Login Phase: provider calls /v1/auth/aws/login, STS verifies
- Credential Issuance Phase: secrets engine generates JIT credentials
- Resource Management Phase: AWS provider uses temporary creds

Remove draw.io PNG render since sequence diagrams don't map well to
editable draw.io shapes. Mermaid source is the authoritative version.
@mengesb
Remove data-flow.drawio — Mermaid source is authoritative
3fbaf56
@mengesb
mengesb requested a review from Copilot July 2, 2026 16:47
Copilot AI reviewed Jul 2, 2026
View reviewed changes

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Adds a Mermaid sequence diagram documenting how credential material flows and transforms through the vault-iam-auth Terraform/Vault/AWS STS interaction, including trust boundary crossings.

Changes:

  • Introduces a new sequenceDiagram describing the auth/login and credential issuance phases.
  • Documents the data shapes at each step (metadata creds → signed request material → Vault token → STS temporary creds).

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Comment thread docs/diagrams/data-flow.mmd Outdated
Comment thread docs/diagrams/data-flow.mmd Outdated
Comment thread docs/diagrams/data-flow.mmd Outdated
@mengesb
Fix data flow diagram per review feedback
613e873 
- Use IMDS field name "Token" (not "SessionToken") to match metadata
  response and aws-credentials.sh parsing
- Fix SigV4 signing note to show correct key derivation chain:
  HMAC(AWS4+secret, date, region, sts, aws4_request)
- Add iam_http_request_method to /v1/auth/aws/login request body
@mengesb
mengesb requested a review from Copilot July 2, 2026 16:58
Copilot AI reviewed Jul 2, 2026
View reviewed changes

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 1 out of 2 changed files in this pull request and generated 3 comments.

Comment thread docs/diagrams/data-flow.mmd Outdated
Comment thread docs/diagrams/data-flow.mmd Outdated
Comment thread docs/diagrams/data-flow.mmd Outdated
@mengesb
Fix SigV4 note accuracy and use X-Vault-Token header
7451ce6 
- Rewrite SigV4 note to show the 4-step process matching aws4-sign.sh:
  canonical request, string-to-sign, derived signing key, signature
- Use X-Vault-Token header (not Authorization) to avoid confusion with
  the AWS SigV4 Authorization header
@mengesb
mengesb requested a review from Copilot July 2, 2026 17:05
Copilot AI reviewed Jul 2, 2026
View reviewed changes

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 1 out of 2 changed files in this pull request and generated 6 comments.

Comment thread docs/diagrams/data-flow.mmd Outdated
Comment thread docs/diagrams/data-flow.mmd Outdated
Comment thread docs/diagrams/data-flow.mmd Outdated
Comment thread docs/diagrams/data-flow.mmd Outdated
Comment thread docs/diagrams/data-flow.mmd Outdated
Comment thread docs/diagrams/data-flow.mmd Outdated
@mengesb
Address review feedback on data flow diagram
de31445 
- Add trust boundary box annotations (EC2 Instance, Vault, AWS)
- Use versioned IMDS path /2020-10-27/meta-data to match implementation
- Add Version=2011-06-15 to STS GetCallerIdentity request body
- Replace hvs.xxx with generic [vault_token] placeholder
- Note base64 encoding on login payload fields
@mengesb
mengesb requested a review from Copilot July 2, 2026 17:15
Copilot AI reviewed Jul 2, 2026
View reviewed changes

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 1 out of 2 changed files in this pull request and generated 4 comments.

Comment thread docs/diagrams/data-flow.mmd Outdated
Comment thread docs/diagrams/data-flow.mmd Outdated
Comment thread docs/diagrams/data-flow.mmd Outdated
Comment thread docs/diagrams/data-flow.mmd Outdated
@mengesb
Address review feedback on data flow diagram
15984b8 
- Remove duplicate participant declarations; define only within box groups
- Include X-Vault-AWS-IAM-Server-Id in SigV4 canonical request note
- Show both /v1/aws/creds/:role and /v1/aws/sts/:role endpoints
- Replace AWS STS target in Resource Management phase with Target AWS
  Services (EC2, S3, IAM, etc.) since STS is only for credential minting
@mengesb
mengesb requested a review from Copilot July 2, 2026 17:23
Copilot AI reviewed Jul 2, 2026
View reviewed changes

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 1 out of 2 changed files in this pull request and generated 2 comments.

Comment thread docs/diagrams/data-flow.mmd Outdated
Comment thread docs/diagrams/data-flow.mmd Outdated
@mengesb
Fix secrets engine label and resource management flow
62bbddc 
- Use full endpoint paths in participant label:
  /v1/aws/creds/:role or /v1/aws/sts/:role
- Fix Resource Management phase: Vault provider returns creds to
  Terraform, which then makes API calls to target AWS services
@mengesb
mengesb requested a review from Copilot July 2, 2026 17:32
Copilot AI reviewed Jul 2, 2026
View reviewed changes

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 1 out of 2 changed files in this pull request and generated 1 comment.

Comment thread docs/diagrams/data-flow.mmd
@mengesb
mengesb requested a review from Copilot July 2, 2026 17:38
Copilot AI reviewed Jul 2, 2026
View reviewed changes

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 1 out of 2 changed files in this pull request and generated 1 comment.

Comment thread docs/diagrams/data-flow.mmd Outdated
@mengesb
mengesb requested a review from Copilot July 2, 2026 17:53
Copilot AI reviewed Jul 2, 2026
View reviewed changes

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 1 out of 2 changed files in this pull request and generated 1 comment.

Comment thread docs/diagrams/data-flow.mmd Outdated
@mengesb
Show full IMDS call sequence matching aws_credentials() implementation
1c6b7a1 
aws_credentials() first fetches creds using the profile name derived
from the ARN, then re-fetches via the listing endpoint as validation.
Show both calls to match the actual temporal flow.
@mengesb
mengesb requested a review from Copilot July 2, 2026 18:26
Copilot AI reviewed Jul 2, 2026
View reviewed changes

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 1 out of 2 changed files in this pull request and generated 4 comments.

Comment thread docs/diagrams/data-flow.mmd
Comment thread docs/diagrams/data-flow.mmd
Comment thread docs/diagrams/data-flow.mmd Outdated
Comment thread docs/diagrams/data-flow.mmd Outdated
@mengesb
mengesb merged commit a356208 into main Jul 2, 2026
4 checks passed
@mengesb
mengesb deleted the docs/data-flow-diagram branch July 2, 2026 18:35
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

Copilot code review Copilot
Copilot review effort, defaults to Lite
Applies to this pull request for everyone.Learn more about Copilot code review.
Copilot left review comments

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@mengesb