CtrlK
CommunityDocumentationLog inGet started
Tessl Logo

langfuse-enterprise-rbac

tessl install github:jeremylongshore/claude-code-plugins-plus-skills --skill langfuse-enterprise-rbac
github.com/jeremylongshore/claude-code-plugins-plus-skills

Configure Langfuse enterprise organization management and access control. Use when implementing team access controls, configuring organization settings, or setting up role-based permissions for Langfuse projects. Trigger with phrases like "langfuse RBAC", "langfuse teams", "langfuse organization", "langfuse access control", "langfuse permissions".

Review Score

78%

Validation Score

12/16

Implementation Score

65%

Activation Score

90%

Langfuse Enterprise RBAC

Overview

Configure enterprise-grade access control for Langfuse projects and organizations.

Prerequisites

  • Langfuse organization/team account
  • Understanding of role-based access patterns
  • SSO provider (optional, for enterprise SSO)

Role Definitions

RoleDashboardAPI ReadAPI WriteSettingsBilling
OwnerFullFullFullFullFull
AdminFullFullFullFullView
MemberFullFullFullNoneNone
ViewerViewReadNoneNoneNone
API OnlyNoneFullFullNoneNone

Instructions

Step 1: Implement Role-Based Access in Your Application

// lib/langfuse/rbac.ts

enum LangfuseRole {
  Owner = "owner",
  Admin = "admin",
  Member = "member",
  Viewer = "viewer",
  ApiOnly = "api_only",
}

interface LangfusePermissions {
  canViewDashboard: boolean;
  canReadTraces: boolean;
  canWriteTraces: boolean;
  canManageSettings: boolean;
  canManageMembers: boolean;
  canManageBilling: boolean;
  canCreateApiKeys: boolean;
  canDeleteData: boolean;
}

const ROLE_PERMISSIONS: Record<LangfuseRole, LangfusePermissions> = {
  [LangfuseRole.Owner]: {
    canViewDashboard: true,
    canReadTraces: true,
    canWriteTraces: true,
    canManageSettings: true,
    canManageMembers: true,
    canManageBilling: true,
    canCreateApiKeys: true,
    canDeleteData: true,
  },
  [LangfuseRole.Admin]: {
    canViewDashboard: true,
    canReadTraces: true,
    canWriteTraces: true,
    canManageSettings: true,
    canManageMembers: true,
    canManageBilling: false,
    canCreateApiKeys: true,
    canDeleteData: true,
  },
  [LangfuseRole.Member]: {
    canViewDashboard: true,
    canReadTraces: true,
    canWriteTraces: true,
    canManageSettings: false,
    canManageMembers: false,
    canManageBilling: false,
    canCreateApiKeys: false,
    canDeleteData: false,
  },
  [LangfuseRole.Viewer]: {
    canViewDashboard: true,
    canReadTraces: true,
    canWriteTraces: false,
    canManageSettings: false,
    canManageMembers: false,
    canManageBilling: false,
    canCreateApiKeys: false,
    canDeleteData: false,
  },
  [LangfuseRole.ApiOnly]: {
    canViewDashboard: false,
    canReadTraces: true,
    canWriteTraces: true,
    canManageSettings: false,
    canManageMembers: false,
    canManageBilling: false,
    canCreateApiKeys: false,
    canDeleteData: false,
  },
};

function hasPermission(
  role: LangfuseRole,
  permission: keyof LangfusePermissions
): boolean {
  return ROLE_PERMISSIONS[role][permission];
}

function checkPermission(
  role: LangfuseRole,
  permission: keyof LangfusePermissions
): void {
  if (!hasPermission(role, permission)) {
    throw new ForbiddenError(
      `Permission denied: ${permission} requires higher role than ${role}`
    );
  }
}

Step 2: Implement API Key Scoping

// lib/langfuse/scoped-keys.ts

interface ScopedApiKey {
  id: string;
  publicKey: string;
  secretKey: string;
  name: string;
  scope: ApiKeyScope;
  createdAt: Date;
  createdBy: string;
  expiresAt?: Date;
}

interface ApiKeyScope {
  permissions: ("read" | "write")[];
  projects?: string[];       // Restrict to specific projects
  environments?: string[];   // Restrict to specific environments
  ipAllowlist?: string[];    // Restrict by IP
  rateLimit?: number;        // Custom rate limit
}

class ScopedLangfuseClient {
  private langfuse: Langfuse;
  private scope: ApiKeyScope;

  constructor(apiKey: ScopedApiKey) {
    this.langfuse = new Langfuse({
      publicKey: apiKey.publicKey,
      secretKey: apiKey.secretKey,
    });
    this.scope = apiKey.scope;
  }

  trace(params: Parameters<typeof this.langfuse.trace>[0]) {
    // Check write permission
    if (!this.scope.permissions.includes("write")) {
      throw new ForbiddenError("API key does not have write permission");
    }

    // Check project restriction
    if (this.scope.projects?.length) {
      const projectId = params.metadata?.projectId;
      if (projectId && !this.scope.projects.includes(projectId)) {
        throw new ForbiddenError(`API key not authorized for project ${projectId}`);
      }
    }

    return this.langfuse.trace(params);
  }

  async fetchTraces(params: any) {
    // Check read permission
    if (!this.scope.permissions.includes("read")) {
      throw new ForbiddenError("API key does not have read permission");
    }

    return this.langfuse.fetchTraces(params);
  }
}

Step 3: Implement Project-Based Access Control

// lib/langfuse/projects.ts

interface LangfuseProject {
  id: string;
  name: string;
  organizationId: string;
  environment: "development" | "staging" | "production";
  members: ProjectMember[];
}

interface ProjectMember {
  userId: string;
  email: string;
  role: LangfuseRole;
  addedAt: Date;
  addedBy: string;
}

class ProjectAccessController {
  private projects: Map<string, LangfuseProject> = new Map();

  async getUserProjects(userId: string): Promise<LangfuseProject[]> {
    return Array.from(this.projects.values()).filter((project) =>
      project.members.some((m) => m.userId === userId)
    );
  }

  async getUserRole(userId: string, projectId: string): Promise<LangfuseRole | null> {
    const project = this.projects.get(projectId);
    if (!project) return null;

    const member = project.members.find((m) => m.userId === userId);
    return member?.role || null;
  }

  async addMember(
    projectId: string,
    member: Omit<ProjectMember, "addedAt">,
    addedBy: string
  ): Promise<void> {
    // Check if adder has permission
    const adderRole = await this.getUserRole(addedBy, projectId);
    if (!adderRole || !hasPermission(adderRole, "canManageMembers")) {
      throw new ForbiddenError("Cannot add members to this project");
    }

    // Prevent privilege escalation
    if (this.isHigherRole(member.role, adderRole)) {
      throw new ForbiddenError("Cannot add member with higher role than yourself");
    }

    const project = this.projects.get(projectId);
    if (!project) throw new NotFoundError("Project not found");

    project.members.push({
      ...member,
      addedAt: new Date(),
      addedBy,
    });
  }

  private isHigherRole(role1: LangfuseRole, role2: LangfuseRole): boolean {
    const hierarchy = [
      LangfuseRole.Viewer,
      LangfuseRole.ApiOnly,
      LangfuseRole.Member,
      LangfuseRole.Admin,
      LangfuseRole.Owner,
    ];
    return hierarchy.indexOf(role1) > hierarchy.indexOf(role2);
  }
}

Step 4: Implement SSO Integration

// lib/langfuse/sso.ts

interface SSOConfig {
  provider: "okta" | "azure" | "google" | "saml";
  domain: string;
  clientId: string;
  clientSecret: string;
  callbackUrl: string;
  groupMapping: Record<string, LangfuseRole>;
}

class LangfuseSSO {
  private config: SSOConfig;

  constructor(config: SSOConfig) {
    this.config = config;
  }

  // Map SSO groups to Langfuse roles
  mapGroupsToRole(groups: string[]): LangfuseRole {
    for (const group of groups) {
      if (this.config.groupMapping[group]) {
        return this.config.groupMapping[group];
      }
    }
    return LangfuseRole.Viewer; // Default role
  }

  // SAML assertion handler
  async handleSAMLAssertion(assertion: any): Promise<{
    userId: string;
    email: string;
    role: LangfuseRole;
    groups: string[];
  }> {
    const email = assertion.user.email;
    const groups = assertion.user.groups || [];

    // Verify domain
    if (!email.endsWith(`@${this.config.domain}`)) {
      throw new UnauthorizedError("Email domain not allowed");
    }

    return {
      userId: assertion.user.id,
      email,
      role: this.mapGroupsToRole(groups),
      groups,
    };
  }
}

// Usage
const ssoConfig: SSOConfig = {
  provider: "okta",
  domain: "company.com",
  clientId: process.env.OKTA_CLIENT_ID!,
  clientSecret: process.env.OKTA_CLIENT_SECRET!,
  callbackUrl: "https://app.company.com/auth/callback",
  groupMapping: {
    "Engineering-Admins": LangfuseRole.Admin,
    "Engineering": LangfuseRole.Member,
    "Data-Team": LangfuseRole.Viewer,
  },
};

Step 5: Implement Audit Logging for RBAC

// lib/langfuse/rbac-audit.ts

interface RBACEvent {
  timestamp: Date;
  action:
    | "member_added"
    | "member_removed"
    | "role_changed"
    | "api_key_created"
    | "api_key_revoked"
    | "permission_denied";
  actor: string;
  target: string;
  projectId?: string;
  details: Record<string, any>;
}

class RBACAuditLogger {
  async log(event: Omit<RBACEvent, "timestamp">) {
    const auditEvent: RBACEvent = {
      ...event,
      timestamp: new Date(),
    };

    // Log to audit trail
    console.log("[RBAC Audit]", JSON.stringify(auditEvent));

    // Store in database
    await this.persist(auditEvent);

    // Alert on sensitive actions
    if (event.action === "permission_denied") {
      await this.alertSecurityTeam(auditEvent);
    }
  }

  private async persist(event: RBACEvent) {
    // Store in audit database
  }

  private async alertSecurityTeam(event: RBACEvent) {
    // Send alert for potential security issues
  }

  async query(options: {
    actor?: string;
    action?: string;
    projectId?: string;
    from?: Date;
    to?: Date;
  }): Promise<RBACEvent[]> {
    // Query audit log
    return [];
  }
}

export const rbacAudit = new RBACAuditLogger();

Output

  • Role-based permission system
  • Scoped API key implementation
  • Project-based access control
  • SSO integration
  • RBAC audit logging

Access Control Matrix

ActionOwnerAdminMemberViewerAPI Only
View tracesYesYesYesYesNo
Create tracesYesYesYesNoYes
Delete tracesYesYesNoNoNo
Manage membersYesYesNoNoNo
Create API keysYesYesNoNoNo
Manage billingYesNoNoNoNo

Error Handling

IssueCauseSolution
Permission deniedInsufficient roleRequest role upgrade
SSO login failsWrong group mappingUpdate group mapping
API key rejectedExpired or scopedCreate new key
Project not foundNo accessRequest project access

Resources

  • Langfuse Organizations
  • Langfuse API Keys
  • SAML 2.0 Specification

Next Steps

For complex migrations, see langfuse-migration-deep-dive.