SSO & SAML

Overview

Single sign-on (SSO) allows your organization's members to authenticate with Unpack using your existing identity provider (IdP). Instead of managing separate passwords, team members sign in through the same credentials they use for other company applications. Unpack supports SAML 2.0, which is compatible with all major identity providers including Okta, Azure Active Directory, Google Workspace, OneLogin, and PingIdentity.

How SSO Works in Unpack

When SSO is configured for your organization, the sign-in flow changes:

1. A user navigates to the Unpack sign-in page and enters their email address.
2. Unpack checks whether the email domain is associated with an SSO-enabled organization (the discovery step).
3. If a match is found, the user is redirected to your identity provider's login page.
4. The user authenticates with their corporate credentials (and any MFA your IdP requires).
5. The IdP sends a SAML assertion back to Unpack, confirming the user's identity.
6. Unpack creates or updates the user's account, signs them in, and redirects to their dashboard.

Users who belong to an SSO-enabled organization cannot sign in with a password. All authentication is handled through the identity provider.

Prerequisites

• An active Enterprise plan for your Unpack organization.
• Admin access to your identity provider (Okta, Azure AD, Google Workspace, etc.).
• The email domain you want to associate with SSO. All users with this domain will be required to authenticate through your IdP.

Setting Up a SAML Provider

Step 1: Create a SAML Application in Your IdP

In your identity provider, create a new SAML 2.0 application with the following settings:

• Assertion Consumer Service (ACS) URL: https://app.unpackretros.com/auth/saml/callback
• Entity ID (Audience): https://app.unpackretros.com/auth/saml/metadata
• Name ID Format: emailAddress
• Name ID Value: The user's email address

Configure these attribute statements so Unpack can populate user profiles:

• email → User's email address (required)
• first_name → User's first name (recommended)
• last_name → User's last name (recommended)

Step 2: Gather Your IdP Details

After creating the application, your identity provider will supply the following:

• IdP SSO URL — The URL where Unpack redirects users for authentication.
• IdP Entity ID — A unique identifier for your identity provider.
• X.509 Certificate — The public certificate used to verify SAML assertions.

Step 3: Configure SAML in Unpack

1. Navigate to Organization Settings → Security → Single Sign-On.
2. Click Configure SAML.
3. Enter the email domain to associate with SSO (for example, yourcompany.com).
4. Choose your configuration method:
   • Manual entry: Paste the IdP SSO URL, IdP Entity ID, and X.509 Certificate into the corresponding fields.
   • Metadata import: Paste the metadata XML URL or upload the metadata XML file. Unpack will parse it and populate the fields automatically.
5. Click Save Configuration. The configuration is saved in a draft state until you test and activate it.

Importing SAML Metadata

If your identity provider publishes a metadata XML endpoint, Unpack can import the configuration automatically. This avoids manual entry errors and simplifies certificate rotation.

1. In the SAML configuration form, select the Import from URL tab.
2. Paste the metadata URL provided by your identity provider.
3. Click Import. Unpack fetches the metadata and populates the IdP SSO URL, Entity ID, and X.509 Certificate fields.
4. Review the imported values to ensure they are correct, then click Save Configuration.

Alternatively, if you have a downloaded metadata XML file, select the Upload File tab and upload the file directly.

Testing and Activating SSO

Before activating SSO for all users, test the configuration:

1. On the SSO settings page, click Test Configuration.
2. A new browser tab opens and redirects you to your identity provider. Sign in with a test account.
3. If the SAML assertion is valid, Unpack displays a success page confirming the user's email, first name, and last name were received correctly.
4. If the test fails, an error message describes the issue (mismatched ACS URLs, expired certificates, or incorrect Name ID formats).

After a successful test, click Activate SSO and confirm. From this point forward, all users with the configured email domain will be required to sign in through your identity provider.

SSO Discovery Flow

Unpack uses email-based discovery to route users to the correct sign-in method:

1. The user enters their email address on the Unpack sign-in page.
2. Unpack extracts the email domain and checks for an SSO configuration matching that domain.
3. If a match is found, the password field is hidden and a Sign in with SSO button appears, redirecting to the IdP.
4. If no match is found, the standard email and password sign-in form is shown.

Users do not need to remember a special SSO URL. They enter their email and Unpack handles the routing automatically.

Managing the SAML Provider

Updating the Certificate

When your identity provider's X.509 certificate approaches expiration, update it in Unpack:

1. Navigate to Organization Settings → Security → Single Sign-On.
2. Click Edit Configuration.
3. Replace the X.509 Certificate with the new one, or click Re-import Metadata to pull the updated certificate automatically.
4. Click Save Configuration and test to verify the new certificate works.

Changing the Email Domain

1. Click Edit Configuration on the SSO settings page.
2. Update the email domain to the new value.
3. Save and test the updated configuration.
4. Ensure existing users update their email addresses in Unpack to match the new domain.

Deactivating SSO

1. Navigate to Organization Settings → Security → Single Sign-On.
2. Click Deactivate SSO and confirm.
3. Users with the configured email domain will be prompted to set a password on their next sign-in.

Troubleshooting

• "Invalid SAML response" error: Verify that the ACS URL and Entity ID in your identity provider match the values in Unpack's SSO settings exactly. Trailing slashes and protocol differences matter.
• Certificate validation failed: Ensure the X.509 certificate in Unpack has not expired and matches the certificate your IdP uses to sign assertions.
• User not found after sign-in: Verify your IdP is sending the email attribute with the correct Name ID format (emailAddress).
• Users not redirected to SSO: Confirm the email domain in the SSO configuration matches the users' email domains exactly.
• Locked out of the organization: Contact support@unpackretros.com to temporarily disable SSO enforcement so you can access the settings and fix the configuration.