0
# Identity Providers
1

2
External identity provider configuration including SAML, OIDC, and social login integrations.
3

4
## Capabilities
5

6
### Identity Provider CRUD Operations
7

8
Management of external identity providers for federated authentication.
9

10
```typescript { .api }
11
/**
12
 * Find all identity providers in the realm
13
 * @returns Array of identity provider representations
14
 */
15
find(): Promise<IdentityProviderRepresentation[]>;
16

17
/**
18
 * Create a new identity provider
19
 * @param identityProvider - Identity provider configuration
20
 */
21
create(identityProvider: IdentityProviderRepresentation): Promise<void>;
22

23
/**
24
 * Find a specific identity provider by alias
25
 * @param params - Identity provider alias
26
 * @returns Identity provider representation or undefined if not found
27
 */
28
findOne(params: { alias: string }): Promise<IdentityProviderRepresentation | undefined>;
29

30
/**
31
 * Update an existing identity provider
32
 * @param params - Identity provider alias
33
 * @param identityProvider - Updated configuration
34
 */
35
update(params: { alias: string }, identityProvider: IdentityProviderRepresentation): Promise<void>;
36

37
/**
38
 * Delete an identity provider
39
 * @param params - Identity provider alias
40
 */
41
del(params: { alias: string }): Promise<void>;
42
```
43

44
**Usage Examples:**
45

46
```typescript
47
// List all identity providers
48
const idps = await kcAdminClient.identityProviders.find();
49
console.log("Identity providers:", idps.map(idp => idp.alias));
50

51
// Create SAML identity provider
52
await kcAdminClient.identityProviders.create({
53
  alias: "corporate-saml",
54
  displayName: "Corporate SAML",
55
  providerId: "saml",
56
  enabled: true,
57
  storeToken: false,
58
  addReadTokenRoleOnCreate: false,
59
  authenticateByDefault: false,
60
  linkOnly: false,
61
  trustEmail: true,
62
  firstBrokerLoginFlowAlias: "first broker login",
63
  config: {
64
    singleSignOnServiceUrl: "https://corporate.example.com/saml/sso",
65
    singleLogoutServiceUrl: "https://corporate.example.com/saml/slo",
66
    nameIDPolicyFormat: "urn:oasis:names:tc:SAML:2.0:nameid-format:persistent",
67
    principalType: "SUBJECT",
68
    signatureAlgorithm: "RSA_SHA256",
69
    xmlSigKeyInfoKeyNameTransformer: "KEY_ID",
70
  },
71
});
72

73
// Create OIDC identity provider
74
await kcAdminClient.identityProviders.create({
75
  alias: "google-oidc",
76
  displayName: "Google",
77
  providerId: "oidc",
78
  enabled: true,
79
  trustEmail: true,
80
  config: {
81
    clientId: "google-client-id",
82
    clientSecret: "google-client-secret",
83
    authorizationUrl: "https://accounts.google.com/o/oauth2/v2/auth",
84
    tokenUrl: "https://oauth2.googleapis.com/token",
85
    userInfoUrl: "https://openidconnect.googleapis.com/v1/userinfo",
86
    issuer: "https://accounts.google.com",
87
    defaultScope: "openid profile email",
88
  },
89
});
90

91
// Get specific identity provider
92
const samlIdp = await kcAdminClient.identityProviders.findOne({
93
  alias: "corporate-saml",
94
});
95

96
// Update identity provider
97
await kcAdminClient.identityProviders.update(
98
  { alias: "corporate-saml" },
99
  {
100
    enabled: false, // Temporarily disable
101
    config: {
102
      singleSignOnServiceUrl: "https://new-corporate.example.com/saml/sso",
103
    },
104
  }
105
);
106

107
// Delete identity provider
108
await kcAdminClient.identityProviders.del({ alias: "old-provider" });
109
```
110

111
### Identity Provider Mappers
112

113
Configuration of attribute and role mappings from external identity providers.
114

115
```typescript { .api }
116
/**
117
 * Find all mappers for an identity provider
118
 * @param params - Identity provider alias
119
 * @returns Array of mapper representations
120
 */
121
findMappers(params: { alias: string }): Promise<IdentityProviderMapperRepresentation[]>;
122

123
/**
124
 * Create a new mapper for an identity provider
125
 * @param params - Identity provider alias
126
 * @param mapper - Mapper configuration
127
 * @returns Created mapper representation
128
 */
129
createMapper(params: {
130
  alias: string;
131
}, mapper: IdentityProviderMapperRepresentation): Promise<IdentityProviderMapperRepresentation>;
132

133
/**
134
 * Find a specific mapper by ID
135
 * @param params - Identity provider alias and mapper ID
136
 * @returns Mapper representation or undefined if not found
137
 */
138
findMapper(params: {
139
  alias: string;
140
  id: string;
141
}): Promise<IdentityProviderMapperRepresentation | undefined>;
142

143
/**
144
 * Update an existing mapper
145
 * @param params - Identity provider alias and mapper ID
146
 * @param mapper - Updated mapper configuration
147
 */
148
updateMapper(params: {
149
  alias: string;
150
  id: string;
151
}, mapper: IdentityProviderMapperRepresentation): Promise<void>;
152

153
/**
154
 * Delete a mapper
155
 * @param params - Identity provider alias and mapper ID
156
 */
157
delMapper(params: { alias: string; id: string }): Promise<void>;
158
```
159

160
**Usage Examples:**
161

162
```typescript
163
// List all mappers for an identity provider
164
const mappers = await kcAdminClient.identityProviders.findMappers({
165
  alias: "corporate-saml",
166
});
167

168
console.log("SAML mappers:", mappers.map(m => m.name));
169

170
// Create attribute mapper
171
const emailMapper = await kcAdminClient.identityProviders.createMapper(
172
  { alias: "corporate-saml" },
173
  {
174
    name: "email-mapper",
175
    identityProviderMapper: "saml-user-attribute-idp-mapper",
176
    config: {
177
      "attribute.name": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress",
178
      "user.attribute": "email",
179
    },
180
  }
181
);
182

183
// Create role mapper
184
await kcAdminClient.identityProviders.createMapper(
185
  { alias: "corporate-saml" },
186
  {
187
    name: "admin-role-mapper",
188
    identityProviderMapper: "saml-role-idp-mapper",
189
    config: {
190
      "attribute.name": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/role",
191
      "attribute.value": "Administrator",
192
      "role": "admin",
193
    },
194
  }
195
);
196

197
// Create username template mapper
198
await kcAdminClient.identityProviders.createMapper(
199
  { alias: "google-oidc" },
200
  {
201
    name: "username-template",
202
    identityProviderMapper: "oidc-username-idp-mapper",
203
    config: {
204
      template: "${CLAIM.preferred_username}@google",
205
    },
206
  }
207
);
208

209
// Update mapper
210
await kcAdminClient.identityProviders.updateMapper(
211
  { alias: "corporate-saml", id: emailMapper.id! },
212
  {
213
    config: {
214
      "attribute.name": "email",
215
      "user.attribute": "email",
216
      "attribute.friendly.name": "Email Address",
217
    },
218
  }
219
);
220

221
// Delete mapper
222
await kcAdminClient.identityProviders.delMapper({
223
  alias: "corporate-saml",
224
  id: "mapper-id-to-delete",
225
});
226
```
227

228
### Social Identity Providers
229

230
Configuration of popular social login providers with predefined settings.
231

232
```typescript { .api }
233
/**
234
 * Social identity providers have predefined configurations
235
 * Use specific providerId values for social providers:
236
 * - "google" for Google
237
 * - "github" for GitHub  
238
 * - "facebook" for Facebook
239
 * - "twitter" for Twitter
240
 * - "linkedin" for LinkedIn
241
 * - "microsoft" for Microsoft
242
 * - "stackoverflow" for Stack Overflow
243
 */
244
```
245

246
**Usage Examples:**
247

248
```typescript
249
// GitHub social provider
250
await kcAdminClient.identityProviders.create({
251
  alias: "github",
252
  displayName: "GitHub",
253
  providerId: "github",
254
  enabled: true,
255
  trustEmail: false,
256
  config: {
257
    clientId: "github-oauth-app-id",
258
    clientSecret: "github-oauth-app-secret",
259
    defaultScope: "user:email",
260
  },
261
});
262

263
// Google social provider
264
await kcAdminClient.identityProviders.create({
265
  alias: "google",
266
  displayName: "Google",
267
  providerId: "google",
268
  enabled: true,
269
  trustEmail: true,
270
  config: {
271
    clientId: "google-oauth-client-id.apps.googleusercontent.com",
272
    clientSecret: "google-oauth-client-secret",
273
    defaultScope: "openid profile email",
274
    hostedDomain: "mycompany.com", // Optional: restrict to specific domain
275
  },
276
});
277

278
// Microsoft social provider
279
await kcAdminClient.identityProviders.create({
280
  alias: "microsoft",
281
  displayName: "Microsoft",
282
  providerId: "microsoft",
283
  enabled: true,
284
  trustEmail: true,
285
  config: {
286
    clientId: "azure-ad-application-id",
287
    clientSecret: "azure-ad-client-secret",
288
    defaultScope: "openid profile email",
289
  },
290
});
291

292
// Facebook social provider
293
await kcAdminClient.identityProviders.create({
294
  alias: "facebook",
295
  displayName: "Facebook",
296
  providerId: "facebook",
297
  enabled: true,
298
  trustEmail: false, // Facebook email may not be verified
299
  config: {
300
    clientId: "facebook-app-id",
301
    clientSecret: "facebook-app-secret",
302
    defaultScope: "public_profile,email",
303
  },
304
});
305
```
306

307
### Advanced Configuration
308

309
Advanced identity provider features and configurations.
310

311
```typescript { .api }
312
/**
313
 * Import identity provider configuration from metadata
314
 * @param params - Identity provider alias
315
 * @param metadata - SAML metadata or OIDC discovery document
316
 */
317
importConfig(params: { alias: string }, metadata: string): Promise<Record<string, any>>;
318

319
/**
320
 * Export identity provider configuration
321
 * @param params - Identity provider alias and format
322
 * @returns Configuration in requested format
323
 */
324
exportConfig(params: {
325
  alias: string;
326
  format?: "saml-idp-descriptor" | "saml-sp-descriptor";
327
}): Promise<string>;
328
```
329

330
**Usage Examples:**
331

332
```typescript
333
// Import SAML metadata
334
const samlMetadata = `<?xml version="1.0"?>
335
<EntityDescriptor xmlns="urn:oasis:names:tc:SAML:2.0:metadata" entityID="https://example.com">
336
  <!-- SAML metadata content -->
337
</EntityDescriptor>`;
338

339
const importedConfig = await kcAdminClient.identityProviders.importConfig(
340
  { alias: "imported-saml" },
341
  samlMetadata
342
);
343

344
// Create identity provider with imported config
345
await kcAdminClient.identityProviders.create({
346
  alias: "imported-saml",
347
  providerId: "saml",
348
  config: importedConfig,
349
});
350

351
// Export SP metadata for external IdP configuration
352
const spMetadata = await kcAdminClient.identityProviders.exportConfig({
353
  alias: "corporate-saml",
354
  format: "saml-sp-descriptor",
355
});
356

357
console.log("SP Metadata for external IdP:", spMetadata);
358
```
359

360
## Types
361

362
```typescript { .api }
363
/**
364
 * Identity provider representation
365
 */
366
interface IdentityProviderRepresentation {
367
  /** Identity provider alias (unique identifier) */
368
  alias?: string;
369
  /** Display name shown to users */
370
  displayName?: string;
371
  /** Provider type (saml, oidc, google, github, etc.) */
372
  providerId?: string;
373
  /** Whether provider is enabled */
374
  enabled?: boolean;
375
  /** Whether to update profile on first login */
376
  updateProfileFirstLogin?: boolean;
377
  /** Whether to trust email from provider */
378
  trustEmail?: boolean;
379
  /** Whether to store external tokens */
380
  storeToken?: boolean;
381
  /** Whether to add read token role on user creation */
382
  addReadTokenRoleOnCreate?: boolean;
383
  /** Whether to authenticate by default */
384
  authenticateByDefault?: boolean;
385
  /** Whether this provider is for linking only */
386
  linkOnly?: boolean;
387
  /** First broker login flow alias */
388
  firstBrokerLoginFlowAlias?: string;
389
  /** Post broker login flow alias */
390
  postBrokerLoginFlowAlias?: string;
391
  /** Provider-specific configuration */
392
  config?: Record<string, string>;
393
}
394

395
/**
396
 * Identity provider mapper representation
397
 */
398
interface IdentityProviderMapperRepresentation {
399
  /** Mapper unique identifier */
400
  id?: string;
401
  /** Mapper name */
402
  name?: string;
403
  /** Identity provider alias */
404
  identityProviderAlias?: string;
405
  /** Mapper type */
406
  identityProviderMapper?: string;
407
  /** Mapper configuration */
408
  config?: Record<string, string>;
409
}
410
```
411

412
## Identity Provider Integration Patterns
413

414
Common patterns for identity provider integration:
415

416
```typescript
417
// Pattern 1: Enterprise SAML integration
418
await kcAdminClient.identityProviders.create({
419
  alias: "corporate-saml",
420
  displayName: "Corporate SSO",
421
  providerId: "saml",
422
  enabled: true,
423
  trustEmail: true,
424
  firstBrokerLoginFlowAlias: "first broker login",
425
  config: {
426
    singleSignOnServiceUrl: "https://corporate.example.com/saml/sso",
427
    singleLogoutServiceUrl: "https://corporate.example.com/saml/slo",
428
    nameIDPolicyFormat: "urn:oasis:names:tc:SAML:2.0:nameid-format:persistent",
429
    wantAssertionsSigned: "true",
430
    wantAuthnRequestsSigned: "true",
431
    signatureAlgorithm: "RSA_SHA256",
432
    signingCertificate: "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----",
433
  },
434
});
435

436
// Add attribute mappers
437
const mappers = [
438
  {
439
    name: "email",
440
    identityProviderMapper: "saml-user-attribute-idp-mapper",
441
    config: {
442
      "attribute.name": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress",
443
      "user.attribute": "email",
444
    },
445
  },
446
  {
447
    name: "firstName",
448
    identityProviderMapper: "saml-user-attribute-idp-mapper",
449
    config: {
450
      "attribute.name": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname",
451
      "user.attribute": "firstName",
452
    },
453
  },
454
  {
455
    name: "lastName", 
456
    identityProviderMapper: "saml-user-attribute-idp-mapper",
457
    config: {
458
      "attribute.name": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname",
459
      "user.attribute": "lastName",
460
    },
461
  },
462
];
463

464
for (const mapper of mappers) {
465
  await kcAdminClient.identityProviders.createMapper(
466
    { alias: "corporate-saml" },
467
    mapper
468
  );
469
}
470

471
// Pattern 2: Multiple social providers
472
const socialProviders = [
473
  {
474
    alias: "google",
475
    displayName: "Google",
476
    providerId: "google",
477
    config: {
478
      clientId: process.env.GOOGLE_CLIENT_ID,
479
      clientSecret: process.env.GOOGLE_CLIENT_SECRET,
480
    },
481
  },
482
  {
483
    alias: "github",
484
    displayName: "GitHub", 
485
    providerId: "github",
486
    config: {
487
      clientId: process.env.GITHUB_CLIENT_ID,
488
      clientSecret: process.env.GITHUB_CLIENT_SECRET,
489
    },
490
  },
491
];
492

493
for (const provider of socialProviders) {
494
  await kcAdminClient.identityProviders.create({
495
    ...provider,
496
    enabled: true,
497
    trustEmail: provider.providerId === "google",
498
  });
499
}
500
```