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 the 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

   • Navigate to portal.azure.com
   • Go to Azure Active Directory

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 Security in the sidebar (under Workspace)
   • 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.

2. User Attributes & Claims

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

3. 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 Security in the sidebar (under Workspace), then the SSO section
   • 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).

3. Attribute Statements Add the following attributes:

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

4. 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

   • Go to admin.google.com
   • Navigate to Apps → Web and mobile apps

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:

• Check our Workspace SSO Documentation
• Contact support with your workspace ID and specific error messages