---
title: "Create an identity provider"
method: POST
path: "/clusters/{cluster_id}/realms/{realm_name}/identity-providers"
tags: ["Identity Providers"]
---

# Create an identity provider

`POST /clusters/{cluster_id}/realms/{realm_name}/identity-providers`

## Request

- Base URL: `http://localhost:8000`
- URL: `http://localhost:8000/clusters/{cluster_id}/realms/{realm_name}/identity-providers`
- Auth: API key in header `API-Key`

Adds a new identity provider to the realm. Supply `template_id` from `GET /identity-provider-templates` to bootstrap configuration from a pre-built template.

Required scope: `identity-providers:write`

## Path parameters

- `cluster_id` string, uuid, required
- `realm_name` string, required: Keycloak realm name (not ID). Must start with a letter; allows letters, digits, and hyphens.

## Headers

- `API-Version` '2026-06-01.beta', required

## Request body

- CreateIdentityProviderRequest: Request body for creating a new identity provider.
  - `provider_id` 'oidc' | 'saml' | 'keycloak-oidc' | 'google' | 'github' | 'microsoft' | 'facebook' | 'gitlab' | 'bitbucket' | 'linkedin-openid-connect' | 'twitter' | 'instagram' | 'paypal' | 'stackoverflow' | 'openshift-v4' | 'google-workspace' | 'okta-oidc' | 'onelogin-oidc' | 'jumpcloud-oidc' | 'pingone-oidc' | 'auth0' | 'salesforce' | 'slack' | 'discord' | 'atlassian' | 'twitch' | 'custom-oidc' | 'google-workspace-saml' | 'okta-saml' | 'azure-ad-saml' | 'onelogin-saml' | 'jumpcloud-saml' | 'pingfederate-saml' | 'pingone-saml' | 'duo-saml' | 'cloudflare-saml' | 'cyberark-saml' | 'custom-saml', required: Supported Skycloak identity provider ID.
  - `type` 'oidc' | 'saml' | 'ldap', required: Protocol of the identity provider.
  - `display_name` string, required
  - `client_id` string: OAuth 2.0 / LDAP client identifier registered with the external provider.
  - `client_secret` string, password: Client secret or LDAP bind password. Write-only; never returned by the API.
  - `config` ProviderConfig: Protocol-specific configuration and shared display options. Populate only the sub-object that matches `type`.
    - `oidc` OIDCConfig
      - `issuer` string, uri: OIDC issuer identifier URL. Use `POST /identity-providers/discover-oidc` to fetch endpoints from the issuer automatically.
      - `authorization_url` string, uri: Authorization endpoint. Derived from discovery when `issuer` is supplied.
      - `token_url` string, uri: Token endpoint. Derived from discovery when `issuer` is supplied.
      - `userinfo_url` string, uri: UserInfo endpoint.
      - `logout_url` string, uri: End-session (logout) endpoint.
    - `saml` SAMLIdPConfig
      - `entity_id` string: SAML entity ID of the external identity provider.
      - `sso_url` string, uri: SAML Single Sign-On service URL.
      - `metadata_url` string, uri: URL to the IdP's SAML metadata document. Takes precedence over `metadata_xml`.
      - `metadata_xml` string: Raw SAML metadata XML. Used when the IdP does not publish a metadata URL.
    - `ldap` LDAPConfig
      - `server_url` string: LDAP server URL including scheme and port.
      - `base_dn` string: Base Distinguished Name used as the search root.
      - `bind_dn` string: Bind DN used to authenticate against the directory.
    - `icon_url` string, uri: URL to the logo displayed on the login button.
    - `button_text` string: Label of the SSO login button shown to end users.
    - `attribute_mappings` object: Keycloak attribute name → IdP claim name mappings applied when importing user profiles.
    - `sync_mode` 'import' | 'force' | 'legacy': Controls how Keycloak imports and synchronises user attributes from the provider on login.
    - `trust_email` boolean: When `true`, Keycloak trusts email addresses provided by this IdP without sending a verification email. Enable only for providers that verify email addresses themselves.
  - `template_id` string: Template ID from `GET /identity-provider-templates`. When provided, `type` and `config` are pre-filled with recommended defaults; explicit fields in this request override template values.

## Response `201`

The request has succeeded and a new resource has been created as a result.

- IdentityProvider: An identity provider (social login, enterprise SSO, or directory federation) configured in a Keycloak realm.
  - `provider_id` string, required: Keycloak identity provider alias. Used as the stable resource identifier in this API and in Keycloak login flows.
  - `type` 'oidc' | 'saml' | 'ldap', required: Protocol of the identity provider.
  - `display_name` string, required
  - `enabled` boolean, required
  - `client_id` string: Client identifier used to authenticate with the external provider. Not a secret.
  - `config` ProviderConfig, required: Protocol-specific configuration and shared display options. Populate only the sub-object that matches `type`.
    - `oidc` OIDCConfig
      - `issuer` string, uri: OIDC issuer identifier URL. Use `POST /identity-providers/discover-oidc` to fetch endpoints from the issuer automatically.
      - `authorization_url` string, uri: Authorization endpoint. Derived from discovery when `issuer` is supplied.
      - `token_url` string, uri: Token endpoint. Derived from discovery when `issuer` is supplied.
      - `userinfo_url` string, uri: UserInfo endpoint.
      - `logout_url` string, uri: End-session (logout) endpoint.
    - `saml` SAMLIdPConfig
      - `entity_id` string: SAML entity ID of the external identity provider.
      - `sso_url` string, uri: SAML Single Sign-On service URL.
      - `metadata_url` string, uri: URL to the IdP's SAML metadata document. Takes precedence over `metadata_xml`.
      - `metadata_xml` string: Raw SAML metadata XML. Used when the IdP does not publish a metadata URL.
    - `ldap` LDAPConfig
      - `server_url` string: LDAP server URL including scheme and port.
      - `base_dn` string: Base Distinguished Name used as the search root.
      - `bind_dn` string: Bind DN used to authenticate against the directory.
    - `icon_url` string, uri: URL to the logo displayed on the login button.
    - `button_text` string: Label of the SSO login button shown to end users.
    - `attribute_mappings` object: Keycloak attribute name → IdP claim name mappings applied when importing user profiles.
    - `sync_mode` 'import' | 'force' | 'legacy': Controls how Keycloak imports and synchronises user attributes from the provider on login.
    - `trust_email` boolean: When `true`, Keycloak trusts email addresses provided by this IdP without sending a verification email. Enable only for providers that verify email addresses themselves.
  - `externally_managed` boolean, required: When `true`, this provider was created or last modified directly in the Keycloak Admin Console. Skycloak reflects its configuration but `PATCH` and `DELETE` will return `403 Forbidden`.
  - `created_at` string, date-time, required
  - `updated_at` string, date-time, required

## Other responses

- `400`: The server could not understand the request due to invalid syntax.
- `401`: Access is unauthorized.
- `402`: Client error
- `403`: Access is forbidden.
- `404`: The server cannot find the requested resource.
- `409`: The request conflicts with the current state of the server.
- `422`: Client error
- `429`: Client error
- `500`: Server error
- `501`: Server error

---

[API](https://skmtc.dev/skycloak/apis/skycloak-public-api.md) · [All operations](https://skmtc.dev/skycloak/apis/skycloak-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/skycloak/apis/skycloak-public-api/revisions/33a69e2ce35f?raw)