Last updated on 23rd February 2026

Setting up SAML Single Sign-On (SSO)

Single Sign-On (SSO) allows your users to authenticate using your organization's identity provider instead of managing separate passwords. DeployHQ supports SAML 2.0, which is compatible with popular identity providers such as Okta, Microsoft Entra ID (formerly Azure AD), Google Workspace, and Auth0.

SSO is available on Enterprise plans only.

Benefits of SSO

  • Centralized user management - Manage user access from your identity provider
  • Enhanced security - Leverage your organization's multi-factor authentication
  • Simplified onboarding and offboarding - Users are automatically provisioned and deprovisioned through your IdP
  • Compliance - Meet corporate security policies and audit requirements

Prerequisites

Before configuring SSO, ensure you have:

  • A DeployHQ account on an Enterprise plan
  • Administrator access to your identity provider (Okta, Microsoft Entra ID, Google Workspace, Auth0, etc.)
  • The ability to create a new SAML application in your identity provider

Configuring SSO

To set up SSO, head to the Settings tab at the top of the DeployHQ interface, then click SAML SSO in the left sidebar under Account Settings.

Step 1: Gather Service Provider Information

When you access the SAML SSO configuration page, you will see the Service Provider (SP) information that you need to provide to your identity provider:

  • ACS (Callback) URL: https://identity.deployhq.com/authentication/saml/acs - Also called Assertion Consumer Service URL or Reply URL
  • Entity ID: deployhq - Your IdP may call this "Audience" (Auth0), "SP Entity ID" (Okta), or "Identifier" (Entra ID)

Step 2: Configure Your Identity Provider

Create a new SAML application in your identity provider using the Service Provider information from Step 1. The exact steps vary by provider:

Okta: 1. Go to Applications and click Create App Integration 2. Select SAML 2.0 and click Next 3. Enter "DeployHQ" as the App name 4. For Single sign-on URL, enter the ACS URL 5. For Audience URI (SP Entity ID), enter deployhq 6. Set Name ID format to EmailAddress 7. Complete the setup and copy the Identity Provider metadata

Microsoft Entra ID: 1. Go to Enterprise Applications and click New Application 2. Click Create your own application 3. Select "Integrate any other application you don't find in the gallery (Non-gallery)" 4. Go to Single sign-on and select SAML 5. For Identifier (Entity ID), enter deployhq 6. For Reply URL (Assertion Consumer Service URL), enter the ACS URL 7. Download the Certificate (Base64) and copy the Login URL and Microsoft Entra Identifier

Google Workspace: 1. Go to Admin Console, then Apps, then Web and mobile apps 2. Click Add App, then Add custom SAML app 3. Enter "DeployHQ" as the App name 4. Copy the SSO URL, Entity ID, and download the Certificate 5. For ACS URL, enter the ACS URL from DeployHQ 6. For Entity ID, enter deployhq 7. Set Name ID format to EMAIL

Auth0: 1. Go to Applications and create a new Regular Web Application 2. Go to Addons and enable SAML2 Web App 3. For Application Callback URL, enter the ACS URL 4. In Settings, set "audience" to deployhq 5. Copy the Identity Provider Login URL, Issuer, and download the Certificate

Step 3: Enter Identity Provider Configuration in DeployHQ

Back in DeployHQ, enter the following information from your identity provider:

  • Identity Provider: Select your provider from the dropdown (Google Workspace, Okta, Microsoft Entra ID, Auth0, or Other SAML Provider)
  • Entity ID: The unique identifier for your identity provider (also called Issuer)
  • SSO URL: The URL where SAML authentication requests should be sent (also called Sign On URL or Login URL)
  • Certificate: The X.509 certificate from your identity provider. Include the -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- lines

Step 4: Enable SSO

Check the Enable SAML SSO checkbox to allow users to authenticate via your identity provider.

Click Save Configuration to save your settings.

Testing SSO

Before enforcing SSO for all users, test that the configuration works correctly:

  1. Open a new incognito or private browser window
  2. Go to the DeployHQ login page
  3. Click Sign in with SSO
  4. Enter your account domain when prompted
  5. You should be redirected to your identity provider to authenticate
  6. After successful authentication, you should be logged into DeployHQ

Enforcing SSO

Once you have verified that SSO works correctly, you can optionally enforce SSO for all users in your account. This will disable password-based login and require all users to authenticate via your identity provider.

To enforce SSO:

  1. Go to Settings, then SAML SSO
  2. Click Edit Configuration
  3. Check the Enforce SSO (disable password login) checkbox
  4. Click Update Configuration

Warning: Before enabling SSO enforcement, ensure: - SAML login has been tested and works correctly - All users who need access are assigned to the DeployHQ application in your identity provider - You have a backup administrator account or recovery plan in case of IdP issues

When SSO enforcement is enabled, the following settings are automatically disabled as they are no longer relevant: - Two-factor authentication requirement - Strong password requirement

Managing Your SSO Configuration

Editing Configuration

To update your SSO configuration (for example, to update an expiring certificate):

  1. Go to Settings, then SAML SSO
  2. Click Edit Configuration
  3. Make your changes
  4. Click Update Configuration

Certificate Expiration

DeployHQ will display a warning if your identity provider certificate is expiring within 30 days. To avoid SSO disruption, update your certificate before it expires:

  1. Generate or obtain a new certificate from your identity provider
  2. Edit your SSO configuration in DeployHQ
  3. Paste the new certificate in the Certificate field
  4. Click Update Configuration

Removing SSO Configuration

To remove SSO from your account:

  1. Go to Settings, then SAML SSO
  2. Click Remove Configuration
  3. Confirm the removal

Note: If SSO enforcement is enabled, it will be automatically disabled when the configuration is removed. Users will need to set up passwords to log in.

Troubleshooting

Users cannot log in via SSO

  • Verify the user is assigned to the DeployHQ application in your identity provider
  • Check that the user's email address in your IdP matches their DeployHQ account email
  • Ensure the SSO configuration is enabled in DeployHQ
  • Verify the Entity ID and ACS URL are correctly configured in your IdP

Certificate errors

  • Ensure you have copied the complete certificate including the BEGIN and END lines
  • Check that the certificate has not expired
  • Download a fresh certificate from your identity provider

SSO enforcement locked out administrator

If you have enforced SSO and are locked out due to IdP issues:

  • Contact DeployHQ support for assistance with account recovery
  • Ensure you have documented your IdP configuration for disaster recovery

User Attribute Mapping

DeployHQ automatically maps user attributes from common identity providers. The following attributes are used:

  • Email address: Used as the primary identifier for the user account
  • First name and last name: Used to update the user profile (if provided)

For most identity providers (Okta, Microsoft Entra ID, Google Workspace, Auth0), attribute mapping is handled automatically. If you are using a custom SAML provider, ensure your IdP sends the email address in the NameID field or as an attribute.