0
# Client Management
1

2
The Clients resource provides comprehensive functionality for managing OAuth2/OIDC client applications, including client configuration, roles, authorization policies, protocol mappers, and service accounts.
3

4
## Capabilities
5

6
### Client CRUD Operations
7

8
Basic client lifecycle management including creation, retrieval, updates, and deletion.
9

10
```typescript { .api }
11
/**
12
 * Client query interface for filtering and pagination
13
 */
14
interface ClientQuery extends PaginatedQuery {
15
  /** Filter by client ID */
16
  clientId?: string;
17
  /** Only return viewable clients */
18
  viewableOnly?: boolean;
19
  /** Enable search mode */
20
  search?: boolean;
21
  /** Query string for search */
22
  q?: string;
23
}
24

25
interface PaginatedQuery {
26
  /** Starting index for pagination (0-based) */
27
  first?: number;
28
  /** Maximum number of results to return */
29
  max?: number;
30
}
31

32
/**
33
 * Find clients with optional filtering and pagination
34
 * @param query - Optional query parameters for filtering clients
35
 * @returns Array of client representations
36
 */
37
find(query?: ClientQuery): Promise<ClientRepresentation[]>;
38

39
/**
40
 * Create a new client
41
 * @param client - Client representation with client details
42
 * @returns Object containing the ID of the created client
43
 */
44
create(client: ClientRepresentation): Promise<{ id: string }>;
45

46
/**
47
 * Get a single client by ID
48
 * @param params - Parameters including client ID
49
 * @returns Client representation or undefined if not found
50
 */
51
findOne(params: { id: string }): Promise<ClientRepresentation | undefined>;
52

53
/**
54
 * Update an existing client
55
 * @param query - Query containing client ID
56
 * @param client - Updated client representation
57
 */
58
update(query: { id: string }, client: ClientRepresentation): Promise<void>;
59

60
/**
61
 * Delete a client
62
 * @param params - Parameters containing client ID
63
 */
64
del(params: { id: string }): Promise<void>;
65
```
66

67
**Usage Examples:**
68

69
```typescript
70
// Find all clients
71
const clients = await kcAdminClient.clients.find();
72

73
// Search for specific client
74
const myClients = await kcAdminClient.clients.find({
75
  clientId: "my-app",
76
});
77

78
// Create OAuth2 confidential client
79
const { id } = await kcAdminClient.clients.create({
80
  clientId: "my-oauth-client",
81
  name: "My OAuth2 Application",
82
  enabled: true,
83
  publicClient: false,
84
  standardFlowEnabled: true,
85
  directAccessGrantsEnabled: true,
86
  serviceAccountsEnabled: true,
87
  redirectUris: ["https://myapp.com/callback"],
88
  webOrigins: ["https://myapp.com"],
89
  protocol: "openid-connect",
90
});
91

92
// Update client configuration
93
await kcAdminClient.clients.update({ id }, {
94
  description: "Updated OAuth2 client",
95
  baseUrl: "https://myapp.com",
96
  adminUrl: "https://myapp.com/admin",
97
});
98

99
// Get client details
100
const client = await kcAdminClient.clients.findOne({ id });
101
```
102

103
### Client Representation
104

105
Complete TypeScript interface for client configuration.
106

107
```typescript { .api }
108
/**
109
 * Complete client representation with all OAuth2/OIDC configuration options
110
 */
111
interface ClientRepresentation {
112
  /** Access control permissions */
113
  access?: Record<string, boolean>;
114
  /** Admin URL for client callbacks */
115
  adminUrl?: string;
116
  /** Custom client attributes */
117
  attributes?: Record<string, any>;
118
  /** Authentication flow binding overrides */
119
  authenticationFlowBindingOverrides?: Record<string, any>;
120
  /** Enable authorization services (UMA) */
121
  authorizationServicesEnabled?: boolean;
122
  /** Authorization server settings */
123
  authorizationSettings?: ResourceServerRepresentation;
124
  /** Base URL for client */
125
  baseUrl?: string;
126
  /** Bearer-only client (no login redirect) */
127
  bearerOnly?: boolean;
128
  /** Client authenticator type */
129
  clientAuthenticatorType?: string;
130
  /** Unique client identifier */
131
  clientId?: string;
132
  /** Require user consent */
133
  consentRequired?: boolean;
134
  /** Default client scopes */
135
  defaultClientScopes?: string[];
136
  /** Default roles for new users */
137
  defaultRoles?: string[];
138
  /** Client description */
139
  description?: string;
140
  /** Enable direct access grants (Resource Owner Password Credentials) */
141
  directAccessGrantsEnabled?: boolean;
142
  /** Whether client is enabled */
143
  enabled?: boolean;
144
  /** Always display in admin console */
145
  alwaysDisplayInConsole?: boolean;
146
  /** Enable frontchannel logout */
147
  frontchannelLogout?: boolean;
148
  /** Allow full scope mappings */
149
  fullScopeAllowed?: boolean;
150
  /** Unique client UUID */
151
  id?: string;
152
  /** Enable implicit flow */
153
  implicitFlowEnabled?: boolean;
154
  /** Client display name */
155
  name?: string;
156
  /** Node re-registration timeout */
157
  nodeReRegistrationTimeout?: number;
158
  /** Not-before policy timestamp */
159
  notBefore?: number;
160
  /** Optional client scopes */
161
  optionalClientScopes?: string[];
162
  /** Origin information */
163
  origin?: string;
164
  /** Protocol type (openid-connect, saml) */
165
  protocol?: string;
166
  /** Protocol mappers configuration */
167
  protocolMappers?: ProtocolMapperRepresentation[];
168
  /** Public client (no client secret) */
169
  publicClient?: boolean;
170
  /** Valid redirect URIs */
171
  redirectUris?: string[];
172
  /** Registered cluster nodes */
173
  registeredNodes?: Record<string, any>;
174
  /** Registration access token */
175
  registrationAccessToken?: string;
176
  /** Root URL for relative URIs */
177
  rootUrl?: string;
178
  /** Client secret (for confidential clients) */
179
  secret?: string;
180
  /** Enable service accounts */
181
  serviceAccountsEnabled?: boolean;
182
  /** Enable standard flow (Authorization Code) */
183
  standardFlowEnabled?: boolean;
184
  /** Surrogate auth required */
185
  surrogateAuthRequired?: boolean;
186
  /** Valid web origins for CORS */
187
  webOrigins?: string[];
188
}
189
```
190

191
### Client Types Examples
192

193
Different client configuration patterns for common use cases.
194

195
```typescript
196
// Public SPA client
197
await kcAdminClient.clients.create({
198
  clientId: "spa-app",
199
  name: "Single Page Application",
200
  enabled: true,
201
  publicClient: true,
202
  standardFlowEnabled: true,
203
  implicitFlowEnabled: false,
204
  directAccessGrantsEnabled: false,
205
  redirectUris: ["https://spa.example.com/*"],
206
  webOrigins: ["https://spa.example.com"],
207
  protocol: "openid-connect",
208
});
209

210
// Confidential server-side client
211
await kcAdminClient.clients.create({
212
  clientId: "backend-service",
213
  name: "Backend Service",
214
  enabled: true,
215
  publicClient: false,
216
  standardFlowEnabled: true,
217
  directAccessGrantsEnabled: true,
218
  serviceAccountsEnabled: true,
219
  redirectUris: ["https://backend.example.com/callback"],
220
  webOrigins: ["https://backend.example.com"],
221
  protocol: "openid-connect",
222
});
223

224
// Machine-to-machine client (service account only)
225
await kcAdminClient.clients.create({
226
  clientId: "m2m-service",
227
  name: "Machine to Machine Service",
228
  enabled: true,
229
  publicClient: false,
230
  serviceAccountsEnabled: true,
231
  standardFlowEnabled: false,
232
  implicitFlowEnabled: false,
233
  directAccessGrantsEnabled: false,
234
  protocol: "openid-connect",
235
});
236

237
// Bearer-only resource server
238
await kcAdminClient.clients.create({
239
  clientId: "api-server",
240
  name: "API Resource Server",
241
  enabled: true,
242
  bearerOnly: true,
243
  protocol: "openid-connect",
244
});
245
```
246

247
### Client Roles Management
248

249
Management of client-specific roles for fine-grained access control.
250

251
```typescript { .api }
252
/**
253
 * Create a new role for the client
254
 * @param params - Client ID and role representation
255
 * @returns Object containing the role name
256
 */
257
createRole(params: { id: string; role: RoleRepresentation }): Promise<{ roleName: string }>;
258

259
/**
260
 * List all roles for a client
261
 * @param params - Parameters containing client ID
262
 * @returns Array of client role representations
263
 */
264
listRoles(params: { id: string }): Promise<RoleRepresentation[]>;
265

266
/**
267
 * Find a specific client role by name
268
 * @param params - Client ID and role name
269
 * @returns Role representation or null if not found
270
 */
271
findRole(params: { id: string; roleName: string }): Promise<RoleRepresentation | null>;
272

273
/**
274
 * Update an existing client role
275
 * @param query - Client ID and role name
276
 * @param role - Updated role representation
277
 */
278
updateRole(query: { id: string; roleName: string }, role: RoleRepresentation): Promise<void>;
279

280
/**
281
 * Delete a client role
282
 * @param params - Client ID and role name
283
 */
284
delRole(params: { id: string; roleName: string }): Promise<void>;
285

286
/**
287
 * Find users with specific client role
288
 * @param params - Client ID, role name, and pagination options
289
 * @returns Array of users with the specified role
290
 */
291
findUsersWithRole(params: {
292
  id: string;
293
  roleName: string;
294
  briefRepresentation?: boolean;
295
  first?: number;
296
  max?: number;
297
}): Promise<UserRepresentation[]>;
298
```
299

300
**Client Roles Examples:**
301

302
```typescript
303
// Create client roles
304
await kcAdminClient.clients.createRole({
305
  id: clientId,
306
  role: {
307
    name: "admin",
308
    description: "Administrator role for the client",
309
    composite: false,
310
  },
311
});
312

313
await kcAdminClient.clients.createRole({
314
  id: clientId,
315
  role: {
316
    name: "user",
317
    description: "Standard user role",
318
    composite: false,
319
  },
320
});
321

322
// List all client roles
323
const clientRoles = await kcAdminClient.clients.listRoles({ id: clientId });
324

325
// Find specific role
326
const adminRole = await kcAdminClient.clients.findRole({
327
  id: clientId,
328
  roleName: "admin",
329
});
330

331
// Find users with client role
332
const admins = await kcAdminClient.clients.findUsersWithRole({
333
  id: clientId,
334
  roleName: "admin",
335
  briefRepresentation: true,
336
});
337
```
338

339
### Service Account Management
340

341
Service account functionality for machine-to-machine authentication.
342

343
```typescript { .api }
344
/**
345
 * Get the service account user for a client
346
 * @param params - Parameters containing client ID
347
 * @returns User representation of the service account
348
 */
349
getServiceAccountUser(params: { id: string }): Promise<UserRepresentation>;
350
```
351

352
**Service Account Example:**
353

354
```typescript
355
// Get service account user
356
const serviceAccount = await kcAdminClient.clients.getServiceAccountUser({
357
  id: clientId,
358
});
359

360
// Use the service account user ID for role mappings
361
await kcAdminClient.users.addRealmRoleMappings({
362
  id: serviceAccount.id!,
363
  roles: [{ id: "realm-role-id", name: "service-role" }],
364
});
365
```
366

367
### Client Secret Management
368

369
Client secret generation and management for confidential clients.
370

371
```typescript { .api }
372
/**
373
 * Generate a new client secret
374
 * @param params - Parameters containing client ID
375
 * @returns New credential representation with secret
376
 */
377
generateNewClientSecret(params: { id: string }): Promise<CredentialRepresentation>;
378

379
/**
380
 * Get current client secret
381
 * @param params - Parameters containing client ID
382
 * @returns Current credential representation
383
 */
384
getClientSecret(params: { id: string }): Promise<CredentialRepresentation>;
385
```
386

387
**Client Secret Examples:**
388

389
```typescript
390
// Generate new client secret
391
const newSecret = await kcAdminClient.clients.generateNewClientSecret({
392
  id: clientId,
393
});
394
console.log("New secret:", newSecret.value);
395

396
// Get current secret
397
const currentSecret = await kcAdminClient.clients.getClientSecret({
398
  id: clientId,
399
});
400
```
401

402
### Client Scopes Management
403

404
Management of client scope assignments for OAuth2 scope-based access control.
405

406
```typescript { .api }
407
/**
408
 * Get default client scopes for a client
409
 * @param params - Parameters containing client ID
410
 * @returns Array of default client scopes
411
 */
412
listDefaultClientScopes(params: { id: string }): Promise<ClientScopeRepresentation[]>;
413

414
/**
415
 * Add default client scope to client
416
 * @param params - Client ID and client scope ID
417
 */
418
addDefaultClientScope(params: { id: string; clientScopeId: string }): Promise<void>;
419

420
/**
421
 * Remove default client scope from client
422
 * @param params - Client ID and client scope ID
423
 */
424
delDefaultClientScope(params: { id: string; clientScopeId: string }): Promise<void>;
425

426
/**
427
 * Get optional client scopes for a client
428
 * @param params - Parameters containing client ID
429
 * @returns Array of optional client scopes
430
 */
431
listOptionalClientScopes(params: { id: string }): Promise<ClientScopeRepresentation[]>;
432

433
/**
434
 * Add optional client scope to client
435
 * @param params - Client ID and client scope ID
436
 */
437
addOptionalClientScope(params: { id: string; clientScopeId: string }): Promise<void>;
438

439
/**
440
 * Remove optional client scope from client
441
 * @param params - Client ID and client scope ID
442
 */
443
delOptionalClientScope(params: { id: string; clientScopeId: string }): Promise<void>;
444
```
445

446
### Protocol Mappers
447

448
Protocol mapper management for customizing token content and SAML assertions.
449

450
```typescript { .api }
451
/**
452
 * Create protocol mapper for client
453
 * @param params - Client ID and protocol mapper configuration
454
 * @returns Created protocol mapper ID
455
 */
456
addProtocolMapper(params: { id: string; mapper: ProtocolMapperRepresentation }): Promise<{ id: string }>;
457

458
/**
459
 * List protocol mappers for client
460
 * @param params - Parameters containing client ID
461
 * @returns Array of protocol mapper representations
462
 */
463
listProtocolMappers(params: { id: string }): Promise<ProtocolMapperRepresentation[]>;
464

465
/**
466
 * Find protocol mapper by ID
467
 * @param params - Client ID and mapper ID
468
 * @returns Protocol mapper representation or undefined
469
 */
470
findProtocolMapperById(params: { id: string; mapperId: string }): Promise<ProtocolMapperRepresentation | undefined>;
471

472
/**
473
 * Update protocol mapper
474
 * @param query - Client ID and mapper ID
475
 * @param mapper - Updated protocol mapper representation
476
 */
477
updateProtocolMapper(query: { id: string; mapperId: string }, mapper: ProtocolMapperRepresentation): Promise<void>;
478

479
/**
480
 * Delete protocol mapper
481
 * @param params - Client ID and mapper ID
482
 */
483
delProtocolMapper(params: { id: string; mapperId: string }): Promise<void>;
484
```
485

486
**Protocol Mapper Examples:**
487

488
```typescript
489
// Add audience mapper for JWT tokens
490
await kcAdminClient.clients.addProtocolMapper({
491
  id: clientId,
492
  mapper: {
493
    name: "audience-mapper",
494
    protocol: "openid-connect",
495
    protocolMapper: "oidc-audience-mapper",
496
    config: {
497
      "included.client.audience": "my-api",
498
      "access.token.claim": "true",
499
    },
500
  },
501
});
502

503
// Add custom claim mapper
504
await kcAdminClient.clients.addProtocolMapper({
505
  id: clientId,
506
  mapper: {
507
    name: "department-mapper",
508
    protocol: "openid-connect",
509
    protocolMapper: "oidc-usermodel-attribute-mapper",
510
    config: {
511
      "user.attribute": "department",
512
      "claim.name": "department",
513
      "access.token.claim": "true",
514
      "id.token.claim": "true",
515
      "userinfo.token.claim": "true",
516
    },
517
  },
518
});
519
```
520

521
### Installation Adapters
522

523
Generate client installation/configuration files for various platforms.
524

525
```typescript { .api }
526
/**
527
 * Get installation/configuration for client adapter
528
 * @param params - Client ID and provider ID
529
 * @returns Installation configuration string
530
 */
531
getInstallationProvider(params: { 
532
  id: string; 
533
  providerId: string; 
534
}): Promise<string>;
535
```
536

537
**Installation Examples:**
538

539
```typescript
540
// Get keycloak.json for JavaScript adapter
541
const keycloakJson = await kcAdminClient.clients.getInstallationProvider({
542
  id: clientId,
543
  providerId: "keycloak-oidc-keycloak-json",
544
});
545

546
// Get configuration for Spring Boot adapter
547
const springConfig = await kcAdminClient.clients.getInstallationProvider({
548
  id: clientId,
549
  providerId: "keycloak-oidc-jboss-subsystem",
550
});
551
```
552

553
### Session Management
554

555
Client-related session monitoring and management.
556

557
```typescript { .api }
558
/**
559
 * List user sessions for client
560
 * @param params - Client ID with optional pagination
561
 * @returns Array of user sessions for the client
562
 */
563
listSessions(params: { id: string; first?: number; max?: number }): Promise<UserSessionRepresentation[]>;
564

565
/**
566
 * Get offline sessions count for client
567
 * @param params - Parameters containing client ID
568
 * @returns Object containing the count of offline sessions
569
 */
570
getOfflineSessionCount(params: { id: string }): Promise<{ count: number }>;
571

572
/**
573
 * List offline sessions for client
574
 * @param params - Client ID with optional pagination
575
 * @returns Array of offline sessions
576
 */
577
listOfflineSessions(params: { id: string; first?: number; max?: number }): Promise<UserSessionRepresentation[]>;
578
```
579

580
### Node Registration
581

582
Cluster node registration for applications in clustered environments.
583

584
```typescript { .api }
585
/**
586
 * Register cluster node for client
587
 * @param params - Client ID and node information
588
 */
589
registerClusterNode(params: { id: string; node: Record<string, any> }): Promise<void>;
590

591
/**
592
 * Unregister cluster node for client
593
 * @param params - Parameters containing client ID
594
 */
595
unregisterClusterNode(params: { id: string }): Promise<void>;
596
```