0
# Role Management
1

2
Realm and client role management with composite role support and role mapping operations.
3

4
## Capabilities
5

6
### Realm Role Management
7

8
Management of realm-level roles that apply across all clients in the realm.
9

10
```typescript { .api }
11
/**
12
 * Find realm roles with optional pagination
13
 * @param query - Optional pagination parameters
14
 * @returns Array of realm roles
15
 */
16
find(query?: RoleQuery): Promise<RoleRepresentation[]>;
17

18
/**
19
 * Create a new realm role
20
 * @param role - Role configuration
21
 * @returns Object with created role name
22
 */
23
create(role: RoleRepresentation): Promise<{ roleName: string }>;
24

25
/**
26
 * Find a specific realm role by name
27
 * @param params - Role name
28
 * @returns Role representation
29
 * @throws NetworkError if role not found
30
 */
31
findByName(params: { name: string }): Promise<RoleRepresentation>;
32

33
/**
34
 * Update an existing realm role
35
 * @param query - Role identifier
36
 * @param role - Updated role configuration
37
 */
38
update(query: { name: string }, role: RoleRepresentation): Promise<void>;
39

40
/**
41
 * Delete a realm role
42
 * @param params - Role identifier
43
 */
44
del(params: { name: string }): Promise<void>;
45
```
46

47
**Usage Examples:**
48

49
```typescript
50
// List all realm roles
51
const realmRoles = await kcAdminClient.roles.find();
52
console.log("Realm roles:", realmRoles.map(r => r.name));
53

54
// Create new realm role
55
await kcAdminClient.roles.create({
56
  name: "application-admin",
57
  description: "Administrator role for the application",
58
  attributes: {
59
    department: ["IT"],
60
    level: ["admin"],
61
  },
62
});
63

64
// Find specific role
65
const adminRole = await kcAdminClient.roles.findByName({
66
  name: "application-admin",
67
});
68

69
// Update role
70
await kcAdminClient.roles.update(
71
  { name: "application-admin" },
72
  {
73
    description: "Updated: Administrator role for the application",
74
    attributes: {
75
      department: ["IT", "Security"],
76
      level: ["admin"],
77
    },
78
  }
79
);
80

81
// Delete role
82
await kcAdminClient.roles.del({ name: "temporary-role" });
83
```
84

85
### Composite Roles
86

87
Management of composite roles that combine multiple other roles.
88

89
```typescript { .api }
90
/**
91
 * Get all composite roles for a realm role
92
 * @param params - Role identifier
93
 * @returns Array of composite roles (realm and client)
94
 */
95
getCompositeRoles(params: { name: string }): Promise<RoleRepresentation[]>;
96

97
/**
98
 * Get realm composite roles only
99
 * @param params - Role identifier
100
 * @returns Array of realm composite roles
101
 */
102
getCompositeRolesForRealm(params: { name: string }): Promise<RoleRepresentation[]>;
103

104
/**
105
 * Get client composite roles for a specific client
106
 * @param params - Role name and client identifier
107
 * @returns Array of client composite roles
108
 */
109
getCompositeRolesForClient(params: {
110
  name: string;
111
  clientId: string;
112
}): Promise<RoleRepresentation[]>;
113

114
/**
115
 * Add composite roles to a realm role
116
 * @param params - Role identifier and roles to add
117
 */
118
addCompositeRoles(params: {
119
  name: string;
120
  roles: RoleRepresentation[];
121
}): Promise<void>;
122

123
/**
124
 * Remove composite roles from a realm role
125
 * @param params - Role identifier and roles to remove
126
 */
127
delCompositeRoles(params: {
128
  name: string;
129
  roles: RoleRepresentation[];
130
}): Promise<void>;
131
```
132

133
**Usage Examples:**
134

135
```typescript
136
// Create composite role
137
await kcAdminClient.roles.create({
138
  name: "super-admin",
139
  description: "Super administrator with all permissions",
140
  composite: true,
141
});
142

143
// Add realm roles to composite
144
const userRole = await kcAdminClient.roles.findByName({ name: "user" });
145
const adminRole = await kcAdminClient.roles.findByName({ name: "admin" });
146

147
await kcAdminClient.roles.addCompositeRoles({
148
  name: "super-admin",
149
  roles: [userRole, adminRole],
150
});
151

152
// Get all composite roles
153
const compositeRoles = await kcAdminClient.roles.getCompositeRoles({
154
  name: "super-admin",
155
});
156
console.log("Composite roles:", compositeRoles.map(r => r.name));
157

158
// Get only realm composite roles
159
const realmComposites = await kcAdminClient.roles.getCompositeRolesForRealm({
160
  name: "super-admin",
161
});
162

163
// Remove composite roles
164
await kcAdminClient.roles.delCompositeRoles({
165
  name: "super-admin",
166
  roles: [userRole],
167
});
168
```
169

170
### Role Users
171

172
Find users assigned to specific roles.
173

174
```typescript { .api }
175
/**
176
 * Find users who have a specific realm role
177
 * @param params - Role name and pagination options
178
 * @returns Array of users with the role
179
 */
180
findUsersWithRole(params: {
181
  name: string;
182
  first?: number;
183
  max?: number;
184
}): Promise<UserRepresentation[]>;
185
```
186

187
**Usage Examples:**
188

189
```typescript
190
// Find all users with admin role
191
const adminUsers = await kcAdminClient.roles.findUsersWithRole({
192
  name: "admin",
193
});
194

195
console.log("Admin users:", adminUsers.map(u => u.username));
196

197
// Find users with pagination
198
const userPage = await kcAdminClient.roles.findUsersWithRole({
199
  name: "user",
200
  first: 0,
201
  max: 50,
202
});
203
```
204

205
### Client Role Management
206

207
Management of client-specific roles through the clients resource.
208

209
```typescript { .api }
210
/**
211
 * Note: Client roles are managed through the clients resource:
212
 * kcAdminClient.clients.createRole()
213
 * kcAdminClient.clients.listRoles()
214
 * kcAdminClient.clients.findRole()
215
 * kcAdminClient.clients.updateRole()
216
 * kcAdminClient.clients.delRole()
217
 */
218
```
219

220
**Usage Examples:**
221

222
```typescript
223
// Client role operations are performed through clients resource
224
const clientId = "my-client-id";
225

226
// Create client role
227
await kcAdminClient.clients.createRole(
228
  { id: clientId },
229
  {
230
    name: "app-user",
231
    description: "Application user role",
232
    clientRole: true,
233
  }
234
);
235

236
// List client roles
237
const clientRoles = await kcAdminClient.clients.listRoles({
238
  id: clientId,
239
});
240

241
// Find specific client role
242
const appUserRole = await kcAdminClient.clients.findRole({
243
  id: clientId,
244
  roleName: "app-user",
245
});
246

247
// Update client role
248
await kcAdminClient.clients.updateRole(
249
  { id: clientId, roleName: "app-user" },
250
  {
251
    description: "Updated: Application user role",
252
  }
253
);
254

255
// Delete client role
256
await kcAdminClient.clients.delRole({
257
  id: clientId,
258
  roleName: "app-user",
259
});
260
```
261

262
## Query Interfaces
263

264
```typescript { .api }
265
/**
266
 * Role query parameters for pagination
267
 */
268
interface RoleQuery {
269
  /** Search term for role name */
270
  search?: string;
271
  /** Number of results to skip */
272
  first?: number;
273
  /** Maximum number of results to return */
274
  max?: number;
275
  /** Return brief representation */
276
  briefRepresentation?: boolean;
277
}
278
```
279

280
## Types
281

282
```typescript { .api }
283
/**
284
 * Role representation with composite role support
285
 */
286
interface RoleRepresentation {
287
  /** Role unique identifier */
288
  id?: string;
289
  /** Role name */
290
  name?: string;
291
  /** Role description */
292
  description?: string;
293
  /** Whether role requires scope parameter */
294
  scopeParamRequired?: boolean;
295
  /** Whether role is composite */
296
  composite?: boolean;
297
  /** Composite role definitions */
298
  composites?: {
299
    /** Realm roles included in composite */
300
    realm?: string[];
301
    /** Client roles included in composite by client name */
302
    client?: Record<string, string[]>;
303
  };
304
  /** Whether this is a client role */
305
  clientRole?: boolean;
306
  /** Container ID (realm or client) */
307
  containerId?: string;
308
  /** Custom role attributes */
309
  attributes?: Record<string, string[]>;
310
}
311
```
312

313
## Role Assignment Patterns
314

315
Common patterns for assigning roles to users and groups:
316

317
```typescript
318
// Pattern 1: Assign realm role to user
319
const user = await kcAdminClient.users.findOne({ id: userId });
320
const role = await kcAdminClient.roles.findByName({ name: "admin" });
321

322
await kcAdminClient.users.addRealmRoleMappings({
323
  id: userId,
324
  roles: [{ id: role.id, name: role.name }],
325
});
326

327
// Pattern 2: Assign client role to user
328
const clientRole = await kcAdminClient.clients.findRole({
329
  id: clientId,
330
  roleName: "app-admin",
331
});
332

333
await kcAdminClient.users.addClientRoleMappings({
334
  id: userId,
335
  clientUniqueId: clientId,
336
  roles: [{ id: clientRole.id, name: clientRole.name }],
337
});
338

339
// Pattern 3: Assign roles to group (inherited by members)
340
await kcAdminClient.groups.addRealmRoleMappings({
341
  id: groupId,
342
  roles: [{ id: role.id, name: role.name }],
343
});
344

345
// Pattern 4: Create role hierarchy with composites
346
await kcAdminClient.roles.create({
347
  name: "manager",
348
  composite: true,
349
});
350

351
const userRole = await kcAdminClient.roles.findByName({ name: "user" });
352
const reportRole = await kcAdminClient.roles.findByName({ name: "view-reports" });
353

354
await kcAdminClient.roles.addCompositeRoles({
355
  name: "manager",
356
  roles: [userRole, reportRole],
357
});
358
```