Keycloak is an Identity Management server, usually located on-premise. Zeplin's SAML SSO is confirmed to work with Keycloak.
☝️ This feature is only available to teams on the Enterprise Plan.
Before you begin
You will need to extract the IdP values from Keycloak's IdP Metadata File, as Keycloak does not show these values in it's Administration interface.
Your IdP Metadata file can be displayed from the Keycloak Administration console. Select Realm Settings from the main navigation sidebar, and on the General tab, click on Endpoints > SAML 2.0 Identity Provider Metadata.
Make a note of the EntityID, X509Certificate, and SingleSignonService Location values in your realm's IdP metadata file. If you have multiple choices for the SSO Location value, choose the HTTP-POST binding.
The fields should be similar to:
EntityID (a.k.a. IdP Issuer): http://idp.example.com:8080/realms/ExampleCorp
X509 Certificate (a.k.a. Public Certificate): MIIC...................c0F=
SingleSignOnService Location (a.k.a. SAML Endpoint):
Configuration
Configure Keycloak from the Keycloak Administration Console
Log in to Zeplin (https://app.zeplin.io) as an Owner or Admin for your Zeplin Organization
In Zeplin:
From the Organization Dashboard, click the settings button on the top right to access Settings, and select the AUTHENTICATION tab.
In the SAML 2.0 section, click on the “Enable” button
In the Zeplin popup:
- Copy the string from the IdP Metadata field SSOService Location into the Zeplin field IdP SAML 2.0 Endpoint
- Copy the string from the IdP Metadata field EntityID into the Zeplin field IdP Issuer.
- Copy the string from the IdP Metadata field X509Certificate into the Zeplin field IdP Public Certificate
Click on the “Enable” button
Click on the “Download SAML 2.0 metadata” link.
In Keycloak:
Select Clients from the main navigation sidebar
Add a new client and upload the details by clicking Import client (or click Create and then Import in the older interface), and upload the file just downloaded from Zeplin.
In the Clients > [client] > Keys tab (or the > Settings tab in older versions)
Turn OFF the setting "Client Signature Required", and click Save
If your version of Keycloak shows a Clients > [client] > Mappers tab (older versions):
Click Create to add a new Attribute, and enter the details below:
Protocol: saml
Name: email
Mapper Type: User Attribute
User Attribute: email
SAML Attribute Name: email
SAML Attribute NameFormat: Unspecified
Click Save
Otherwise, if your Keycloak is a more current version:
Select Client scopes from the main navigation sidebar
Click Create client scope and add a scope with the details below:
Name: saml-email
Protocol: SAML
Click Save, then select the Client Scope > [scope] > Mappers tab
Click Configure a new mapper > User Attribute, and enter the details below:
Mapper Type: User Attribute
Name: email
User Attribute: email
SAML Attribute Name: email
SAML Attribute NameFormat: Unspecified
Click Save
Return to Clients > [client] and click Add client scope
Select saml-email, click Add, and select "Default"
Confirm everything works!
Go to the Zeplin login page, and click the link that says Login with SSO (or go directly to https://app.zeplin.io/login/sso). Enter the email address of an existing Zeplin user. You should redirect to your Keycloak IdP to authenticate, then back to that user's Project page.
Your company may have policies in place that will require the Zeplin app to first be assigned to users. Keycloak achieves this via custom-written authentication flows, which is unique to your company and beyond the scope of this guide. Discuss with your Keycloak administrators of how your company has implemented access restrictions to Clients if required.
Finishing Up
When it is confirmed users can log in with SAML, you can restrict login to be via SAML only for all users in your domain by setting Require SSO on the AUTHENTICATION tab in Zeplin.
Don't Require: Users can continue to log in with username/password or SSO
Require for All Members: Users in your domain who try to log in with username/password will be redirected to your IdP instead.
☝️ For safety, the Owner will still be able to log in using their username/password even if this option is set to Require.
You can specify a Session timeout. Zeplin will check with your IdP at the shorter period of this setting and the Session Duration as sent by your IdP (if it sends one) to verify the user is still authenticated.
You can choose to Allow inviting users from different domains. If not ticked, only users with an email address in your domain will be permitted to be invited to the Workspace.
Extra information for Keycloak users
Keycloak sends a session duration value in its SAML assertion by default. Zeplin will expire and attempt re-authentication at the shorter of this time, or the duration set in the Session Timeout field (see the AUTHENTICATION tab in Zeplin’s Organization settings).
Keycloak can sign the Message, the Assertion, or both. Zeplin will enforce valid signatures against the Keycloak-generated IdP Public Certificate.
By default, Keycloak encrypts the Assertion. Zeplin will accept unencrypted assertions, and also assertions encrypted with the Zeplin-generated x.509 certificate (imported into Keycloak during the Client creation step, or available from Zeplin Support). Zeplin can decrypt all of the ciphers that Keycloak supports.