vercel-enterprise-rbac

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:

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": "[email protected]",
    "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

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

Resources

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

Next Steps

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