Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
40 changes: 37 additions & 3 deletions docs/api-reference.md
Original file line number Diff line number Diff line change
Expand Up @@ -405,6 +405,10 @@ Export your key as `AMCP_MCP_API_KEY` (or `AMCP_ACCESS_TOKEN` when the server op
| GET | `/api/roles/:id/tools` | List tool access for a role |
| PUT | `/api/roles/:id/tools` | Set tool access whitelist |
| PUT | `/api/roles/:id/tools/:toolId/rate-limit` | Update rate limits on an existing tool grant |
| GET | `/api/roles/members` | List members with every MCP role they hold and the connectors those roles reach |
| GET | `/api/roles/assignments/:userId` | List a member's MCP roles, with where each comes from |
| PUT | `/api/roles/assignments/:userId` | Replace a member's manual MCP roles |
| PUT | `/api/roles/assign/:userId` | Deprecated: set one MCP role. Use `PUT /api/roles/assignments/:userId` |

### Create Role with Tool Whitelist

Expand All @@ -423,12 +427,42 @@ curl -s -X PUT http://localhost:4000/api/roles/$ROLE_ID/tools \
-d '{"toolIds": ["tool-id-1", "tool-id-2", "tool-id-3"]}'
```

### Assign roles to members

A member can hold several MCP roles and may call the **union** of their tools:
each role adds tools, none takes any away. A role comes from one of two
sources:

- `manual`: set by an admin, under **Settings → Roles** or with
`PUT /api/roles/assignments/:userId`.
- the single sign-on group sync (for example `entra`): set by the
provider's role mappings ([SSO guide](sso.md#3-map-directory-groups-to-roles)).
Change these in the mappings, not on the member.

`PUT /api/roles/assignments/:userId` replaces only the member's **manual**
roles in your workspace; roles from group sync stay.

```bash
curl -s -X PUT http://localhost:4000/api/roles/assignments/$USER_ID \
-H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' \
-d '{"roleIds": ["'$ROLE_ID'"]}'
```

`GET /api/roles/members` returns every member of your workspace with all their
roles (`roles[]`: `roleId`, `roleName`, `source`, and `global` for a grant that
applies in every workspace) and `connectors`, the connectors those roles reach.
`connectors` is `null` when roles do not limit the member: a workspace ADMIN,
or a member with no role while no role of the workspace has a tool list.
`GET /api/users` also returns all roles of each member in `mcpRoles`; its
`mcpRoleId` and `mcpRole` fields are deprecated and hold one role at most.

### Per-tool rate limits

An administrator can set optional minute and hour limits on an existing
role/tool grant. The editor UI is planned separately; configure limits through
the API for now. `GET /api/roles/:id/tools` returns `callsPerMinute` and
`callsPerHour` on each grant.
role/tool grant, under **Settings → Roles → Manage tools** or through the API.
`GET /api/roles/:id/tools` returns `callsPerMinute` and `callsPerHour` on each
grant.

```bash
curl -s -X PUT "http://localhost:4000/api/roles/$ROLE_ID/tools/tool-id-1/rate-limit" \
Expand Down
13 changes: 9 additions & 4 deletions docs/operations/member-visibility.md
Original file line number Diff line number Diff line change
Expand Up @@ -127,10 +127,15 @@ of its tools. So set up the roles first, then switch the mode:
2. **Make members Viewer** (or Editor if they create connectors themselves)
under **Settings → Users**. Admins are never restricted, so keep the admin
role for the people who manage the workspace.
3. **Assign the roles.** By hand under **Settings → Users**, or from your
directory: map SSO groups to MCP roles under **Settings → Single sign-on →
Role mappings** ([SSO guide](../sso.md#3-map-directory-groups-to-roles)).
Set the workspace role of those mappings to Viewer as well.
3. **Assign the roles.** By hand under **Settings → Roles → User MCP Role
Assignment**, or from your directory: map SSO groups to MCP roles under
**Settings → Single sign-on → Role mappings**
([SSO guide](../sso.md#3-map-directory-groups-to-roles)). Set the workspace
role of those mappings to Viewer as well. A member can hold several roles
and reaches the connectors of all of them together. The assignment table
shows every role of each member: roles from a single sign-on group are
marked and can only be changed in the role mappings, and the last column
counts the connectors the member's roles reach.
4. **Switch to Restricted** under **Settings → Organization → Security →
Member visibility**, and save.

Expand Down
4 changes: 3 additions & 1 deletion docs/sso.md
Original file line number Diff line number Diff line change
Expand Up @@ -128,7 +128,9 @@ Resolution rules:
- A user in several mapped groups receives the **union** of their MCP roles and
the **most privileged** workspace role.
- Roles an admin assigned by hand are **never** removed by a sync, and vice
versa.
versa. **Settings → Roles → User MCP Role Assignment** shows both kinds for
each member; synced roles are marked `from single sign-on group` and can
only be changed here, in the mappings.
- A sync will **not** demote the last remaining admin of a workspace. The
attempt is refused and audited as `LAST_ADMIN_PROTECTION_TRIGGERED`.

Expand Down
57 changes: 49 additions & 8 deletions llms-full.txt

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

46 changes: 44 additions & 2 deletions packages/backend/src/roles/roles.controller.ts
Original file line number Diff line number Diff line change
Expand Up @@ -105,8 +105,9 @@ export class RolesController {
summary: 'List all roles (ADMIN)',
description:
'The MCP roles of your workspace plus the built-in system roles. An MCP role is a whitelist of tools: a member ' +
'with one or more roles may call only the tools those roles allow (the union); a member with no MCP role keeps ' +
'access to every tool of the servers they reach. Separate from the workspace role (ADMIN, EDITOR, VIEWER).',
'with one or more roles may call only the tools those roles allow (the union). A member with no MCP role can call ' +
'every tool while no role of the workspace has a tool list, and no tool once one has. Separate from the workspace ' +
'role (ADMIN, EDITOR, VIEWER); a workspace ADMIN can call every tool.',
})
async listRoles(@Req() req: any) {
return this.rolesService.findAll(req.user.organizationId);
Expand All @@ -129,6 +130,46 @@ export class RolesController {
return this.rolesService.create({ ...dto, organizationId: req.user.organizationId });
}

// Declared before `GET :id`, which would otherwise capture "members".
@Get('members')
@ApiOperation({
summary: 'List members with all their MCP roles (ADMIN)',
description:
'Every member of your workspace with EVERY MCP role they hold in it: `roles[].source` is `manual` (set by an ' +
'admin, editable with `PUT /api/roles/assignments/{userId}`) or the identity provider group sync (change it in ' +
'the provider\'s role mappings); `roles[].global` marks a grant that applies in every workspace. A member may ' +
'call the union of the tools of all their roles. `connectors` lists the connectors those roles grant tools of; ' +
'it is null when roles do not limit the member (a workspace ADMIN, or no role while no role of the workspace ' +
'has a tool list).',
})
@ApiResponse({
status: 200,
schema: {
type: 'array',
items: { type: 'object' },
example: [
{
id: 'cmo8a7b6c0000abcdx1y2z3w4',
email: 'ana@example.com',
name: 'Ana',
role: 'VIEWER',
active: true,
roles: [
{ roleId: 'cmoc1d2e300e01zrpr3s4t5u6', roleName: 'sales-read-only', source: 'manual', global: false },
{ roleId: 'cmoc1d2e300e11zrpa1b2c3d4', roleName: 'finance', source: 'entra', global: false },
],
connectors: [
{ id: 'cmob7a1b200c01zrp1a2b3c4d', name: 'CRM' },
{ id: 'cmob7a1b200c11zrp5e6f7g8h', name: 'ERP' },
],
},
],
},
})
async listMembers(@Req() req: any) {
return this.rolesService.getMemberAssignments(req.user.organizationId);
}

@Get(':id')
@ApiOperation({ summary: 'Get role details with tool access (ADMIN)' })
async getRole(@Req() req: any, @Param('id') id: string) {
Expand Down Expand Up @@ -265,6 +306,7 @@ export class RolesController {
userId,
req.user.organizationId,
);
if (!assignments) throw new NotFoundException('User not found');
return {
roleIds: [...new Set(assignments.map((a) => a.roleId))],
roles: assignments.map((a) => ({
Expand Down
137 changes: 137 additions & 0 deletions packages/backend/src/roles/roles.service.spec.ts
Original file line number Diff line number Diff line change
Expand Up @@ -40,6 +40,7 @@
},
organizationMember: {
findUnique: jest.fn(),
findMany: jest.fn().mockResolvedValue([]),
},
userRoleAssignment: {
findMany: jest.fn().mockResolvedValue([]),
Expand Down Expand Up @@ -505,7 +506,7 @@
});

describe('setUserRoles', () => {
const memberOf = (org = 'org-1') =>

Check warning on line 509 in packages/backend/src/roles/roles.service.spec.ts

View workflow job for this annotation

GitHub Actions / Backend (lint, typecheck, test, build)

'org' is assigned a value but never used. Allowed unused args must match /^_/u
mockPrisma.organizationMember.findUnique.mockResolvedValue({ userId: 'user-1' });

it('replaces the manual grants and leaves IdP-derived ones alone', async () => {
Expand Down Expand Up @@ -661,6 +662,142 @@
});
});

describe('getUserRoles', () => {
it('returns null for a user outside the organization', async () => {
// Grants with no organization apply everywhere; without the membership
// check an admin could read them for anyone on the instance.
mockPrisma.organizationMember.findUnique.mockResolvedValue(null);
expect(await service.getUserRoles('u1', 'org-1')).toBeNull();
expect(mockPrisma.userRoleAssignment.findMany).not.toHaveBeenCalled();
});

it('lists the org and workspace-independent grants of a member', async () => {
mockPrisma.organizationMember.findUnique.mockResolvedValue({ userId: 'u1' });
mockPrisma.userRoleAssignment.findMany.mockResolvedValue([{ roleId: 'r1', source: 'manual', role: { id: 'r1', name: 'Sales' } }]);
expect(await service.getUserRoles('u1', 'org-1')).toHaveLength(1);
expect(mockPrisma.userRoleAssignment.findMany).toHaveBeenCalledWith(
expect.objectContaining({
where: { userId: 'u1', OR: [{ organizationId: 'org-1' }, { organizationId: null }] },
}),
);
});
});

describe('getMemberAssignments', () => {
const member = (id: string, role: string, deactivatedAt: Date | null = null) => ({
role,
deactivatedAt,
user: { id, email: `${id}@example.com`, name: null },
});

it('returns every assignment of a member, not just one', async () => {
// The bug this guards: the roles page showed the deprecated single
// `users.mcpRoleId`, so an IdP-synced role widening access was invisible.
mockPrisma.organizationMember.findMany.mockResolvedValue([member('u1', 'VIEWER')]);
mockPrisma.userRoleAssignment.findMany.mockResolvedValue([
{ userId: 'u1', roleId: 'r1', source: 'manual', organizationId: 'org-1', role: { name: 'Support' } },
{ userId: 'u1', roleId: 'r2', source: 'entra', organizationId: 'org-1', role: { name: 'Finance' } },
{ userId: 'u1', roleId: 'sys', source: 'manual', organizationId: null, role: { name: 'Global' } },
]);
mockPrisma.toolRoleAccess.findMany.mockResolvedValue([
{ roleId: 'r1', tool: { connector: { id: 'c1', name: 'Helpdesk' } } },
{ roleId: 'r2', tool: { connector: { id: 'c2', name: 'ERP' } } },
{ roleId: 'r2', tool: { connector: { id: 'c3', name: 'CRM' } } },
// Same connector through a second role and a second tool: counted once.
{ roleId: 'r1', tool: { connector: { id: 'c3', name: 'CRM' } } },
]);

const [row] = await service.getMemberAssignments('org-1');

expect(row.roles).toEqual([
{ roleId: 'r1', roleName: 'Support', source: 'manual', global: false },
{ roleId: 'r2', roleName: 'Finance', source: 'entra', global: false },
{ roleId: 'sys', roleName: 'Global', source: 'manual', global: true },
]);
expect(row.connectors).toEqual([
{ id: 'c3', name: 'CRM' },
{ id: 'c2', name: 'ERP' },
{ id: 'c1', name: 'Helpdesk' },
]);
expect(row.active).toBe(true);
});

it('keeps every query inside the organization', async () => {
mockPrisma.organizationMember.findMany.mockResolvedValue([member('u1', 'EDITOR'), member('u2', 'VIEWER')]);
mockPrisma.userRoleAssignment.findMany.mockResolvedValue([
{ userId: 'u1', roleId: 'r1', source: 'manual', organizationId: 'org-1', role: { name: 'Support' } },
]);

await service.getMemberAssignments('org-1');

expect(mockPrisma.organizationMember.findMany).toHaveBeenCalledWith(
expect.objectContaining({ where: { organizationId: 'org-1' } }),
);
expect(mockPrisma.userRoleAssignment.findMany).toHaveBeenCalledWith(
expect.objectContaining({
where: { userId: { in: ['u1', 'u2'] }, OR: [{ organizationId: 'org-1' }, { organizationId: null }] },
}),
);
expect(mockPrisma.toolRoleAccess.findMany).toHaveBeenCalledWith(
expect.objectContaining({
where: { roleId: { in: ['r1'] }, tool: { connector: { organizationId: 'org-1' } } },
}),
);
});

it('reports admins as not limited by roles, even when they hold some', async () => {
mockPrisma.organizationMember.findMany.mockResolvedValue([member('a1', 'ADMIN')]);
mockPrisma.userRoleAssignment.findMany.mockResolvedValue([
{ userId: 'a1', roleId: 'r1', source: 'entra', organizationId: 'org-1', role: { name: 'Support' } },
]);

const [row] = await service.getMemberAssignments('org-1');

expect(row.connectors).toBeNull();
expect(row.roles).toHaveLength(1);
});

it('a member with no role is unrestricted while the org has no whitelist', async () => {
mockPrisma.organizationMember.findMany.mockResolvedValue([member('u1', 'EDITOR'), member('u2', 'VIEWER')]);
mockPrisma.toolRoleAccess.findFirst.mockResolvedValue(null);

const rows = await service.getMemberAssignments('org-1');

expect(rows.map((r) => r.connectors)).toEqual([null, null]);
expect(mockPrisma.toolRoleAccess.findMany).not.toHaveBeenCalled();
// The probe runs once for the whole list, not per member.
expect(mockPrisma.toolRoleAccess.findFirst).toHaveBeenCalledTimes(1);
});

it('a member with no role reaches nothing once the org uses whitelists', async () => {
mockPrisma.organizationMember.findMany.mockResolvedValue([member('u1', 'EDITOR')]);
mockPrisma.toolRoleAccess.findFirst.mockResolvedValue({ id: 'g1' });

const [row] = await service.getMemberAssignments('org-1');

expect(row.connectors).toEqual([]);
expect(row.roles).toEqual([]);
});

it('a role with an empty whitelist reaches no connector', async () => {
mockPrisma.organizationMember.findMany.mockResolvedValue([member('u1', 'VIEWER', new Date())]);
mockPrisma.userRoleAssignment.findMany.mockResolvedValue([
{ userId: 'u1', roleId: 'empty', source: 'manual', organizationId: 'org-1', role: { name: 'Empty' } },
]);
mockPrisma.toolRoleAccess.findMany.mockResolvedValue([]);

const [row] = await service.getMemberAssignments('org-1');

expect(row.connectors).toEqual([]);
expect(row.active).toBe(false);
});

it('returns [] for an organization without members', async () => {
expect(await service.getMemberAssignments('org-1')).toEqual([]);
expect(mockPrisma.userRoleAssignment.findMany).not.toHaveBeenCalled();
});
});

describe('getCapabilities', () => {
it('returns {} for a non-member', async () => {
mockPrisma.organizationMember.findUnique.mockResolvedValue(null);
Expand Down
Loading
Loading