Skip to main content

SAML SSO (Single Sign-On)

SAML 2.0 Single Sign-On allows your organization members to authenticate through your company's identity provider (IdP). SSO supports Okta, Microsoft Entra ID (Azure AD), Google Workspace, and custom SAML 2.0 providers.

Requirements​

  • Pro plan — SSO is available on the Pro plan
  • Organization owner or admin — required to configure SSO settings

Supported Identity Providers​

ProviderStatus
OktaSupported
Microsoft Entra ID (Azure AD)Supported
Google WorkspaceSupported
Custom SAML 2.0Supported

How It Works​

  1. User visits the Envshed login page and enters their email
  2. Envshed detects the user's organization has SSO enabled
  3. User is redirected to the identity provider for authentication
  4. IdP authenticates the user and sends a SAML assertion back to Envshed
  5. Envshed validates the assertion, provisions the user if needed, and creates a session
  6. User is redirected to the dashboard

Setting Up SSO​

Step 1: Get SP Metadata​

Before configuring your IdP, you need the Service Provider (SP) metadata from Envshed:

  1. Go to Organization Settings → SSO
  2. Click Configure SSO
  3. Note the following values (shown after initial setup):
    • SP Entity ID: https://app.envshed.com/api/sso/saml/<your-org-slug>/metadata
    • ACS URL: https://app.envshed.com/api/sso/saml/<your-org-slug>/acs

You can also download the SP metadata XML from the metadata URL.

Step 2: Configure Your IdP​

Okta​

  1. In Okta Admin Console, go to Applications → Create App Integration
  2. Select SAML 2.0
  3. Enter the app name (e.g., "Envshed")
  4. Set the Single sign-on URL to the ACS URL from Step 1
  5. Set the Audience URI (SP Entity ID) to the SP Entity ID from Step 1
  6. Set Name ID format to EmailAddress
  7. Under Attribute Statements, add:
    • email → user.email
    • firstName → user.firstName
    • lastName → user.lastName
  8. Complete the setup and copy the IdP Entity ID, SSO URL, and X.509 Certificate

Microsoft Entra ID (Azure AD)​

  1. In Azure Portal, go to Enterprise Applications → New Application
  2. Click Create your own application and select SAML
  3. In Basic SAML Configuration:
    • Identifier (Entity ID): SP Entity ID from Step 1
    • Reply URL (ACS URL): ACS URL from Step 1
  4. Under User Attributes & Claims, ensure emailaddress is mapped
  5. Download the Certificate (Base64) from the SAML Signing Certificate section
  6. Copy the Login URL and Azure AD Identifier from the Set up section

Google Workspace​

  1. In Google Workspace Admin, go to Apps → Web and mobile apps → Add App → Add custom SAML app
  2. Copy the SSO URL, Entity ID, and download the Certificate
  3. In Service Provider Details:
    • ACS URL: ACS URL from Step 1
    • Entity ID: SP Entity ID from Step 1
    • Name ID format: EMAIL
  4. Add attribute mappings for email, firstName, lastName

Step 3: Configure Envshed​

  1. Go to Organization Settings → SSO
  2. Click Configure SSO
  3. Select your identity provider
  4. Enter the IdP Entity ID, IdP SSO URL, and paste the IdP Certificate
  5. Configure auto-provisioning and default role settings
  6. Click Save SSO Configuration

SSO Settings​

Enforce SSO​

When enabled, all organization members (except owners) must use SSO to log in. Email-based login will be blocked for non-owner members.

Important: Organization owners always retain email login as a fallback to prevent lockout scenarios.

Auto-Provision Users​

When enabled, users who authenticate through SSO for the first time are automatically:

  • Created in Envshed with their SSO email and name
  • Added to the organization with the configured default role

When disabled, users must be manually invited to the organization before they can log in via SSO.

Default Role​

The organization role assigned to auto-provisioned users. Options:

  • Admin — full organization access
  • Member — standard access (recommended)
  • Viewer — read-only access

Troubleshooting​

"SSO is not configured for this organization"​

Ensure that:

  • Your organization is on the Pro plan
  • An admin has completed SSO configuration
  • The SSO configuration is marked as active

SAML assertion errors​

Common issues:

  • INVALID_SIGNATURE: The IdP certificate in Envshed doesn't match the one your IdP is using. Re-upload the certificate.
  • INVALID_ISSUER: The IdP Entity ID in Envshed doesn't match what your IdP is sending. Verify the entity ID.
  • INVALID_AUDIENCE: The SP Entity ID configured in your IdP doesn't match. Check the audience restriction.
  • ASSERTION_EXPIRED: Clock skew between your IdP and Envshed. Ensure your IdP's clock is synchronized.
  • MISSING_EMAIL: Your IdP is not sending an email attribute. Add email to the attribute mapping.

Users can't log in after enabling SSO enforcement​

  • Organization owners can always use email login as a fallback
  • Disable enforcement temporarily to allow users to access the dashboard
  • Check that your IdP is correctly configured and active

Certificate rotation​

When your IdP's signing certificate is rotated:

  1. Download the new certificate from your IdP
  2. Go to Organization Settings → SSO
  3. Update the IdP Certificate field with the new certificate
  4. Both old and new certificates will work during the transition period in most IdPs