instantly-enterprise-rbac

配置即时企业 SSO、基于角色的访问控制和组织管理。在实施 SSO 集成、配置基于角色的权限或为 Instantly 设置组织级控制时使用。使用“即时 SSO”、“即时 RBAC”、“即时企业”、“即时角色”、“即时权限”、“即时 SAML”等短语触发。

📖 中文导读:配置即时企业 SSO、基于角色的访问控制和组织管理。在实施 SSO 集成、配置基于角色的权限或为 Instantly 设置组织级控制时使用。使用“即时 SSO”、“即时 RBAC”、“即时企业”、“即时角色”、“即时权限”、“即时 SAML”等短语触发。 以下正文为该技能的原始 SKILL.md 内容(英文),上方安装命令可直接使用。

name: instantly-enterprise-rbac description: | Configure Instantly enterprise SSO, role-based access control, and organization management. Use when implementing SSO integration, configuring role-based permissions, or setting up organization-level controls for Instantly. Trigger with phrases like "instantly SSO", "instantly RBAC", "instantly enterprise", "instantly roles", "instantly permissions", "instantly SAML". allowed-tools: Read, Write, Edit version: 1.0.0 license: MIT author: Jeremy Longshore jeremy@intentsolutions.io

Instantly Enterprise RBAC

Overview

Configure enterprise-grade access control for Instantly integrations.

Prerequisites

  • Instantly Enterprise tier subscription
  • Identity Provider (IdP) with SAML/OIDC support
  • Understanding of role-based access patterns
  • Audit logging infrastructure

Role Definitions

Role Permissions Use Case
Admin Full access Platform administrators
Developer Read/write, no delete Active development
Viewer Read-only Stakeholders, auditors
Service API access only Automated systems

Role Implementation

enum InstantlyRole {
  Admin = 'admin',
  Developer = 'developer',
  Viewer = 'viewer',
  Service = 'service',
}

interface InstantlyPermissions {
  read: boolean;
  write: boolean;
  delete: boolean;
  admin: boolean;
}

const ROLE_PERMISSIONS: Record<InstantlyRole, InstantlyPermissions> = {
  admin: { read: true, write: true, delete: true, admin: true },
  developer: { read: true, write: true, delete: false, admin: false },
  viewer: { read: true, write: false, delete: false, admin: false },
  service: { read: true, write: true, delete: false, admin: false },
};

function checkPermission(
  role: InstantlyRole,
  action: keyof InstantlyPermissions
): boolean {
  return ROLE_PERMISSIONS[role][action];
}

SSO Integration

SAML Configuration

// Instantly SAML setup
const samlConfig = {
  entryPoint: 'https://idp.company.com/saml/sso',
  issuer: 'https://instantly.com/saml/metadata',
  cert: process.env.SAML_CERT,
  callbackUrl: 'https://app.yourcompany.com/auth/instantly/callback',
};

// Map IdP groups to Instantly roles
const groupRoleMapping: Record<string, InstantlyRole> = {
  'Engineering': InstantlyRole.Developer,
  'Platform-Admins': InstantlyRole.Admin,
  'Data-Team': InstantlyRole.Viewer,
};

OAuth2/OIDC Integration

import { OAuth2Client } from '@instantly/sdk';

const oauthClient = new OAuth2Client({
  clientId: process.env.INSTANTLY_OAUTH_CLIENT_ID!,
  clientSecret: process.env.INSTANTLY_OAUTH_CLIENT_SECRET!,
  redirectUri: 'https://app.yourcompany.com/auth/instantly/callback',
  scopes: ['read', 'write'],
});

Organization Management

interface InstantlyOrganization {
  id: string;
  name: string;
  ssoEnabled: boolean;
  enforceSso: boolean;
  allowedDomains: string[];
  defaultRole: InstantlyRole;
}

async function createOrganization(
  config: InstantlyOrganization
): Promise<void> {
  await instantlyClient.organizations.create({
    ...config,
    settings: {
      sso: {
        enabled: config.ssoEnabled,
        enforced: config.enforceSso,
        domains: config.allowedDomains,
      },
    },
  });
}

Access Control Middleware

function requireInstantlyPermission(
  requiredPermission: keyof InstantlyPermissions
) {
  return async (req: Request, res: Response, next: NextFunction) => {
    const user = req.user as { instantlyRole: InstantlyRole };

    if (!checkPermission(user.instantlyRole, requiredPermission)) {
      return res.status(403).json({
        error: 'Forbidden',
        message: `Missing permission: ${requiredPermission}`,
      });
    }

    next();
  };
}

// Usage
app.delete('/instantly/resource/:id',
  requireInstantlyPermission('delete'),
  deleteResourceHandler
);

Audit Trail

interface InstantlyAuditEntry {
  timestamp: Date;
  userId: string;
  role: InstantlyRole;
  action: string;
  resource: string;
  success: boolean;
  ipAddress: string;
}

async function logInstantlyAccess(entry: InstantlyAuditEntry): Promise<void> {
  await auditDb.insert(entry);

  // Alert on suspicious activity
  if (entry.action === 'delete' && !entry.success) {
    await alertOnSuspiciousActivity(entry);
  }
}

Instructions

Step 1: Define Roles

Map organizational roles to Instantly permissions.

Step 2: Configure SSO

Set up SAML or OIDC integration with your IdP.

Step 3: Implement Middleware

Add permission checks to API endpoints.

Step 4: Enable Audit Logging

Track all access for compliance.

Output

  • Role definitions implemented
  • SSO integration configured
  • Permission middleware active
  • Audit trail enabled

Error Handling

Issue Cause Solution
SSO login fails Wrong callback URL Verify IdP config
Permission denied Missing role mapping Update group mappings
Token expired Short TTL Refresh token logic
Audit gaps Async logging failed Check log pipeline

Examples

Quick Permission Check

if (!checkPermission(user.role, 'write')) {
  throw new ForbiddenError('Write permission required');
}

Resources

Next Steps

For major migrations, see instantly-migration-deep-dive.