vercel-enterprise-rbac

Overview

Configure Vercel's role-based access control (RBAC) with team roles, project-level access groups, SSO/SAML integration, and audit logging. Covers the two access control planes: team-level (who can deploy) and application-level (who can access deployed content).

Prerequisites

• Vercel Pro or Enterprise plan
• Identity Provider (IdP) with SAML 2.0 support (for SSO)
• Understanding of your organization's access requirements

Instructions

Step 1: Understand Vercel's Role Model

Team-Level Roles:

| Role | Deploy Prod | Manage Projects | Manage Billing | Manage Members | |------|-------------|-----------------|----------------|----------------| | Owner | Yes | Yes | Yes | Yes | | Member | Yes | Yes | No | No | | Developer | Preview only | Limited | No | No | | Viewer | No | Read-only | No | No | | Security (Enterprise) | No | Security settings | No | No |

Extended Permissions (Enterprise): Layer on top of base roles for granular control:

• Deploy to production
• Manage environment variables
• Manage domains
• Access runtime logs
• Manage integrations

Step 2: Configure Team Members via API

# Invite a team member
curl -X POST "https://api.vercel.com/v1/teams/team_xxx/members" \
  -H "Authorization: Bearer $VERCEL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "developer@company.com",
    "role": "DEVELOPER"
  }'

# List team members
curl -s -H "Authorization: Bearer $VERCEL_TOKEN" \
  "https://api.vercel.com/v2/teams/team_xxx/members" \
  | jq '.members[] | {name: .name, email: .email, role: .role}'

# Update a member's role
curl -X PATCH "https://api.vercel.com/v1/teams/team_xxx/members/user_xxx" \
  -H "Authorization: Bearer $VERCEL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"role": "MEMBER"}'

# Remove a team member
curl -X DELETE "https://api.vercel.com/v1/teams/team_xxx/members/user_xxx" \
  -H "Authorization: Bearer $VERCEL_TOKEN"

Step 3: Access Groups (Project-Level Permissions)

Access Groups assign teams of people to specific projects with specific roles:

1. Go to Team Settings > Access Groups
2. Create a group (e.g., "Frontend Team", "Backend Team")
3. Add members to the group
4. Assign the group to specific projects with a role

Example Access Group Setup:
├── Frontend Team → [project-web, project-docs] → Member role
├── Backend Team → [project-api, project-worker] → Member role
├── DevOps Team → [all projects] → Member role
└── QA Team → [all projects] → Viewer role

Step 4: SSO / SAML Configuration

In the Vercel dashboard: Team Settings > Authentication > SAML Single Sign-On

1. Enable SAML SSO
2. Configure your IdP (Okta, Azure AD, Google Workspace):
   • ACS URL: https://vercel.com/api/auth/saml/acs
   • Entity ID: https://vercel.com
   • Name ID format: emailAddress
3. Enter IdP metadata URL or upload certificate
4. Map SAML attributes to Vercel fields

SAML Attribute Mapping:
├── email → user email (required)
├── firstName → display name
├── lastName → display name
└── groups → Vercel team roles (optional)

Enforce SSO for all team members: Once enabled, toggle "Require SAML for login" — all members must authenticate through SSO.

Step 5: Application-Level Auth with Middleware

// middleware.ts — enforce auth on deployed application routes
import { NextRequest, NextResponse } from 'next/server';
import { verifyJWT } from '@/lib/auth';

const ROLE_ROUTES: Record<string, string[]> = {
  '/admin': ['admin'],
  '/dashboard': ['admin', 'member'],
  '/api/admin': ['admin'],
};

export async function middleware(request: NextRequest) {
  const { pathname } = request.nextUrl;

  // Check if route requires auth
  const requiredRoles = Object.entries(ROLE_ROUTES)
    .find(([prefix]) => pathname.startsWith(prefix));

  if (!requiredRoles) return NextResponse.next();

  const token = request.cookies.get('session')?.value;
  if (!token) {
    return pathname.startsWith('/api')
      ? NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
      : NextResponse.redirect(new URL('/login', request.url));
  }

  const payload = await verifyJWT(token);
  if (!payload || !requiredRoles[1].includes(payload.role)) {
    return NextResponse.json({ error: 'Forbidden' }, { status: 403 });
  }

  // Pass user info to API routes via headers
  const response = NextResponse.next();
  response.headers.set('x-user-id', payload.sub);
  response.headers.set('x-user-role', payload.role);
  return response;
}

export const config = {
  matcher: ['/admin/:path*', '/dashboard/:path*', '/api/admin/:path*'],
};

Step 6: Audit Logging

Vercel Enterprise includes audit logs in Team Settings > Audit Log.

Events tracked:

• Team member added/removed/role changed
• Project created/deleted
• Deployment to production
• Environment variable created/updated/deleted
• Domain added/removed
• Integration installed/uninstalled
• SSO configuration changes

# Export audit logs via API (Enterprise)
curl -s -H "Authorization: Bearer $VERCEL_TOKEN" \
  "https://api.vercel.com/v1/teams/team_xxx/audit-log?limit=100" \
  | jq '.events[] | {action: .action, user: .user.email, createdAt: .createdAt, resource: .resource}'

RBAC Checklist

| Check | Status | |-------|--------| | Team roles assigned per least privilege | Required | | Production deploy restricted to Member+ | Required | | Access Groups configured per project | Recommended | | SSO/SAML enforced for all members | Enterprise | | Audit logging exported to SIEM | Enterprise | | Application-level auth in middleware | Required | | Off-boarding removes Vercel access via IdP | Required |

Output

• Team roles configured with least-privilege access
• Access Groups scoping members to specific projects
• SSO/SAML enforced for all team authentication
• Application-level RBAC in Edge Middleware
• Audit logs exported for compliance

Error Handling

| Error | Cause | Solution | |-------|-------|----------| | Member can't deploy to prod | Developer role (preview only) | Change to Member or Owner role | | SSO login fails | IdP metadata URL expired | Update SAML configuration | | Access Group not applied | Member not in group | Add member to the Access Group | | Audit log missing events | Free/Pro plan limitation | Upgrade to Enterprise for audit logs | | Off-boarded user still has access | SSO not enforced | Enable "Require SAML for login" |

Examples

Off-board a production deployer with evidence

Remove the person from the identity-provider group that maps to Vercel production access, then confirm their team membership and Access Group assignments no longer grant deployment capability. Keep at least two designated owners in the recovery group before making changes, and test a non-production access path with a substitute account rather than the departed user’s credentials. Export the relevant audit event to the approved SIEM and retain the change ticket identifier without copying user data into the repository.

Resources

• Vercel RBAC
• Access Roles
• Access Groups
• Extended Permissions
• Managing Team Members

Next Steps

For migration strategies, see vercel-migration-deep-dive.