All Collections
Enterprise Plan
Setting up SSO
Azure (Entra ID), SAML 2.0, and SCIM
Azure (Entra ID), SAML 2.0, and SCIM

Setting up Zeplin with Microsoft Entra ID (previously known as Azure AD) for Single Sign-On and SCIM

Rian avatar
Written by Rian
Updated over a week ago

Microsoft Azure - now renamed to Microsoft Entra ID - includes a Directory-as-a-Service. Zeplin's SAML SSO and user provisioning with SCIM are confirmed to work with Entra ID.

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

Before you begin

Entra ID does not generate application details (needed by Zeplin) until it has Zeplin-generated values (which need Entra ID data to generate). You will need to contact us at success@zeplin.io to have us manually generate and supply your specific SSO URL and SP EntityID.

Configuration

In Azure:

  • Select Microsoft Entra ID in the main navigation panel

  • Select Enterprise Applications from the subcategory panel

  • Click the “+ Create your own application” link, and add a Non-gallery application.

  • Click on Setup single sign on in the Getting Started section, and select SAML.

  • In Section 1 (Basic SAML Configuration):

    • Enter the SP EntityID we gave you into the Entra ID field Identifier (Entity ID)

    • Enter the SSO URL we gave you into the Entra ID field Reply URL (Assertion Consumer Service URL)

    • Leave the other fields on this page blank, and click Save

  • In Section 2 (Attributes & Claims), select [ + Add new claim ] and add an attribute:
      - Name: email
    - Namespace: leave blank
    ​  - Source: user.mail

  • In Section 3 (SAML Signing Certificate), click to Download Certificate (Base64)

Don’t click Test just yet.

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 Entra ID field Login URL into the Zeplin field IdP SAML 2.0 Endpoint
    ​   - Copy the string from the Entra ID field Azure AD Identifier into the Zeplin field IDP Issuer
    ​  - Copy the contents of the Entra ID SAML Signing Certificate you downloaded into the Zeplin field IdP Public Certificate

  • Click on the “Enable” button

  • Click on the “Download SAML 2.0 metadata”

Back in Entra ID:

  • At the top of the screen, click on the “Upload metadata file” button and upload the file just downloaded from Zeplin

  • Click on the “Validate this application”

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 AAD 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 Entra ID “Users and Groups” in Enterprise Applications (from the subcategory panel). Select the appropriate Group in Entra ID, 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.

User Provisioning with SCIM

Entra ID can autoprovision users in Zeplin using the SCIM protocol. See the article User Provisioning With SCIM for detailed configuration information. In Entra ID, the SCIM integration is configured and enabled by selecting Provisioning in the right sidebar menu when configuring an Application.

Many Entra ID setups will attempt to use SCIM to create actual groups on Zeplin (as opposed to creating all the users in an Entra ID group). Make sure that Group mapping is disabled in the Mappings submenu.

Extra information for Entra ID Configurations

SSO Notes

  • Entra ID does not send the session duration value in its SAML assertion. Zeplin will expire and attempt session re-authentication only 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.

  • Entra ID can optionally sign the Assertion. Zeplin will verify the signature against the Entra ID-generated IdP Public Certificate.

  • By default, Entra ID does not 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). Zeplin can decrypt all of the ciphers that Entra ID supports.

SCIM Notes

  • EntraID may report that "Provisioning has been quarantined", with the error "An HTP/404 Not Found response was returned", even though there is no error in the Provisioning logs to explain what has gone wrong. If this occurs to you, double-check you are not attempting to manage Groups over SCIM (this should be disabled in the Mappings section on the Provisioning tab) and stop/start Provisioning. If this does not clear the error, reach out to us at support@zeplin.io to help investigate.

Did this answer your question?