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.
Before you begin
AAD and Zeplin can be configured by yourself without Zeplin needing to be involved. If you need help, feel free to contact us at firstname.lastname@example.org!
Zeplin requires ADFS information before it will generate the information required by ADFS. At this time, Zeplin cannot extract these values from the ADFS metadata file itself. You will need to extract these values from the ADFS metadata file manually.
- 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
- Copy the EntityID, X509Certificate and SSOService Location from your ADFS IdP metadata (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 section Metadata. It should look like this: https://sts.yourdomain.com/FederationMetadata/2007-06/FederationMetadata.xml.
- 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 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:
- Template: Send LDAP Attributes as Claims
- Name: email
- Attribute Store: Active Directory
- LDAP Attribute: E-Mail-Addresses
- Outgoing Claim Type: E-Mail Address
- 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.
Extra information for ADFS users
- When it is confirmed users can log in with SAML, you can restrict login to be via via SAML only for all users by selecting this option from the AUTHENTICATION tab in Zeplin. For safety, the Owner will still be able to log in using their username/password after this option is set.
- 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 ADF-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. Zeplin can decrypt all of the ciphers that ADFS supports.