All Collections
Enterprise Plan
Setting up SSO
Generic Identity Provider and SAML 2.0
Generic Identity Provider and SAML 2.0

Setting up Zeplin with a SAML 2.0-based Identity Provider

Rian avatar
Written by Rian
Updated over a week ago

Zeplin SAML SSO is confirmed to work with multiple SAML 2.0 compliant Identity Providers (IdP). You can find several help articles specific for many popular IdP here. This article describes how to set up Zeplin with a non-specific SAML 2.0-based IdP.

☝️ This feature is only available to teams on the Enterprise Plan.

Before you begin

Zeplin generates the configuration parameters needed by your IdP during the configuration process, which needs the IdP settings. Some IdP do not provide their parameters until after they receive the Zeplin-generated parameters. If your IdP is one of these, contact us at success@zeplin.io to manually generate and supply your specific SP EntityID and SSO URL.

Configuration

  • Log in to Zeplin (https://app.zeplin.io) as an Owner or Admin for your Zeplin Organization.

  • Configure your IdP from its own IdP administrative console.

Configuring Zeplin

  • From the Organization Dashboard, click the settings button on the top right to access Settings, and select the AUTHENTICATION tab

  • Next to the SAML 2.0 option, click on the “Enable” button

  • In the Zeplin popup:
      - The Zeplin field IdP SAML 2.0 Endpoint is the IdP's URL that is listening for an authentication request. It will likely be called something similar to Single Sign On Service URL.  If your IdP offers different entries for different bindings, choose the one for “HTTP-POST” (often called just “POST”).
    - The Zeplin field IdP Issuer is the identifier that your IdP gives this connection. The IdP will likely call this field IdP Issuer or IdP Entity ID.
      - The Zeplin field IdP Public Certificate is the public half of the digital certificate that proves the response from the IdP is legitimate. The IdP will call it something like “Signing Certificate” or “Public X.509 Certificate”, and it will look like a block of text starting with “---BEGIN CERTIFICATE ---”. On some IdP, the certificate might be a file, and you will need to copy the file contents into this field.

  • Click on the “Enable” button

  • Click Download SAML 2.0 metadata.

Configuring your IdP

  • If your IdP can interpret SP Metadata files, simply upload the metadata file you just downloaded from Zeplin. If not, you will need to enter at least two fields:
      - The value of SP EntityID we gave you is the identifier that Zeplin gives this connection. It will need to be entered in a field on the IdP named something like Entity ID or Audience URI.
      - The value of SSO URL we gave you is the URL on Zeplin that is listening for the authentication response. It will need to be entered in a field on the IdP named something like Single SignOn URL, ACS, or Consumer Assertion Service.

  • An attribute, sometimes called a claim, must be added to the connection.
      - Name:  email
    ​  - Format: unspecified. Optionally, email-address format will also be accepted.
      - Value: the Zeplin-known email address of the user
    Zeplin uses the email address as the identity of the user. This attribute can be sent as a multi-value attribute - that is, it may have multiple values such as all the known email aliases of this user. If more than one email address is sent in this way, Zeplin will search for, and use, the first Zeplin-known email address in the list.

Confirm everything works!

Go to the Zeplin login page, and click on the Login with SSO link (or go directly to https://app.zeplin.io/login/sso). Enter the email address of an existing Zeplin user. You should redirect to your 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. Generally, this is via a user group defined on the IdP. Find appropriate Group in your IdP, and assign the Zeplin application and specific users 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

  • Some IdP send the session duration value in its SAML assertion. Zeplin will expire and attempt session re-authentication at the shorter of the IdP-sent duration, or the duration chosen in the Zeplin setting Session Timeout on the AUTHENTICATION tab in Zeplin’s Organization settings. The default value is to never log out the user.

  • IdP can sign either the Assertion, Response, or both. Zeplin will enforce a valid signature against the IdP Public Certificate.

  • IdP can encrypt the Assertion. Zeplin will accept unencrypted assertions, and also assertions encrypted with the Zeplin-generated x.509 certificate (uploaded as part of the Zeplin SP metadata, or contact us to supply it in a separate file). Zeplin can decrypt all of the ciphers in common use by IdP.

Did this answer your question?