CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-keycloak--keycloak-admin-client

A comprehensive TypeScript client library for interacting with Keycloak's Administration API.

—

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

identity-providers.mddocs/

Identity Providers

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

Capabilities

Identity Provider CRUD Operations

Management of external identity providers for federated authentication.

/**
 * Find all identity providers in the realm
 * @returns Array of identity provider representations
 */
find(): Promise<IdentityProviderRepresentation[]>;

/**
 * Create a new identity provider
 * @param identityProvider - Identity provider configuration
 */
create(identityProvider: IdentityProviderRepresentation): Promise<void>;

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

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

/**
 * Delete an identity provider
 * @param params - Identity provider alias
 */
del(params: { alias: string }): Promise<void>;

Usage Examples:

// List all identity providers
const idps = await kcAdminClient.identityProviders.find();
console.log("Identity providers:", idps.map(idp => idp.alias));

// Create SAML identity provider
await kcAdminClient.identityProviders.create({
  alias: "corporate-saml",
  displayName: "Corporate SAML",
  providerId: "saml",
  enabled: true,
  storeToken: false,
  addReadTokenRoleOnCreate: false,
  authenticateByDefault: false,
  linkOnly: false,
  trustEmail: true,
  firstBrokerLoginFlowAlias: "first broker login",
  config: {
    singleSignOnServiceUrl: "https://corporate.example.com/saml/sso",
    singleLogoutServiceUrl: "https://corporate.example.com/saml/slo",
    nameIDPolicyFormat: "urn:oasis:names:tc:SAML:2.0:nameid-format:persistent",
    principalType: "SUBJECT",
    signatureAlgorithm: "RSA_SHA256",
    xmlSigKeyInfoKeyNameTransformer: "KEY_ID",
  },
});

// Create OIDC identity provider
await kcAdminClient.identityProviders.create({
  alias: "google-oidc",
  displayName: "Google",
  providerId: "oidc",
  enabled: true,
  trustEmail: true,
  config: {
    clientId: "google-client-id",
    clientSecret: "google-client-secret",
    authorizationUrl: "https://accounts.google.com/o/oauth2/v2/auth",
    tokenUrl: "https://oauth2.googleapis.com/token",
    userInfoUrl: "https://openidconnect.googleapis.com/v1/userinfo",
    issuer: "https://accounts.google.com",
    defaultScope: "openid profile email",
  },
});

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

// Update identity provider
await kcAdminClient.identityProviders.update(
  { alias: "corporate-saml" },
  {
    enabled: false, // Temporarily disable
    config: {
      singleSignOnServiceUrl: "https://new-corporate.example.com/saml/sso",
    },
  }
);

// Delete identity provider
await kcAdminClient.identityProviders.del({ alias: "old-provider" });

Identity Provider Mappers

Configuration of attribute and role mappings from external identity providers.

/**
 * Find all mappers for an identity provider
 * @param params - Identity provider alias
 * @returns Array of mapper representations
 */
findMappers(params: { alias: string }): Promise<IdentityProviderMapperRepresentation[]>;

/**
 * Create a new mapper for an identity provider
 * @param params - Identity provider alias
 * @param mapper - Mapper configuration
 * @returns Created mapper representation
 */
createMapper(params: {
  alias: string;
}, mapper: IdentityProviderMapperRepresentation): Promise<IdentityProviderMapperRepresentation>;

/**
 * Find a specific mapper by ID
 * @param params - Identity provider alias and mapper ID
 * @returns Mapper representation or undefined if not found
 */
findMapper(params: {
  alias: string;
  id: string;
}): Promise<IdentityProviderMapperRepresentation | undefined>;

/**
 * Update an existing mapper
 * @param params - Identity provider alias and mapper ID
 * @param mapper - Updated mapper configuration
 */
updateMapper(params: {
  alias: string;
  id: string;
}, mapper: IdentityProviderMapperRepresentation): Promise<void>;

/**
 * Delete a mapper
 * @param params - Identity provider alias and mapper ID
 */
delMapper(params: { alias: string; id: string }): Promise<void>;

Usage Examples:

// List all mappers for an identity provider
const mappers = await kcAdminClient.identityProviders.findMappers({
  alias: "corporate-saml",
});

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

// Create attribute mapper
const emailMapper = await kcAdminClient.identityProviders.createMapper(
  { alias: "corporate-saml" },
  {
    name: "email-mapper",
    identityProviderMapper: "saml-user-attribute-idp-mapper",
    config: {
      "attribute.name": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress",
      "user.attribute": "email",
    },
  }
);

// Create role mapper
await kcAdminClient.identityProviders.createMapper(
  { alias: "corporate-saml" },
  {
    name: "admin-role-mapper",
    identityProviderMapper: "saml-role-idp-mapper",
    config: {
      "attribute.name": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/role",
      "attribute.value": "Administrator",
      "role": "admin",
    },
  }
);

// Create username template mapper
await kcAdminClient.identityProviders.createMapper(
  { alias: "google-oidc" },
  {
    name: "username-template",
    identityProviderMapper: "oidc-username-idp-mapper",
    config: {
      template: "${CLAIM.preferred_username}@google",
    },
  }
);

// Update mapper
await kcAdminClient.identityProviders.updateMapper(
  { alias: "corporate-saml", id: emailMapper.id! },
  {
    config: {
      "attribute.name": "email",
      "user.attribute": "email",
      "attribute.friendly.name": "Email Address",
    },
  }
);

// Delete mapper
await kcAdminClient.identityProviders.delMapper({
  alias: "corporate-saml",
  id: "mapper-id-to-delete",
});

Social Identity Providers

Configuration of popular social login providers with predefined settings.

/**
 * Social identity providers have predefined configurations
 * Use specific providerId values for social providers:
 * - "google" for Google
 * - "github" for GitHub  
 * - "facebook" for Facebook
 * - "twitter" for Twitter
 * - "linkedin" for LinkedIn
 * - "microsoft" for Microsoft
 * - "stackoverflow" for Stack Overflow
 */

Usage Examples:

// GitHub social provider
await kcAdminClient.identityProviders.create({
  alias: "github",
  displayName: "GitHub",
  providerId: "github",
  enabled: true,
  trustEmail: false,
  config: {
    clientId: "github-oauth-app-id",
    clientSecret: "github-oauth-app-secret",
    defaultScope: "user:email",
  },
});

// Google social provider
await kcAdminClient.identityProviders.create({
  alias: "google",
  displayName: "Google",
  providerId: "google",
  enabled: true,
  trustEmail: true,
  config: {
    clientId: "google-oauth-client-id.apps.googleusercontent.com",
    clientSecret: "google-oauth-client-secret",
    defaultScope: "openid profile email",
    hostedDomain: "mycompany.com", // Optional: restrict to specific domain
  },
});

// Microsoft social provider
await kcAdminClient.identityProviders.create({
  alias: "microsoft",
  displayName: "Microsoft",
  providerId: "microsoft",
  enabled: true,
  trustEmail: true,
  config: {
    clientId: "azure-ad-application-id",
    clientSecret: "azure-ad-client-secret",
    defaultScope: "openid profile email",
  },
});

// Facebook social provider
await kcAdminClient.identityProviders.create({
  alias: "facebook",
  displayName: "Facebook",
  providerId: "facebook",
  enabled: true,
  trustEmail: false, // Facebook email may not be verified
  config: {
    clientId: "facebook-app-id",
    clientSecret: "facebook-app-secret",
    defaultScope: "public_profile,email",
  },
});

Advanced Configuration

Advanced identity provider features and configurations.

/**
 * Import identity provider configuration from metadata
 * @param params - Identity provider alias
 * @param metadata - SAML metadata or OIDC discovery document
 */
importConfig(params: { alias: string }, metadata: string): Promise<Record<string, any>>;

/**
 * Export identity provider configuration
 * @param params - Identity provider alias and format
 * @returns Configuration in requested format
 */
exportConfig(params: {
  alias: string;
  format?: "saml-idp-descriptor" | "saml-sp-descriptor";
}): Promise<string>;

Usage Examples:

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

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

// Create identity provider with imported config
await kcAdminClient.identityProviders.create({
  alias: "imported-saml",
  providerId: "saml",
  config: importedConfig,
});

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

console.log("SP Metadata for external IdP:", spMetadata);

Types

/**
 * Identity provider representation
 */
interface IdentityProviderRepresentation {
  /** Identity provider alias (unique identifier) */
  alias?: string;
  /** Display name shown to users */
  displayName?: string;
  /** Provider type (saml, oidc, google, github, etc.) */
  providerId?: string;
  /** Whether provider is enabled */
  enabled?: boolean;
  /** Whether to update profile on first login */
  updateProfileFirstLogin?: boolean;
  /** Whether to trust email from provider */
  trustEmail?: boolean;
  /** Whether to store external tokens */
  storeToken?: boolean;
  /** Whether to add read token role on user creation */
  addReadTokenRoleOnCreate?: boolean;
  /** Whether to authenticate by default */
  authenticateByDefault?: boolean;
  /** Whether this provider is for linking only */
  linkOnly?: boolean;
  /** First broker login flow alias */
  firstBrokerLoginFlowAlias?: string;
  /** Post broker login flow alias */
  postBrokerLoginFlowAlias?: string;
  /** Provider-specific configuration */
  config?: Record<string, string>;
}

/**
 * Identity provider mapper representation
 */
interface IdentityProviderMapperRepresentation {
  /** Mapper unique identifier */
  id?: string;
  /** Mapper name */
  name?: string;
  /** Identity provider alias */
  identityProviderAlias?: string;
  /** Mapper type */
  identityProviderMapper?: string;
  /** Mapper configuration */
  config?: Record<string, string>;
}

Identity Provider Integration Patterns

Common patterns for identity provider integration:

// Pattern 1: Enterprise SAML integration
await kcAdminClient.identityProviders.create({
  alias: "corporate-saml",
  displayName: "Corporate SSO",
  providerId: "saml",
  enabled: true,
  trustEmail: true,
  firstBrokerLoginFlowAlias: "first broker login",
  config: {
    singleSignOnServiceUrl: "https://corporate.example.com/saml/sso",
    singleLogoutServiceUrl: "https://corporate.example.com/saml/slo",
    nameIDPolicyFormat: "urn:oasis:names:tc:SAML:2.0:nameid-format:persistent",
    wantAssertionsSigned: "true",
    wantAuthnRequestsSigned: "true",
    signatureAlgorithm: "RSA_SHA256",
    signingCertificate: "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----",
  },
});

// Add attribute mappers
const mappers = [
  {
    name: "email",
    identityProviderMapper: "saml-user-attribute-idp-mapper",
    config: {
      "attribute.name": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress",
      "user.attribute": "email",
    },
  },
  {
    name: "firstName",
    identityProviderMapper: "saml-user-attribute-idp-mapper",
    config: {
      "attribute.name": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname",
      "user.attribute": "firstName",
    },
  },
  {
    name: "lastName", 
    identityProviderMapper: "saml-user-attribute-idp-mapper",
    config: {
      "attribute.name": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname",
      "user.attribute": "lastName",
    },
  },
];

for (const mapper of mappers) {
  await kcAdminClient.identityProviders.createMapper(
    { alias: "corporate-saml" },
    mapper
  );
}

// Pattern 2: Multiple social providers
const socialProviders = [
  {
    alias: "google",
    displayName: "Google",
    providerId: "google",
    config: {
      clientId: process.env.GOOGLE_CLIENT_ID,
      clientSecret: process.env.GOOGLE_CLIENT_SECRET,
    },
  },
  {
    alias: "github",
    displayName: "GitHub", 
    providerId: "github",
    config: {
      clientId: process.env.GITHUB_CLIENT_ID,
      clientSecret: process.env.GITHUB_CLIENT_SECRET,
    },
  },
];

for (const provider of socialProviders) {
  await kcAdminClient.identityProviders.create({
    ...provider,
    enabled: true,
    trustEmail: provider.providerId === "google",
  });
}

docs

attack-detection.md

authentication-management.md

cache-management.md

client-configuration.md

client-management.md

client-policies.md

client-scopes.md

components.md

group-management.md

identity-providers.md

index.md

organization-management.md

realm-management.md

role-management.md

server-info.md

user-management.md

user-storage-provider.md

utility-functions.md

whoami.md

tile.json