Guides
Enterprise SSO Setup

Enterprise SSO Setup

This guide covers setting up enterprise identity providers in Skycloak using OIDC and SAML protocols. Enterprise SSO lets your users sign in through their organization’s identity provider (like Okta, Azure AD, or OneLogin).

All setup happens on a single page — select a template, paste credentials, test, and save.

Prerequisites

  • An active Skycloak cluster
  • A configured realm
  • Admin credentials for your identity provider
  • Basic understanding of OIDC or SAML protocols

Choosing Between OIDC and SAML

Feature OIDC SAML
Protocol Modern, JSON-based XML-based, mature
Setup complexity Simpler More configuration
Token format JWT XML assertions
Best for Modern cloud apps Legacy enterprise systems
Discovery Automatic via .well-known Manual metadata exchange
Auto-discovery Supported in Skycloak Not applicable

Recommendation: Use OIDC when your identity provider supports it. Use SAML when OIDC is not available or when you need SAML-specific features.

OIDC Auto-Discovery

For enterprise OIDC providers, Skycloak can automatically detect your provider’s OAuth endpoints. Instead of manually entering authorization, token, and userinfo URLs:

  1. Paste your discovery URL (e.g., https://dev-123456.okta.com/.well-known/openid-configuration)
  2. Click “Auto-Detect”
  3. All endpoints are populated automatically

This works with any OIDC-compliant provider. The setup page shows a provider-specific placeholder URL to help you find the right discovery endpoint.

Enterprise OIDC Providers

Okta (OIDC)

  1. In Okta: Create a new Web Application integration
    • Sign-in method: OIDC
    • Application type: Web Application
    • Grant type: Authorization Code
  2. Copy the Client ID, Client Secret, and your Okta domain (e.g., dev-123456.okta.com)
  3. In Skycloak: Select the “Okta” OIDC template
  4. Use Auto-Discovery: Paste your Okta discovery URL (https://dev-123456.okta.com/.well-known/openid-configuration) and click “Auto-Detect” — all endpoints populate automatically
  5. Enter your Client ID and Client Secret
  6. Test Connection and Save & Enable

OneLogin (OIDC)

  1. In OneLogin: Add a new OIDC application
    • Application Type: Web
    • Token endpoint: POST
  2. Copy the Client ID, Client Secret, and your OneLogin subdomain
  3. In Skycloak: Select the “OneLogin” OIDC template
  4. Enter credentials and subdomain
  5. URLs use your subdomain: https://{subdomain}.onelogin.com/oidc/2/...

JumpCloud (OIDC)

  1. In JumpCloud: Create a new SSO Application
    • Select Custom OIDC
    • Grant type: Authorization Code
  2. Copy the Client ID, Client Secret, and Application ID
  3. In Skycloak: Select the “JumpCloud” OIDC template
  4. Enter credentials — JumpCloud uses standard OAuth endpoints

PingOne (OIDC)

  1. In PingOne: Create a new application
    • Application Type: Web App
    • Grant type: Authorization Code
  2. Copy the Client ID, Client Secret, and Environment ID
  3. In Skycloak: Select the “PingOne” OIDC template
  4. Enter credentials and environment ID
  5. URLs use your environment: https://auth.pingone.com/{envId}/as/...

Auth0 (OIDC)

  1. In Auth0: Create a new Regular Web Application
    • Allowed callback URL: Copy the Redirect URI from Skycloak’s setup page
  2. Copy the Client ID, Client Secret, and your Auth0 domain
  3. In Skycloak: Select the “Auth0” OIDC template
  4. Use Auto-Discovery: Paste your Auth0 discovery URL (https://{domain}.auth0.com/.well-known/openid-configuration) and click “Auto-Detect”
  5. Enter Client ID and Client Secret
  6. Test Connection and Save & Enable

Salesforce (OIDC)

  1. In Salesforce: Create a Connected App
    • Enable OAuth Settings
    • Scopes: openid, email, profile
  2. Copy Consumer Key (Client ID) and Consumer Secret
  3. In Skycloak: Select the “Salesforce” OIDC template
  4. Enter credentials — uses standard Salesforce login endpoints

Enterprise SAML Providers

Okta (SAML)

  1. In Okta: Create a new SAML 2.0 Application
    • Single sign on URL: Copy from Skycloak’s SP Entity ID
    • Audience URI: Copy from Skycloak
  2. Copy the IdP metadata URL from Okta
  3. In Skycloak: Select the “Okta” SAML template
  4. Enter the metadata URL — configuration auto-imports

Azure AD (SAML)

  1. In Azure Portal: Create an Enterprise Application
    • Select SAML-based Sign-on
    • Configure Basic SAML Configuration with Skycloak’s Entity ID and Reply URL
  2. Download the Federation Metadata XML
  3. In Skycloak: Select the “Azure AD” SAML template
  4. Upload metadata XML or paste the metadata URL

Google Workspace (SAML)

  1. In Google Admin Console: Add a custom SAML app
    • Copy the SSO URL and download the certificate
  2. In Skycloak: Select the “Google Workspace” SAML template
  3. Enter the SSO URL and upload the certificate
  4. Configure attribute mappings for email, first name, last name

Additional SAML Providers

Skycloak also supports SAML integration with:

  • OneLogin — PascalCase attribute naming (Email, FirstName, LastName)
  • JumpCloud — Lowercase attribute naming (email, firstname, lastname)
  • PingFederate — On-premise PingIdentity federation
  • PingOne — PingIdentity cloud with User.* attribute prefix
  • Duo Security — AD-style attribute naming (mail, givenName)
  • Cloudflare Access — Zero Trust identity
  • CyberArk — Privileged access management

Custom SAML Provider

For SAML providers not listed above:

  1. In Skycloak: Select “Custom SAML v2.0”
  2. Enter the required configuration:
    • Entity ID (from your IdP)
    • Single Sign-On URL
    • Metadata URL or XML
    • Signing certificate (if required)
  3. Configure attribute mappings based on your IdP’s claim format
  4. Test the connection before enabling

Custom OIDC Provider

For any OIDC-compliant provider not listed above:

  1. In Skycloak: Select “Custom OpenID Connect 1.0”
  2. Use Auto-Discovery (recommended): Paste your provider’s discovery URL and click “Auto-Detect” to populate all endpoints automatically
  3. Or enter manually:
    • Authorization URL
    • Token URL
    • UserInfo URL (optional but recommended)
    • Issuer URL (optional)
  4. Enter Client ID and Client Secret
  5. Test the connection before enabling

Understanding SAML Authentication Flows

SAML supports three types of authentication flows. It’s important to understand which one you need.

SP-Initiated SSO (What Skycloak Configures)

This is the default and most common flow. It works like this:

  1. User visits your application
  2. Your app redirects to Keycloak
  3. Keycloak redirects to the Identity Provider (Okta, Azure AD, etc.)
  4. User authenticates at the IdP
  5. IdP sends a SAML assertion back to Keycloak
  6. Keycloak logs the user in and redirects back to your app

This is the flow that Skycloak’s SSO setup page configures automatically. No extra steps needed.

IdP-Initiated SSO (Requires Additional Setup)

In this flow, the user starts from their Identity Provider’s portal (e.g., Okta dashboard, Azure AD MyApps) and clicks an app tile to access your application — without visiting your app first.

Skycloak’s SSO setup page does not configure this flow. If your organization needs IdP-initiated SSO, follow these additional steps after completing the standard SAML setup:

  1. Log in to your Keycloak Admin Console for the cluster
  2. Go to Identity Providers and select your SAML provider
  3. Under Advanced Settings, verify that IdP-initiated SSO is not blocked
  4. Copy the SAML endpoint URL:
    https://{your-cluster}.skycloak.io/realms/{realm}/broker/{provider-alias}/endpoint
  5. In your Identity Provider’s admin portal (Okta, Azure AD, OneLogin, etc.):
    • Create a new “app tile” or “bookmark app”
    • Set the SSO URL to the Keycloak SAML endpoint from step 4
    • Configure the RelayState parameter to your application’s client ID (optional, for deep linking)
  6. Test by clicking the app tile in your IdP portal
ℹ️
When do you need IdP-initiated SSO? Most organizations use SP-initiated SSO and don’t need this. Consider IdP-initiated SSO if your users primarily access applications from their IdP dashboard (e.g., Okta portal, Azure AD MyApps) rather than navigating directly to your app.

Proxy/Broker Flow (Advanced)

In this flow, Keycloak acts as a SAML broker between an external Identity Provider and your downstream applications. This is used for complex federation scenarios such as:

  • Multi-organization access where different partners use different IdPs
  • Chaining authentication through intermediary identity systems
  • Centralizing identity brokering for multiple applications

This flow requires manual configuration in the Keycloak Admin Console and is not available through Skycloak’s SSO setup page. If you need this, configure it through:

  1. Keycloak Admin Console → Authentication → Flows
  2. Set up a custom authentication flow that brokers between providers
  3. Configure the appropriate identity provider mappers for attribute transformation

For most organizations, SP-initiated SSO is sufficient. Contact support if you need help with broker/proxy configurations.

Testing Your Configuration

After configuring any enterprise SSO provider:

  1. Click “Test Connection” in Skycloak
  2. Verify the authentication flow completes
  3. Check that user attributes map correctly
  4. Test with a real user account from the identity provider

Troubleshooting

OIDC Issues

  • Invalid redirect URI: Ensure the redirect URI in your IdP matches exactly what Skycloak provides
  • Token validation failed: Check that the Issuer URL is correct
  • Missing user attributes: Verify scopes include openid email profile

SAML Issues

  • Signature validation failed: Ensure you’re using the correct signing certificate
  • Attribute mapping errors: Check your IdP’s attribute naming convention matches the template
  • Clock skew: Ensure server clocks are synchronized (within 5 minutes)

Related Guides

Last updated on
Authorization ModelInvitation Lifecycle and Account Linking