Microsoft Azure AD (AAD) is a Directory-as-a-Service provided by Azure. Zeplin SAML SSO is confirmed to work with AAD.
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!
- Configure AAD from the Azure Administrative Portal (https://portal.azure.com)
- Log in to Zeplin (https://app.zeplin.io) as an Owner or Admin for your Zeplin Organization
- Select Azure Active Directory in the main navigation panel
- Select Enterprise Applications from the subcategory panel
- Click the “+ New application” button, and add a Non-gallery application.
- Select Single sign-on from the subcategory panel, and choose type SAML.
- In Section 2 (User Attributes & Claims), select [ + Add new claim ] and add an attribute:
- Name: email
- Source: user.mail
- In Section 3 (SAML Signing Certificate), Download Certificate (Base64)
Don’t click save or validate just yet.
- 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 AAD field Login URL into the Zeplin field IdP SAML 2.0 Endpoint
- Copy the string from the AAD field Azure AD Identifier into the Zeplin field IDP Issuer
- Copy the contents of the AAD 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 Azure:
- 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 AAD “Users and Groups” in Enterprise Applications (from the subcategory panel). Select the appropriate Group in AAD, and assign the Zeplin application and specific users if required.
Extra information for AAD 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.
- AAD 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.
- AAD can optionally sign the Assertion. Zeplin will verify the signature against the AAD-generated IdP Public Certificate.
- By default, AAD 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 AAD supports.