Skip to content

Get an identity provider

GET
/clusters/{cluster_id}/realms/{realm_name}/identity-providers/{provider_id}
curl --request GET \
  --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'

Required scope: identity-providers:read

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

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"
  }
}

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"
}

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"
}

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.