0
# Client Scopes
1

2
Client scopes define sets of protocol mappers and roles that can be applied to clients for OpenID Connect and SAML protocols. They provide a way to manage claims, scopes, and roles in a reusable manner across multiple clients.
3

4
## Capabilities
5

6
### Client Scope Management
7

8
Core CRUD operations for managing client scopes.
9

10
```typescript { .api }
11
/**
12
 * List all client scopes in the realm
13
 * @returns Array of client scope representations
14
 */
15
find(): Promise<ClientScopeRepresentation[]>;
16

17
/**
18
 * Create a new client scope
19
 * @param clientScope - Client scope representation to create
20
 * @returns Object containing the new client scope ID
21
 */
22
create(clientScope: ClientScopeRepresentation): Promise<{ id: string }>;
23

24
/**
25
 * Find a client scope by ID
26
 * @param params - Parameters containing the client scope ID
27
 * @returns Client scope representation or undefined if not found
28
 */
29
findOne(params: { id: string }): Promise<ClientScopeRepresentation | undefined>;
30

31
/**
32
 * Update a client scope
33
 * @param query - Parameters containing the client scope ID
34
 * @param clientScope - Updated client scope representation
35
 * @returns void
36
 */
37
update(query: { id: string }, clientScope: ClientScopeRepresentation): Promise<void>;
38

39
/**
40
 * Delete a client scope
41
 * @param params - Parameters containing the client scope ID
42
 * @returns void
43
 */
44
del(params: { id: string }): Promise<void>;
45

46
/**
47
 * Find client scope by name
48
 * @param payload - Parameters containing realm and name
49
 * @returns Client scope representation or undefined if not found
50
 */
51
findOneByName(payload: { realm?: string; name: string }): Promise<ClientScopeRepresentation | undefined>;
52

53
/**
54
 * Delete client scope by name
55
 * @param payload - Parameters containing realm and name
56
 * @returns void
57
 */
58
delByName(payload: { realm?: string; name: string }): Promise<void>;
59
```
60

61
### Default Client Scopes
62

63
Manage default client scopes that are automatically applied to all clients.
64

65
```typescript { .api }
66
/**
67
 * List all default client scopes
68
 * @returns Array of default client scope representations
69
 */
70
listDefaultClientScopes(): Promise<ClientScopeRepresentation[]>;
71

72
/**
73
 * Add a client scope to default scopes
74
 * @param params - Parameters containing the client scope ID
75
 * @returns void
76
 */
77
addDefaultClientScope(params: { id: string }): Promise<void>;
78

79
/**
80
 * Remove a client scope from default scopes
81
 * @param params - Parameters containing the client scope ID
82
 * @returns void
83
 */
84
delDefaultClientScope(params: { id: string }): Promise<void>;
85
```
86

87
### Default Optional Client Scopes
88

89
Manage optional client scopes that are available but not automatically applied.
90

91
```typescript { .api }
92
/**
93
 * List all default optional client scopes
94
 * @returns Array of optional client scope representations
95
 */
96
listDefaultOptionalClientScopes(): Promise<ClientScopeRepresentation[]>;
97

98
/**
99
 * Add a client scope to default optional scopes
100
 * @param params - Parameters containing the client scope ID
101
 * @returns void
102
 */
103
addDefaultOptionalClientScope(params: { id: string }): Promise<void>;
104

105
/**
106
 * Remove a client scope from default optional scopes
107
 * @param params - Parameters containing the client scope ID
108
 * @returns void
109
 */
110
delDefaultOptionalClientScope(params: { id: string }): Promise<void>;
111
```
112

113
### Protocol Mappers
114

115
Manage protocol mappers that define how user information is mapped to tokens and assertions.
116

117
```typescript { .api }
118
/**
119
 * Add multiple protocol mappers to a client scope
120
 * @param query - Parameters containing the client scope ID
121
 * @param mappers - Array of protocol mapper representations
122
 * @returns void
123
 */
124
addMultipleProtocolMappers(query: { id: string }, mappers: ProtocolMapperRepresentation[]): Promise<void>;
125

126
/**
127
 * Add a single protocol mapper to a client scope
128
 * @param query - Parameters containing the client scope ID
129
 * @param mapper - Protocol mapper representation
130
 * @returns void
131
 */
132
addProtocolMapper(query: { id: string }, mapper: ProtocolMapperRepresentation): Promise<void>;
133

134
/**
135
 * List all protocol mappers for a client scope
136
 * @param params - Parameters containing the client scope ID
137
 * @returns Array of protocol mapper representations
138
 */
139
listProtocolMappers(params: { id: string }): Promise<ProtocolMapperRepresentation[]>;
140

141
/**
142
 * Find a specific protocol mapper by ID
143
 * @param params - Parameters containing client scope ID and mapper ID
144
 * @returns Protocol mapper representation or undefined if not found
145
 */
146
findProtocolMapper(params: { id: string; mapperId: string }): Promise<ProtocolMapperRepresentation | undefined>;
147

148
/**
149
 * Find protocol mappers by protocol type
150
 * @param params - Parameters containing client scope ID and protocol
151
 * @returns Array of protocol mapper representations
152
 */
153
findProtocolMappersByProtocol(params: { id: string; protocol: string }): Promise<ProtocolMapperRepresentation[]>;
154

155
/**
156
 * Update a protocol mapper
157
 * @param query - Parameters containing client scope ID and mapper ID
158
 * @param mapper - Updated protocol mapper representation
159
 * @returns void
160
 */
161
updateProtocolMapper(query: { id: string; mapperId: string }, mapper: ProtocolMapperRepresentation): Promise<void>;
162

163
/**
164
 * Delete a protocol mapper
165
 * @param params - Parameters containing client scope ID and mapper ID
166
 * @returns void
167
 */
168
delProtocolMapper(params: { id: string; mapperId: string }): Promise<void>;
169

170
/**
171
 * Find protocol mapper by name
172
 * @param payload - Parameters containing client scope ID, realm, and mapper name
173
 * @returns Protocol mapper representation or undefined if not found
174
 */
175
findProtocolMapperByName(payload: { realm?: string; id: string; name: string }): Promise<ProtocolMapperRepresentation | undefined>;
176
```
177

178
### Scope Mappings
179

180
Manage role mappings for client scopes.
181

182
```typescript { .api }
183
/**
184
 * List all scope mappings for a client scope
185
 * @param params - Parameters containing the client scope ID
186
 * @returns Mappings representation containing realm and client mappings
187
 */
188
listScopeMappings(params: { id: string }): Promise<MappingsRepresentation>;
189

190
/**
191
 * Add client role mappings to a client scope
192
 * @param query - Parameters containing client scope ID and client ID
193
 * @param roles - Array of roles to add
194
 * @returns void
195
 */
196
addClientScopeMappings(query: { id: string; client: string }, roles: RoleRepresentation[]): Promise<void>;
197

198
/**
199
 * List client role mappings for a client scope
200
 * @param params - Parameters containing client scope ID and client ID
201
 * @returns Array of role representations
202
 */
203
listClientScopeMappings(params: { id: string; client: string }): Promise<RoleRepresentation[]>;
204

205
/**
206
 * Add realm role mappings to a client scope
207
 * @param query - Parameters containing the client scope ID
208
 * @param roles - Array of roles to add
209
 * @returns void
210
 */
211
addRealmScopeMappings(query: { id: string }, roles: RoleRepresentation[]): Promise<void>;
212

213
/**
214
 * List realm role mappings for a client scope
215
 * @param params - Parameters containing the client scope ID
216
 * @returns Array of role representations
217
 */
218
listRealmScopeMappings(params: { id: string }): Promise<RoleRepresentation[]>;
219
```
220

221
## Usage Examples
222

223
```typescript
224
import KeycloakAdminClient from "@keycloak/keycloak-admin-client";
225

226
const kcAdminClient = new KeycloakAdminClient({
227
  baseUrl: 'http://localhost:8080',
228
  realmName: 'myrealm',
229
});
230

231
await kcAdminClient.auth({
232
  username: 'admin',
233
  password: 'admin',
234
  grantType: 'password',
235
  clientId: 'admin-cli',
236
});
237

238
// Create a client scope
239
const { id } = await kcAdminClient.clientScopes.create({
240
  name: 'custom-scope',
241
  description: 'Custom claims scope',
242
  protocol: 'openid-connect',
243
});
244

245
// Add a protocol mapper
246
await kcAdminClient.clientScopes.addProtocolMapper(
247
  { id },
248
  {
249
    name: 'department-mapper',
250
    protocol: 'openid-connect',
251
    protocolMapper: 'oidc-usermodel-attribute-mapper',
252
    config: {
253
      'user.attribute': 'department',
254
      'claim.name': 'department',
255
      'claim.value.type': 'String',
256
      'access.token.claim': 'true',
257
      'id.token.claim': 'true'
258
    }
259
  }
260
);
261

262
// Make it a default optional scope
263
await kcAdminClient.clientScopes.addDefaultOptionalClientScope({ id });
264

265
// List all client scopes
266
const scopes = await kcAdminClient.clientScopes.find();
267
```
268

269
## Types
270

271
```typescript { .api }
272
interface ClientScopeRepresentation {
273
  id?: string;
274
  name?: string;
275
  description?: string;
276
  protocol?: string;
277
  attributes?: Record<string, string>;
278
  protocolMappers?: ProtocolMapperRepresentation[];
279
}
280

281
interface ProtocolMapperRepresentation {
282
  id?: string;
283
  name?: string;
284
  protocol?: string;
285
  protocolMapper?: string;
286
  consentRequired?: boolean;
287
  config?: Record<string, string>;
288
}
289

290
interface MappingsRepresentation {
291
  realmMappings?: RoleRepresentation[];
292
  clientMappings?: Record<string, ClientMappingsRepresentation>;
293
}
294

295
interface ClientMappingsRepresentation {
296
  id?: string;
297
  client?: string;
298
  mappings?: RoleRepresentation[];
299
}
300
```