Skip to content

Update an identity provider

PATCH
/clusters/{cluster_id}/realms/{realm_name}/identity-providers/{provider_id}
curl --request PATCH \
  --url http://localhost:8000/clusters/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/realms/customer-portal/identity-providers/google-workspace \
  --header 'API-Key: <API-Key>' \
  --header 'API-Version: 2026-06-01.beta' \
  --header 'Content-Type: application/json' \
  --data '{ "display_name": "example", "enabled": true, "client_id": "example", "client_secret": "example", "config": { "oidc": { "issuer": "https://accounts.google.com", "authorization_url": "https://accounts.google.com/o/oauth2/v2/auth", "token_url": "https://oauth2.googleapis.com/token", "userinfo_url": "https://openidconnect.googleapis.com/v1/userinfo", "logout_url": "https://example.com" }, "saml": { "entity_id": "https://idp.example.com/entity", "sso_url": "https://idp.example.com/sso/saml", "metadata_url": "https://example.com", "metadata_xml": "example" }, "ldap": { "server_url": "ldaps://ldap.example.com:636", "base_dn": "dc=example,dc=com", "bind_dn": "cn=skycloak-svc,ou=service-accounts,dc=example,dc=com" }, "icon_url": "https://example.com", "button_text": "Continue with Okta", "attribute_mappings": { "email": "email", "firstName": "given_name", "lastName": "family_name" }, "sync_mode": "import", "trust_email": true } }'

Partially updates an identity provider. Only provided fields are modified. Returns 403 Forbidden when the provider is externally_managed.

Required scope: identity-providers:write

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
cluster_id
required
string format: uuid
realm_name
required

Keycloak realm name (not ID). Must start with a letter; allows letters, digits, and hyphens.

string
>= 1 characters <= 63 characters /^[a-zA-Z][a-zA-Z0-9-]*$/

Example 

customer-portal
provider_id
required

Keycloak identity provider alias. Used as the stable resource identifier in this API and in Keycloak login flows.

string
>= 1 characters <= 255 characters /^[a-zA-Z0-9_-]+$/

Example 

google-workspace

Header Parameters

Section titled “Header Parameters”
API-Version
required
string
Allowed values: 2026-06-01.beta

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json

Partial update request. Only provided fields are modified.

object
display_name
string
>= 1 characters <= 255 characters
enabled
boolean
client_id

Updated client identifier.

string
>= 1 characters <= 1024 characters
client_secret

Updated client secret or LDAP bind password. Write-only; never returned by the API.

string format: password
>= 1 characters <= 8192 characters
config

Protocol-specific configuration update. Populate only the sub-object matching the provider’s existing type (e.g. oidc for OIDC providers). Mixing sub-objects (e.g. sending config.saml for an OIDC provider) returns 422. All URL fields must use http/https (or ldap/ldaps for config.ldap.server_url). Only provided fields are merged; omitted fields retain their current values.

object
oidc

OIDC-specific endpoints. Required when type is oidc.

object
issuer

OIDC issuer identifier URL. Use POST /identity-providers/discover-oidc to fetch endpoints from the issuer automatically.

string format: uri
<= 2048 characters

Example 

https://accounts.google.com
authorization_url

Authorization endpoint. Derived from discovery when issuer is supplied.

string format: uri
<= 2048 characters

Example 

https://accounts.google.com/o/oauth2/v2/auth
token_url

Token endpoint. Derived from discovery when issuer is supplied.

string format: uri
<= 2048 characters

Example 

https://oauth2.googleapis.com/token
userinfo_url

UserInfo endpoint.

string format: uri
<= 2048 characters

Example 

https://openidconnect.googleapis.com/v1/userinfo
logout_url

End-session (logout) endpoint.

string format: uri
<= 2048 characters
saml

SAML-specific settings. Required when type is saml.

object
entity_id

SAML entity ID of the external identity provider.

string
<= 512 characters

Example 

https://idp.example.com/entity
sso_url

SAML Single Sign-On service URL.

string format: uri
<= 2048 characters

Example 

https://idp.example.com/sso/saml
metadata_url

URL to the IdP’s SAML metadata document. Takes precedence over metadata_xml.

string format: uri
<= 2048 characters
metadata_xml

Raw SAML metadata XML. Used when the IdP does not publish a metadata URL.

string
<= 65536 characters
ldap

LDAP-specific settings. Required when type is ldap.

object
server_url

LDAP server URL including scheme and port.

string
<= 512 characters /^ldaps?:///

Example 

ldaps://ldap.example.com:636
base_dn

Base Distinguished Name used as the search root.

string
<= 512 characters

Example 

dc=example,dc=com
bind_dn

Bind DN used to authenticate against the directory.

string
<= 512 characters

Example 

cn=skycloak-svc,ou=service-accounts,dc=example,dc=com
icon_url

URL to the logo displayed on the login button.

string format: uri
<= 2048 characters
button_text

Label of the SSO login button shown to end users.

string
<= 100 characters

Example 

Continue with Okta
attribute_mappings

Keycloak attribute name → IdP claim name mappings applied when importing user profiles.

object
key
additional properties
string

Example 

{
  "email": "email",
  "firstName": "given_name",
  "lastName": "family_name"
}
sync_mode
string
Allowed values: import force legacy
trust_email

When true, Keycloak trusts email addresses provided by this IdP without sending a verification email. Enable only for providers that verify email addresses themselves.

boolean

Responses

Section titled “Responses”

200

Section titled “200”

The request has succeeded.

Media typeapplication/json

An identity provider (social login, enterprise SSO, or directory federation) configured in a Keycloak realm.

object
provider_id
required

Keycloak alias. Stable resource identifier for this API. For providers created via Skycloak this is always a SkycloakProviderId value; for externally managed providers it may be any valid alias string.

string
>= 1 characters <= 255 characters /^[a-zA-Z0-9_-]+$/
type
required

Protocol of the identity provider.

string
Allowed values: oidc saml ldap
display_name
required
string
enabled
required
boolean
client_id

Client identifier used to authenticate with the external provider. Not a secret.

string
config
required

Protocol-specific configuration and shared display options. Populate only the sub-object that matches type.

object
oidc

OIDC-specific endpoints. Required when type is oidc.

object
issuer

OIDC issuer identifier URL. Use POST /identity-providers/discover-oidc to fetch endpoints from the issuer automatically.

string format: uri
<= 2048 characters
authorization_url

Authorization endpoint. Derived from discovery when issuer is supplied.

string format: uri
<= 2048 characters
token_url

Token endpoint. Derived from discovery when issuer is supplied.

string format: uri
<= 2048 characters
userinfo_url

UserInfo endpoint.

string format: uri
<= 2048 characters
logout_url

End-session (logout) endpoint.

string format: uri
<= 2048 characters
saml

SAML-specific settings. Required when type is saml.

object
entity_id

SAML entity ID of the external identity provider.

string
<= 512 characters
sso_url

SAML Single Sign-On service URL.

string format: uri
<= 2048 characters
metadata_url

URL to the IdP’s SAML metadata document. Takes precedence over metadata_xml.

string format: uri
<= 2048 characters
metadata_xml

Raw SAML metadata XML. Used when the IdP does not publish a metadata URL.

string
<= 65536 characters
ldap

LDAP-specific settings. Required when type is ldap.

object
server_url

LDAP server URL including scheme and port.

string
<= 512 characters /^ldaps?:///
base_dn

Base Distinguished Name used as the search root.

string
<= 512 characters
bind_dn

Bind DN used to authenticate against the directory.

string
<= 512 characters
icon_url

URL to the logo displayed on the login button.

string format: uri
<= 2048 characters
button_text

Label of the SSO login button shown to end users.

string
<= 100 characters
attribute_mappings

Keycloak attribute name → IdP claim name mappings applied when importing user profiles.

object
key
additional properties
string
sync_mode
string
Allowed values: import force legacy
trust_email

When true, Keycloak trusts email addresses provided by this IdP without sending a verification email. Enable only for providers that verify email addresses themselves.

boolean
externally_managed
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.

boolean
created_at
required
string format: date-time
updated_at
required
string format: date-time

Example 

{
  "provider_id": "google-workspace",
  "type": "oidc",
  "config": {
    "oidc": {
      "issuer": "https://accounts.google.com",
      "authorization_url": "https://accounts.google.com/o/oauth2/v2/auth",
      "token_url": "https://oauth2.googleapis.com/token",
      "userinfo_url": "https://openidconnect.googleapis.com/v1/userinfo"
    },
    "saml": {
      "entity_id": "https://idp.example.com/entity",
      "sso_url": "https://idp.example.com/sso/saml"
    },
    "ldap": {
      "server_url": "ldaps://ldap.example.com:636",
      "base_dn": "dc=example,dc=com",
      "bind_dn": "cn=skycloak-svc,ou=service-accounts,dc=example,dc=com"
    },
    "button_text": "Continue with Okta",
    "attribute_mappings": {
      "email": "email",
      "firstName": "given_name",
      "lastName": "family_name"
    },
    "sync_mode": "import"
  }
}

400

Section titled “400”

The server could not understand the request due to invalid syntax.

Media typeapplication/problem+json

RFC 9457 Problem Details object.

object
type
required
string format: uri
title
required
string
status
required
integer
detail
required
string
instance
string format: uri

Example generated

{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "https://example.com"
}

401

Section titled “401”

Access is unauthorized.

Media typeapplication/problem+json

RFC 9457 Problem Details object.

object
type
required
string format: uri
title
required
string
status
required
integer
detail
required
string
instance
string format: uri

Example generated

{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "https://example.com"
}

403

Section titled “403”

Access is forbidden.

Media typeapplication/problem+json

RFC 9457 Problem Details object.

object
type
required
string format: uri
title
required
string
status
required
integer
detail
required
string
instance
string format: uri

Example generated

{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "https://example.com"
}

404

Section titled “404”

The server cannot find the requested resource.

Media typeapplication/problem+json

RFC 9457 Problem Details object.

object
type
required
string format: uri
title
required
string
status
required
integer
detail
required
string
instance
string format: uri

Example generated

{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "https://example.com"
}

422

Section titled “422”

Client error

Media typeapplication/problem+json
object
type
required
string format: uri
title
required
string
status
required
integer
detail
required
string
instance
string format: uri
errors
required
Array<object>
>= 1 items
object
field
required
string
detail
required
string
code
string
value

Example generated

{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "https://example.com",
  "errors": [
    {
      "field": "example",
      "detail": "example",
      "code": "example",
      "value": "example"
    }
  ]
}

429

Section titled “429”

Client error

Media typeapplication/problem+json

RFC 9457 Problem Details object.

object
type
required
string format: uri
title
required
string
status
required
integer
detail
required
string
instance
string format: uri

Example generated

{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "https://example.com"
}

Headers

Section titled “Headers”
Retry-After
integer
RateLimit-Limit
integer
RateLimit-Remaining
integer
RateLimit-Reset
integer
X-RateLimit-Limit-Second
integer
X-RateLimit-Remaining-Second
integer
X-RateLimit-Limit-Minute
integer
X-RateLimit-Remaining-Minute
integer
X-RateLimit-Limit-Hour
integer
X-RateLimit-Remaining-Hour
integer
X-RateLimit-Limit-Day
integer
X-RateLimit-Remaining-Day
integer

500

Section titled “500”

Server error

Media typeapplication/problem+json

RFC 9457 Problem Details object.

object
type
required
string format: uri
title
required
string
status
required
integer
detail
required
string
instance
string format: uri

Example generated

{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "https://example.com"
}

501

Section titled “501”

Server error

Media typeapplication/problem+json

RFC 9457 Problem Details object.

object
type
required
string format: uri
title
required
string
status
required
integer
detail
required
string
instance
string format: uri

Example generated

{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "https://example.com"
}
© 2026 Skycloak. All Rights Reserved. Design by Yasser SolimanKeycloak™ is a trademark of the Linux Foundation. Skycloak is not affiliated with the Keycloak project.