Microsoft ADFS is a Single Sign-On solution allowing SAML authentication for applications that do not directly connect to Microsoft Active Directory. Zeplin is confirmed to work with ADFS.

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

Before you begin

The ADFS - Zeplin SAML integration can be configured by yourself without Zeplin needing to be involved. If you need help, feel free to contact us at success@zeplin.io!

Zeplin requires ADFS information before it generates the information required by ADFS. ADFS only supplies these values in a metadata file, but at this time, Zeplin cannot import it. You will need to extract these values from the ADFS metadata file manually.

Configuration

Configure ADFS from the ADFS server's ADFS Management Console.
Log in to Zeplin (https://app.zeplin.io) as an Owner or Admin for your Zeplin Organization.

In ADFS:

Make a note of the EntityID, X509Certificate, and SSOService Location values in your ADFS IdP metadata file (FederationMetadata.xml). You can find your ADFS Federation Metadata file URL on the ADFS server through the ADFS Management in AD FS > Service > Endpoints and go to the section Metadata. It should look like this: sts.yourdomain.com/FederationMetadata/2007-06/FederationMetadata.xml

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 ADFS field SSOService Location into the Zeplin field IdP SAML 2.0 Endpoint
- Copy the string from the ADFS field EntityID into the Zeplin field IdP Issuer.
- Copy the string from the ADFS X509Certificate into the Zeplin field IdP Public Certificate

Click on the “Enable” button
Click on the “Download SAML 2.0 metadata” link.

Back in ADFS:

Click Add Relying Party Trust… in the Actions pane. On the Welcome step, click Start. Select Import data about the relying party from a file, and import the metadata file just downloaded from Zeplin. Click through the remaining screens and click Close to finish the wizard.
Select your relying party trust and click Edit Claim Rules…. In the Issuance Transform Rules tab, create a new claim:
RULE #1
- Template: Send LDAP Attributes as Claims
- Name: email
- Attribute Store: Active Directory
- LDAP Attribute: E-Mail-Addresses
- Outgoing Claim Type: E-Mail Address
RULE #2
- Template: Transform an Incoming Claim
- Name: email
- Incoming Claim Type: E-Mail Address
- Outgoing Claim Type: Name ID
- Outgoing Name ID format: Email
From the services manager, restart ADFS service.

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 ADFS 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 ADFS "Issuance Authorization Rules". Select the appropriate group mechanism for your Company policies.

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 ADFS users

ADFS does not send the session duration value in its SAML assertion. Zeplin will expire and attempt session re-authentication at 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.
ADFS can optionally sign the Assertion. Zeplin will verify the signature against the ADFS-generated IdP Public Certificate.
By default, ADFS does not encrypt the Assertion. Zeplin will accept unencrypted assertions, and also assertions encrypted with the Zeplin-generated x.509 certificate (included in the Zeplin metadata file). Zeplin can decrypt all of the ciphers that ADFS supports.