AWS IAM Temporary Delegation Implementation Guide

Overview

This document outlines the implementation plan for integrating AWS IAM Temporary Delegation into Vell's Cloud Connector wizard, enabling accelerated onboarding for demos, trials, and enterprise evaluations.

---

Prerequisites Checklist

AWS Partner Requirements

Requirement	Status	Notes
ISV Accelerate (ISVA) enrollment	[ ] Verify	Contact AWS Partner team
AWS Marketplace listing	[x] Active	Vell is listed on AWS Marketplace
"Deployed on AWS" badge	[ ] Verify	Required for qualification
AWS Partner Central account	[ ] Confirm	Needed for Partner ID

Vell Account Information (Pre-filled)

Field	Value	Source
AWS Account ID	253265132499	Production account
Requestor Domain	vell.ai	Primary domain
Partner Name	Vell	Display name in AWS Console

---

Partner Questionnaire (Ready to Submit)

Email to: aws-iam-partner-onboarding@amazon.com

Subject: IAM Temporary Delegation Onboarding Request - Vell

Partner Central Account ID: [Your Partner Central AWS Account ID]
Partner ID: [From AWS Partner Central - format: P-XXXXXXXX]
AWS Marketplace Product ID: [From AWS Marketplace - format: prod-XXXXXXXX]

AWS Account IDs for API Access:
- Production: 253265132499
- Staging: [Your staging account ID]
- Development: [Your dev account ID]

Partner Name: Vell
Contact Emails: [your-email@vell.ai], [team-email@vell.ai]
Requestor Domain: vell.ai

Integration Description:
Vell is an AI-powered GTM automation platform for AWS Marketplace partners.
We help ISVs manage their marketplace listings, sync agreements, and
accelerate go-to-market through 22 AI capabilities.

We want to use IAM Temporary Delegation to:
1. Enable instant demo experiences with real customer AWS Marketplace data
2. Provide friction-free trial onboarding (4-12 hour access)
3. Automate permanent IAM role creation with permission boundaries

Our integration will request read-only AWS Marketplace API access
(DescribeEntity, ListEntities, etc.) with optional write access for
listing updates. See attached policy template.

Architecture Diagram: [Attach architecture diagram]
Policy Template: [See below]
Permission Boundary: [See below]

---

Policy Template

This defines what temporary permissions Vell requests from customers.

Read-Only Demo Template (4 hours)

{
  "TemplateName": "VellMarketplaceReadOnly",
  "Description": "Read-only access to AWS Marketplace Catalog and Agreement APIs for demo/trial purposes",
  "MaxDuration": 14400,
  "PolicyDocument": {
    "Version": "2012-10-17",
    "Statement": [
      {
        "Sid": "MarketplaceCatalogReadAccess",
        "Effect": "Allow",
        "Action": [
          "aws-marketplace:DescribeEntity",
          "aws-marketplace:ListEntities",
          "aws-marketplace:DescribeChangeSet",
          "aws-marketplace:ListChangeSets"
        ],
        "Resource": "*"
      },
      {
        "Sid": "MarketplaceAgreementReadAccess",
        "Effect": "Allow",
        "Action": [
          "aws-marketplace:SearchAgreements",
          "aws-marketplace:DescribeAgreement",
          "aws-marketplace:GetAgreementTerms"
        ],
        "Resource": "*"
      }
    ]
  }
}

Full Access Template (up to 12 hours)

{
  "TemplateName": "VellMarketplaceFullAccess",
  "Description": "Full AWS Marketplace access for trial/onboarding, including listing updates",
  "MaxDuration": 43200,
  "PolicyDocument": {
    "Version": "2012-10-17",
    "Statement": [
      {
        "Sid": "MarketplaceCatalogReadAccess",
        "Effect": "Allow",
        "Action": [
          "aws-marketplace:DescribeEntity",
          "aws-marketplace:ListEntities",
          "aws-marketplace:DescribeChangeSet",
          "aws-marketplace:ListChangeSets"
        ],
        "Resource": "*"
      },
      {
        "Sid": "MarketplaceCatalogWriteAccess",
        "Effect": "Allow",
        "Action": [
          "aws-marketplace:StartChangeSet",
          "aws-marketplace:CancelChangeSet"
        ],
        "Resource": "*"
      },
      {
        "Sid": "MarketplaceAgreementReadAccess",
        "Effect": "Allow",
        "Action": [
          "aws-marketplace:SearchAgreements",
          "aws-marketplace:DescribeAgreement",
          "aws-marketplace:GetAgreementTerms"
        ],
        "Resource": "*"
      },
      {
        "Sid": "DenyDangerousOperations",
        "Effect": "Deny",
        "Action": [
          "aws-marketplace:DeleteEntity",
          "iam:*",
          "organizations:*",
          "account:*"
        ],
        "Resource": "*"
      }
    ]
  }
}

---

Permission Boundary

Required if creating persistent IAM roles via temporary delegation.

Boundary ARN Format

arn:aws:iam::partner:policy/permission_boundary/vell.ai/VellMarketplaceConnectorBoundary_20251206

Permission Boundary Document

{
  "BoundaryName": "VellMarketplaceConnectorBoundary_20251206",
  "Description": "Permission boundary for IAM roles created by Vell temporary delegation",
  "PolicyDocument": {
    "Version": "2012-10-17",
    "Statement": [
      {
        "Sid": "AllowMarketplaceCatalogAPI",
        "Effect": "Allow",
        "Action": [
          "aws-marketplace:DescribeEntity",
          "aws-marketplace:ListEntities",
          "aws-marketplace:DescribeChangeSet",
          "aws-marketplace:ListChangeSets",
          "aws-marketplace:StartChangeSet",
          "aws-marketplace:CancelChangeSet"
        ],
        "Resource": "*"
      },
      {
        "Sid": "AllowMarketplaceAgreementAPI",
        "Effect": "Allow",
        "Action": [
          "aws-marketplace:SearchAgreements",
          "aws-marketplace:DescribeAgreement",
          "aws-marketplace:GetAgreementTerms"
        ],
        "Resource": "*"
      },
      {
        "Sid": "DenyAllOtherServices",
        "Effect": "Deny",
        "NotAction": [
          "aws-marketplace:*"
        ],
        "Resource": "*"
      },
      {
        "Sid": "DenyDangerousMarketplaceActions",
        "Effect": "Deny",
        "Action": [
          "aws-marketplace:DeleteEntity"
        ],
        "Resource": "*"
      }
    ]
  }
}

---

Technical Implementation Plan

Phase 1: AWS Partner Onboarding (Week 1-2)

1. Verify ISV Accelerate status
2. Contact AWS Partner team

3. Confirm "Deployed on AWS" badge on Marketplace listing

4. Submit Partner Questionnaire

5. Complete all required fields above
6. Include architecture diagram

7. Submit policy templates and permission boundary

8. AWS Review Process

9. Expect 1-2 weeks for validation
10. Respond to any feedback on policies
11. Receive policy template ARNs upon approval

Phase 2: Backend Implementation (Week 3-4)

2.1 Create SNS Topic for Token Delivery

// app/CustomExtensions/CloudMarketplace/System/Services/AWS/DelegationTokenService.php

namespace App\CustomExtensions\CloudMarketplace\System\Services\AWS;

use Aws\Iam\IamClient;
use Aws\Sns\SnsClient;
use Illuminate\Support\Facades\Log;
use Illuminate\Support\Facades\Cache;

class DelegationTokenService
{
    private IamClient $iamClient;
    private SnsClient $snsClient;
    private string $policyTemplateArn;
    private string $permissionBoundaryArn;

    public function __construct()
    {
        $this->iamClient = new IamClient([
            'version' => 'latest',
            'region' => 'us-east-1',
        ]);

        $this->snsClient = new SnsClient([
            'version' => 'latest',
            'region' => 'us-east-1',
        ]);

        // These ARNs will be provided by AWS after onboarding
        $this->policyTemplateArn = config('cloud-marketplace.delegation.policy_template_arn');
        $this->permissionBoundaryArn = config('cloud-marketplace.delegation.permission_boundary_arn');
    }

    /**
     * Create a delegation request for a customer
     */
    public function createDelegationRequest(
        string $customerAwsAccountId,
        string $templateType = 'read_only',
        int $durationSeconds = 14400,
        bool $createPersistentRole = false
    ): array {
        $requestParams = [
            'PolicyTemplateArn' => $this->getPolicyTemplateArn($templateType),
            'Duration' => min($durationSeconds, 43200), // Max 12 hours
            'NotificationTarget' => config('cloud-marketplace.delegation.sns_topic_arn'),
        ];

        // If creating persistent role, include permission boundary
        if ($createPersistentRole) {
            $requestParams['CreateRole'] = true;
            $requestParams['RoleName'] = 'vell-marketplace-connector';
            $requestParams['PermissionsBoundary'] = $this->permissionBoundaryArn;
        }

        try {
            $result = $this->iamClient->createDelegationRequest($requestParams);

            return [
                'success' => true,
                'request_id' => $result['DelegationRequestId'],
                'console_url' => $result['ApprovalUrl'],
                'expires_at' => now()->addSeconds($durationSeconds),
            ];
        } catch (\Exception $e) {
            Log::error('Failed to create delegation request', [
                'error' => $e->getMessage(),
                'customer_account' => $customerAwsAccountId,
            ]);

            return [
                'success' => false,
                'error' => $e->getMessage(),
            ];
        }
    }

    /**
     * Handle SNS notification when customer approves delegation
     */
    public function handleApprovalNotification(array $snsMessage): void
    {
        $requestId = $snsMessage['DelegationRequestId'];
        $exchangeToken = $snsMessage['ExchangeToken'];

        // Store token for later exchange
        Cache::put(
            "delegation_token:{$requestId}",
            $exchangeToken,
            now()->addHours(1)
        );

        // Notify the waiting session (via websocket or polling)
        event(new DelegationApproved($requestId, $exchangeToken));
    }

    /**
     * Exchange token for temporary credentials
     */
    public function exchangeTokenForCredentials(string $requestId): array
    {
        $exchangeToken = Cache::get("delegation_token:{$requestId}");

        if (!$exchangeToken) {
            return [
                'success' => false,
                'error' => 'Token not found or expired',
            ];
        }

        try {
            $result = $this->iamClient->getDelegatedAccessToken([
                'DelegationRequestId' => $requestId,
                'ExchangeToken' => $exchangeToken,
            ]);

            return [
                'success' => true,
                'access_key_id' => $result['Credentials']['AccessKeyId'],
                'secret_access_key' => $result['Credentials']['SecretAccessKey'],
                'session_token' => $result['Credentials']['SessionToken'],
                'expiration' => $result['Credentials']['Expiration'],
            ];
        } catch (\Exception $e) {
            Log::error('Failed to exchange delegation token', [
                'error' => $e->getMessage(),
                'request_id' => $requestId,
            ]);

            return [
                'success' => false,
                'error' => $e->getMessage(),
            ];
        }
    }

    private function getPolicyTemplateArn(string $type): string
    {
        return match($type) {
            'read_only' => config('cloud-marketplace.delegation.read_only_template_arn'),
            'full_access' => config('cloud-marketplace.delegation.full_access_template_arn'),
            default => config('cloud-marketplace.delegation.read_only_template_arn'),
        };
    }
}

2.2 New Database Migration

// database/migrations/2025_12_XX_create_delegation_requests_table.php

Schema::create('delegation_requests', function (Blueprint $table) {
    $table->id();
    $table->foreignId('user_id')->constrained();
    $table->string('aws_account_id', 12);
    $table->string('delegation_request_id')->unique();
    $table->enum('type', ['demo', 'trial', 'onboarding']);
    $table->enum('status', ['pending', 'approved', 'rejected', 'expired', 'converted']);
    $table->timestamp('approved_at')->nullable();
    $table->timestamp('expires_at');
    $table->boolean('create_persistent_role')->default(false);
    $table->string('persistent_role_arn')->nullable();
    $table->foreignId('cloud_connection_id')->nullable()->constrained();
    $table->json('metadata')->nullable();
    $table->timestamps();

    $table->index(['user_id', 'status']);
    $table->index(['delegation_request_id']);
});

Phase 3: Frontend Implementation (Week 4-5)

3.1 Updated Wizard Flow

Current Flow:
Step 1: Provider Selection
Step 2: Account Information
Step 3: CloudFormation Deployment  ← FRICTION POINT
Step 4: IAM Role Validation
Step 5: Success

New Flow:
Step 1: Provider Selection (unchanged)
Step 2: Account Information (unchanged)
Step 3: Choose Onboarding Path (NEW)
        ├── [Quick Start - Demo] 4-hour read-only access
        │   └── One-click AWS approval → Immediate access
        ├── [Trial] Up to 12-hour full access
        │   └── Extended evaluation period
        └── [Production Setup] CloudFormation (existing)
            └── Permanent IAM role for production use

Step 4a: (Quick Start/Trial) → Waiting for Approval
         └── Customer redirected to AWS Console
         └── Real-time status update via websocket

Step 4b: (Production) → IAM Role Validation (existing)

Step 5: Connected! (with "Upgrade to Production" CTA for temp access)

3.2 New Step 3 View

{{-- resources/views/connections/wizard/step3-choose-path.blade.php --}}

<div class="grid grid-cols-1 md:grid-cols-3 gap-6">
    {{-- Quick Start Demo --}}
    <div class="card border-2 hover:border-primary cursor-pointer"
         data-path="demo">
        <div class="card-body text-center">
            <div class="text-4xl mb-4">⚡</div>
            <h3 class="font-bold text-lg">Quick Start Demo</h3>
            <p class="text-muted text-sm mb-4">
                4-hour read-only access<br>
                Perfect for evaluating Vell
            </p>
            <ul class="text-left text-sm space-y-2">
                <li>✓ View your marketplace listings</li>
                <li>✓ Sync agreement data</li>
                <li>✓ Try AI capabilities</li>
                <li>✓ No cleanup required</li>
            </ul>
            <div class="mt-4">
                <span class="badge bg-blue-100 text-blue-800">
                    Auto-expires in 4 hours
                </span>
            </div>
        </div>
    </div>

    {{-- Trial --}}
    <div class="card border-2 hover:border-primary cursor-pointer"
         data-path="trial">
        <div class="card-body text-center">
            <div class="text-4xl mb-4">🎯</div>
            <h3 class="font-bold text-lg">Extended Trial</h3>
            <p class="text-muted text-sm mb-4">
                Up to 12-hour full access<br>
                Complete GTM automation trial
            </p>
            <ul class="text-left text-sm space-y-2">
                <li>✓ Everything in Demo</li>
                <li>✓ Update marketplace listings</li>
                <li>✓ Full AgentCore capabilities</li>
                <li>✓ Co-sell matching</li>
            </ul>
            <div class="mt-4">
                <span class="badge bg-purple-100 text-purple-800">
                    Renewable daily
                </span>
            </div>
        </div>
    </div>

    {{-- Production --}}
    <div class="card border-2 hover:border-primary cursor-pointer"
         data-path="production">
        <div class="card-body text-center">
            <div class="text-4xl mb-4">🏢</div>
            <h3 class="font-bold text-lg">Production Setup</h3>
            <p class="text-muted text-sm mb-4">
                Permanent IAM role<br>
                For ongoing operations
            </p>
            <ul class="text-left text-sm space-y-2">
                <li>✓ Persistent connection</li>
                <li>✓ CloudFormation deployment</li>
                <li>✓ Least-privilege IAM role</li>
                <li>✓ Enterprise security</li>
            </ul>
            <div class="mt-4">
                <span class="badge bg-green-100 text-green-800">
                    Recommended for production
                </span>
            </div>
        </div>
    </div>
</div>

Phase 4: Use Case Implementation

4.1 Demo Mode (Sales Demos)

Scenario: Customer requests Vellocity demo

1. Sales rep creates demo link: /demo/request?company=acme
2. Customer enters AWS Account ID
3. Vell initiates delegation request (read-only, 4 hours)
4. Customer clicks "Approve in AWS Console" button
5. Customer approves in AWS Console (one click)
6. Vell receives SNS notification
7. Sales rep demos with customer's real data:
   - Show their marketplace listings
   - Display agreement pipeline
   - Generate AI content for their products
8. Access automatically expires - no cleanup

4.2 Trial Mode (Self-Service)

Scenario: Partner signs up for trial

1. Partner creates account on Vell
2. Starts cloud connector wizard
3. Selects "Extended Trial" path
4. Vell requests 12-hour full access
5. Partner approves in AWS Console
6. Partner experiences full platform:
   - Sync and optimize listings
   - Run AI workflows
   - Match with co-sell partners
7. Before expiry, prompt: "Ready for production?"
8. If yes: Use temporary delegation to CREATE permanent role
   - Vell uses current access to deploy IAM role
   - Role has permission boundary attached
   - Partner confirms role creation
9. Converted to permanent CloudConnection

4.3 Hybrid Onboarding (Temporary → Permanent)

Scenario: Enterprise wants full setup without manual CloudFormation

1. Admin selects "Automated Setup" option
2. Vell requests temporary delegation WITH create_role=true
3. Request includes:
   - 12-hour temporary access
   - Permission to create IAM role
   - Permission boundary attached to created role
4. Admin approves in AWS Console
5. Vell uses temporary credentials to:
   - Create IAM role with permission boundary
   - Configure trust policy for Vell account
   - Set external ID for security
6. Temporary access expires
7. Permanent role remains with bounded permissions
8. CloudConnection created automatically

---

Integration with Existing Features

Updated ConnectionController

// New method for delegation path
public function processDelegationRequest(Request $request): JsonResponse
{
    $validated = $request->validate([
        'aws_account_id' => 'required|string|size:12',
        'path' => 'required|in:demo,trial,production',
        'create_persistent_role' => 'boolean',
    ]);

    if ($validated['path'] === 'production') {
        // Redirect to existing CloudFormation flow
        return response()->json([
            'redirect' => route('dashboard.user.cloud-connectors.create', ['step' => 3]),
        ]);
    }

    $delegationService = new DelegationTokenService();

    $duration = match($validated['path']) {
        'demo' => 14400,  // 4 hours
        'trial' => 43200, // 12 hours
    };

    $result = $delegationService->createDelegationRequest(
        $validated['aws_account_id'],
        $validated['path'] === 'demo' ? 'read_only' : 'full_access',
        $duration,
        $validated['create_persistent_role'] ?? false
    );

    if ($result['success']) {
        // Store pending delegation
        DelegationRequest::create([
            'user_id' => Auth::id(),
            'aws_account_id' => $validated['aws_account_id'],
            'delegation_request_id' => $result['request_id'],
            'type' => $validated['path'],
            'status' => 'pending',
            'expires_at' => $result['expires_at'],
            'create_persistent_role' => $validated['create_persistent_role'] ?? false,
        ]);

        return response()->json([
            'success' => true,
            'approval_url' => $result['console_url'],
            'request_id' => $result['request_id'],
        ]);
    }

    return response()->json([
        'success' => false,
        'error' => $result['error'],
    ], 400);
}

---

Configuration

// config/cloud-marketplace.php

return [
    // Existing config...

    'delegation' => [
        'enabled' => env('AWS_DELEGATION_ENABLED', false),

        // SNS topic for receiving approval notifications
        'sns_topic_arn' => env('AWS_DELEGATION_SNS_TOPIC_ARN'),

        // Policy template ARNs (provided by AWS after onboarding)
        'read_only_template_arn' => env('AWS_DELEGATION_READ_ONLY_TEMPLATE_ARN'),
        'full_access_template_arn' => env('AWS_DELEGATION_FULL_ACCESS_TEMPLATE_ARN'),

        // Permission boundary for persistent roles
        'permission_boundary_arn' => env('AWS_DELEGATION_PERMISSION_BOUNDARY_ARN'),

        // Default durations
        'demo_duration_seconds' => 14400,  // 4 hours
        'trial_duration_seconds' => 43200, // 12 hours
    ],
];

---

Success Metrics

Metric	Current	Target	Measurement
Wizard completion rate	~40% (estimated)	75%+	Analytics tracking
Time to first sync	30-60 minutes	5 minutes	Timestamp delta
Demo conversion rate	N/A	Track	Demo → Trial → Production
Trial to production	N/A	60%+	Conversion funnel
Support tickets (setup)	Baseline	-50%	Support system

---

Timeline Summary

Phase	Duration	Deliverables
AWS Partner Onboarding	1-2 weeks	Partner approval, template ARNs
Backend Implementation	1-2 weeks	Services, models, migrations
Frontend Implementation	1 week	Updated wizard, new views
Testing & QA	1 week	End-to-end testing
Total	4-6 weeks	Production-ready integration

---

Next Steps

1. Immediate: Verify ISV Accelerate enrollment and "Deployed on AWS" badge
2. This week: Complete and submit Partner Questionnaire
3. After AWS approval: Begin backend implementation
4. Parallel: Design and build frontend components
5. Final: End-to-end testing with test AWS accounts

---

References

• AWS IAM Temporary Delegation Documentation
• Partner Integration Guide
• Current CloudFormation: /app/CustomExtensions/CloudMarketplace/resources/cloudformation/vell-aws-marketplace-role.yaml
• Current Wizard: /app/CustomExtensions/CloudMarketplace/System/Http/Controllers/ConnectionController.php