Tutorials
Setting Up Workspace SSO

Setting Up Workspace SSO

This tutorial walks you through setting up Single Sign-On (SSO) for your Skycloak workspace using popular identity providers.

Before You Begin

Ensure you have:

  • A Skycloak workspace on Business or Enterprise plan
  • Workspace Owner or Admin role
  • Admin access to your identity provider (Azure AD, Okta, or Google Workspace)
  • Your organization’s email domain (e.g., @yourcompany.com)

Azure AD SAML Setup

Part 1: Create Enterprise Application in Azure

  1. Sign in to Azure Portal

  2. Create New Application

    • Select Enterprise applications from the left menu
    • Click + New application
    • Click Create your own application
    • Name it “Skycloak SSO”
    • Select Integrate any other application you don’t find in the gallery
    • Click Create

  3. Configure Single Sign-On

    • In your new application, go to Single sign-on
    • Select SAML as the sign-on method

Part 2: Configure Skycloak

  1. Open Skycloak Security Settings

    • Navigate to Settings → Workspace → Security
    • Find the Single Sign-On (SSO) section
    • Click Configure SSO

  2. Select Azure AD

    • Choose Azure AD (SAML) as the provider type
    • Note your domain restriction (e.g., @yourcompany.com)

  3. Keep This Page Open

    • You’ll need the Entity ID and ACS URL for Azure configuration

Part 3: Configure Azure AD SAML

  1. Basic SAML Configuration (in Azure)
    • Click Edit in Basic SAML Configuration
    • Identifier (Entity ID): Copy from Skycloak configuration page
    • Reply URL (ACS URL): Add both URLs for full SSO support:
      • IdP-initiated URL (primary): Copy the ACS URL shown in Skycloak (e.g., .../broker/sso-abc123/endpoint/clients/sso-abc123)
      • SP-initiated URL (secondary): Use the same URL but remove /clients/{provider-id} suffix (e.g., .../broker/sso-abc123/endpoint)
    • Click Save

Important: Both Reply URLs are required for full SSO functionality:

  • The IdP-initiated URL (with /clients/...) handles users clicking the app tile in their Azure AD portal
  • The SP-initiated URL (without /clients/...) handles “Sign in with SAML” from the Skycloak login page

If you only configure one URL, either IdP-initiated or SP-initiated login will fail with a “Reply URL mismatch” error.

  1. User Attributes & Claims

    • Click Edit in User Attributes & Claims
    • Ensure these claims are mapped:
      • emailaddress → user.mail
      • givenname → user.givenname
      • surname → user.surname

  2. Download Federation Metadata

    • In the SAML Certificates section
    • Click Download next to Federation Metadata XML

Part 4: Complete Skycloak Configuration

  1. Upload Metadata

    • Return to Skycloak SSO configuration
    • Select Metadata XML tab
    • Upload the Federation Metadata XML file
    • Or copy the App Federation Metadata Url from Azure and paste in Metadata URL tab

  2. Configure Attribute Mapping

    • Email: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
    • First Name: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname
    • Last Name: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname

  3. Save Configuration

    • Click Save Configuration
    • Copy the displayed Entity ID and ACS URL

Part 5: Assign Users in Azure

  1. Assign Users/Groups
    • In Azure, go to Users and groups
    • Click + Add user/group
    • Select users or groups who should have access
    • Click Assign

Part 6: Test the Configuration

  1. Test in Skycloak

    • Click Test Connection button
    • Verify success message

  2. Test User Login

    • Open a new incognito browser window
    • Navigate to login.app.skycloak.io
    • Click Sign in with SAML
    • Authenticate with Azure AD credentials
    • Verify successful login to Skycloak

Okta SAML Setup

Part 1: Create SAML Application in Okta

  1. Sign in to Okta Admin Console

    • Go to your Okta admin dashboard
    • Navigate to Applications → Applications

  2. Create New App Integration

    • Click Create App Integration
    • Select SAML 2.0
    • Click Next
    • Name it “Skycloak Workspace SSO”

Part 2: Configure Skycloak

  1. Start SSO Configuration
    • Go to Settings → Workspace → Security → SSO
    • Click Configure SSO
    • Select Okta (SAML)
    • Keep this page open for the next steps

Part 3: Configure SAML in Okta

  1. Configure SAML Settings

    • Single sign-on URL: Copy the ACS URL from Skycloak (this is the IdP-initiated URL)
    • Audience URI (SP Entity ID): Copy Entity ID from Skycloak
    • Name ID format: EmailAddress
    • Application username: Email

  2. Configure Additional URLs (click Show Advanced Settings)

    • Other Requestable SSO URLs: Add the SP-initiated URL:
      • Take the ACS URL from Skycloak and remove the /clients/{provider-id} suffix
      • Example: If ACS URL is .../broker/sso-abc123/endpoint/clients/sso-abc123, add .../broker/sso-abc123/endpoint
    • This allows both IdP-initiated (from Okta dashboard) and SP-initiated (from Skycloak login page) SSO to work

Important: Both URLs are required for full SSO functionality. The main Single sign-on URL handles IdP-initiated logins (clicking the app tile in Okta), while the additional URL handles SP-initiated logins (clicking “Sign in with SAML” in Skycloak).

  1. Attribute Statements Add the following attributes:

    • Name: email → Value: user.email
    • Name: firstName → Value: user.firstName
    • Name: lastName → Value: user.lastName

  2. Complete Setup

    • Click Next
    • Select I’m an Okta customer adding an internal app
    • Click Finish

Part 4: Get Okta Metadata

  1. Copy Metadata URL
    • In your Okta application, go to Sign On tab
    • Right-click on View SAML setup instructions
    • Copy the Identity Provider metadata URL

Part 5: Complete Skycloak Configuration

  1. Add Metadata

    • Return to Skycloak
    • Paste the metadata URL in Metadata URL field
    • Verify attribute mappings are set to:
      • Email: email
      • First Name: firstName
      • Last Name: lastName

  2. Save and Test

    • Click Save Configuration
    • Click Test Connection

Part 6: Assign Users in Okta

  1. Assign Application
    • In Okta, go to Assignments tab
    • Click Assign → Assign to People or Assign to Groups
    • Select appropriate users/groups
    • Click Save and Go Back

Google Workspace SAML Setup

Important Google Workspace Considerations:

  • Google Workspace may not always return the RelayState parameter
  • Skycloak automatically handles this behavior when Google Workspace is selected
  • Google uses HTTP-Redirect for authentication requests, not POST
  • These configurations are applied automatically when you select “Google Workspace (SAML)”

Part 1: Access Google Admin Console

  1. Sign in to Google Admin

  2. Add Custom SAML App

    • Click Add app → Add custom SAML app
    • Enter “Skycloak Workspace” as the app name
    • Click Continue

Part 2: Configure Skycloak

  1. Start Configuration
    • In Skycloak, go to Security settings
    • Click Configure SSO
    • Select Google Workspace (SAML)
    • Keep this window open

Part 3: Configure Google Workspace

  1. Download IDP Metadata

    • In Google Admin, you’ll see your SSO URL and Entity ID
    • Click Download Metadata to get the XML file
    • Click Continue

  2. Service Provider Details

    • ACS URL: Copy from Skycloak (this is the IdP-initiated URL shown in Skycloak)
    • Entity ID: Copy from Skycloak
    • Name ID format: Select EMAIL from the dropdown
    • Name ID: Select Basic Information > Primary email
    • Click Continue

    Note for SP-initiated SSO: Google Workspace typically works with a single ACS URL. If you need SP-initiated SSO (login from Skycloak), you may need to add a second ACS URL without the /clients/{provider-id} suffix. Check if Google allows multiple ACS URLs in your configuration.

    Important: The Name ID configuration is critical for proper user identification. Always use EMAIL format with Primary email as the value.

  3. Attribute Mapping Add these attributes:

    • email → Basic Information → Primary email
    • firstName → Basic Information → First name
    • lastName → Basic Information → Last name
    • Click Finish

Part 4: Complete Skycloak Setup

  1. Upload Metadata

    • Return to Skycloak
    • Upload the Google metadata XML file
    • Verify attribute mappings

  2. Save Configuration

    • Click Save Configuration
    • Note the configuration details

Part 5: Enable for Users

  1. Turn on Application
    • In Google Admin, find your Skycloak app
    • Click on it to open settings
    • Click User access
    • Select ON for everyone or specific organizational units
    • Click Save

Part 6: Test the Setup

  1. Test Connection

    • In Skycloak, click Test Connection
    • Verify success

  2. Test User Login

    • Open incognito browser
    • Go to login.app.skycloak.io
    • Click Sign in with SAML
    • Sign in with Google Workspace account

Custom SAML Provider Setup

General Steps

  1. Configure Skycloak

    • Select Custom SAML as provider type
    • Note the Entity ID and ACS URL

  2. Configure Your IdP Use these standard SAML settings:

    • Service Provider Entity ID: From Skycloak
    • Assertion Consumer Service URL (ACS URL): Configure both URLs for full SSO support:
      • IdP-initiated URL: The ACS URL shown in Skycloak (e.g., .../broker/sso-abc123/endpoint/clients/sso-abc123)
      • SP-initiated URL: The same URL without /clients/{provider-id} suffix (e.g., .../broker/sso-abc123/endpoint)
    • Name ID Format: Email Address
    • Protocol Binding: HTTP-POST

    Important: Both ACS URLs are required if you want both IdP-initiated (clicking app tile in your IdP) and SP-initiated (clicking “Sign in with SAML” in Skycloak) logins to work.

  3. Configure Attributes Map these minimum required attributes:

    • User’s email address → email
    • User’s first name → firstName
    • User’s last name → lastName

  4. Exchange Metadata

    • Get metadata from your IdP (URL or XML)
    • Add it to Skycloak configuration
    • Save and test

Advanced Configuration Options

Signature Validation

Skycloak supports flexible SAML signature validation to work with various IdP configurations:

  • Default: Validates signatures on SAML responses (recommended)
  • RSA_SHA256: Default signature algorithm (most secure)
  • RSA_SHA1: Supported for legacy IdPs
  • Response vs Assertion Signatures: Some IdPs only sign the response, not the assertion - both patterns are supported

Note: For testing purposes, signature validation can be temporarily disabled, but this should never be done in production.

Metadata Import Behavior

When configuring SSO with metadata (URL or XML):

  1. Automatic Field Extraction: Entity ID and SSO URL are automatically extracted
  2. Priority Order:
    • Metadata URL (highest priority - always fetches latest)
    • Metadata XML (static snapshot)
    • Manual fields (lowest priority - only used if no metadata)
  3. Keycloak Processing: Metadata is passed directly to Keycloak for native processing

Tip: Using metadata URL ensures your configuration stays up-to-date with IdP changes.

Troubleshooting Guide

Issue: “Sign in with SAML” Button Not Visible

Solutions:

  1. Ensure SSO is enabled in Skycloak settings
  2. Clear browser cache and cookies
  3. Try incognito/private browsing mode
  4. Wait 2-3 minutes for changes to propagate

Issue: Authentication Fails

Check these common causes:

  1. Incorrect URLs

    • Verify Entity ID matches exactly
    • Ensure ACS URL has no typos
    • Check for trailing slashes

  2. Attribute Mapping Issues

    • Verify attribute names match exactly
    • Check case sensitivity
    • Ensure IdP is sending required attributes

  3. User Issues

    • Verify user’s email domain matches workspace domain
    • Ensure user is assigned to the application in IdP
    • Check user has required attributes populated

Issue: “Invalid SAML Response”

Solutions:

  1. Verify metadata is current (not expired)
  2. Check time sync between IdP and Skycloak
  3. Ensure SAML response is signed
  4. Validate certificate hasn’t expired

Issue: User Created but Cannot Access Resources

Check:

  1. User’s email domain matches workspace domain
  2. User has appropriate role assigned
  3. No conflicting security policies

Provider-Specific Known Issues

Google Workspace

  • RelayState Parameter: Google doesn’t always include RelayState in SAML responses. Skycloak automatically handles this when “Google Workspace (SAML)” is selected.
  • Authentication Binding: Google prefers HTTP-Redirect for authentication requests rather than POST.
  • Solution: Always select “Google Workspace (SAML)” as the provider type for automatic configuration.

Azure AD

  • Signature Algorithm: Older Azure AD configurations may use RSA_SHA1.
  • Claim Names: Azure uses full URIs for claim names (e.g., http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress).
  • Solution: Ensure attribute mappings use the full URI format.

Okta

  • Assertion Validity: Okta has strict time windows for assertion validity.
  • Solution: Ensure server time is synchronized (NTP).

Custom SAML Providers

  • Variable Behaviors: Custom providers may have unique requirements.
  • Solution: Skycloak uses permissive settings by default for custom providers (allows missing RelayState, flexible signature validation).

Best Practices

Before Going Live

  1. Test Thoroughly

    • Test with multiple user accounts
    • Verify attribute mapping works correctly
    • Test both login and logout flows

  2. Prepare Your Team

    • Send announcement email about SSO enablement
    • Provide login instructions
    • Share troubleshooting steps

  3. Maintain Fallback Access

    • Keep at least one admin account with password access
    • Document emergency access procedures
    • Test fallback authentication method

After Implementation

  1. Monitor Usage

    • Check event logs for failed authentications
    • Track adoption rate
    • Identify users having issues

  2. Regular Maintenance

    • Test SSO connection monthly
    • Update certificates before expiration
    • Review and update user assignments

  3. Security Reviews

    • Audit user access quarterly
    • Remove inactive users from IdP
    • Review and update security policies

Next Steps

After successfully configuring SSO:

  1. Enable MFA in Your IdP - Add extra security layer
  2. Configure Session Policies - Set appropriate timeout values
  3. Set Up Automated Provisioning - Streamline user management
  4. Review Audit Logs - Monitor authentication patterns
  5. Document Your Setup - Create internal documentation for your team

Getting Help

If you need assistance:

Setting Up Enhanced BrandingJWT Token Validation Best Practices