Okta is an Identity-as-a-Service. Zeplin's SAML SSO and user provisioning with SCIM are confirmed to work with Okta.

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

Before you begin

Okta does not generate application details (needed by Zeplin) until it has Zeplin-generated values (which need Okta 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

Configure Okta from the Okta Admin Console (https://<yourorg>.admin.okta.com).
Log in to Zeplin (https://app.zeplin.io) as an Owner or Admin for your Zeplin Organization

In Okta:

Select Applications from the main navigation sidebar
Click the “Create App Integration” button, and choose SAML 2.0 as the Sign on method
Add a name for this application in General Settings, and click on the “Next” button
Under SAML Settings > General
- Enter the SSO URL we gave you into the Okta field Single sign on URL
- Enter the SP EntityID we gave you into the Okta field Audience URI (SP Entity ID)

Under SAML Settings > Attribute Statements (optional), add a new Attribute:
- Name: email
- Name Format: leave blank / Unspecified
- Value: user.email
Click the “Next” button then “Finish” button
In the Sign On tab, click on the “View Setup Instructions” button. A new browser tab will open with the information you need to enter into Zeplin.

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 Okta field Identity Provider Single Sign-On URL into the Zeplin field IdP SAML 2.0 Endpoint
- Copy the string from the Okta field Identity Provider Issuer into the Zeplin field IDP Issuer
- Copy the contents of the Okta field X.509 Certificate into the Zeplin field IdP Public Certificate
Click on the “Enable” button

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 Okta 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. Usually, this is via an existing Okta user group that will need to be assigned to the Application. Select an appropriate group on the Application's Assignments tab, 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

Okta can autoprovision users in Zeplin using the SCIM protocol. See the article User Provisioning With SCIM for configuration information. In Okta, the SCIM integration is enabled on the General tab under App Settings:

which will enable the Provisioning tab. Configure the connection on the Integration screen, and then enable the required actions on the To App screen.

Extra information for Okta users

Okta does not send a session duration value in its SAML assertion. Zeplin will expire and attempt re-authentication only at the duration set in the Session Timeout field (see the AUTHENTICATION tab in Zeplin’s Organization settings). The default value is to never log out the user.
By default, Okta signs both Assertion and Response. Zeplin will enforce a valid signature against the Okta-generated IdP Public Certificate.
By default, Okta does not encrypt the Assertion. Zeplin will accept unencrypted assertions, and also assertions encrypted with the Zeplin-generated x.509 certificate (available from Zeplin Support). Zeplin can decrypt all of the ciphers that Okta supports.