Last updated on 23rd February 2026

Configuring SSO with Okta

This guide walks through connecting DeployHQ to Okta using SAML 2.0 so that your team can sign in with their company credentials. Follow the steps below in Okta first, then finish the setup inside DeployHQ.

Prerequisites

  • DeployHQ account on the Enterprise plan with access to Settings → SAML SSO
  • Okta administrator permissions
  • Users or groups in Okta that you can assign to the DeployHQ application

Step 1: Create a SAML application in Okta

  1. Open the Okta Admin Console and go to Applications → Applications.
  2. Click Create App Integration, choose SAML 2.0, and click Next.
  3. Enter "DeployHQ" (or another helpful name) and optionally upload the DeployHQ logo.
  4. Under SAML Settings, configure the following values:
    • Single sign-on URL: https://identity.deployhq.com/authentication/saml/acs
    • Audience URI (SP Entity ID): deployhq
    • Name ID format: EmailAddress
    • Application username: Email
  5. (Optional) Add attribute statements so DeployHQ can prefill user names:
    • FirstName → user.firstName
    • LastName → user.lastName
  6. Click Next, review the configuration, then click Finish.

Step 2: Assign people

DeployHQ will only allow SSO for users assigned to the Okta app:

  1. On the Okta application page, go to the Assignments tab.
  2. Click Assign and choose People or Groups.
  3. Select every DeployHQ user that should authenticate via Okta and click Assign.

Step 3: Collect Okta identity provider details

From the Sign On tab in Okta, click View SAML setup instructions and copy the following information:

  • Identity Provider Issuer (sometimes shown as http://www.okta.com/...)
  • Identity Provider Single Sign-On URL
  • X.509 Certificate (download as text or copy the certificate body)

These values map to the DeployHQ fields in the next step.

Step 4: Configure DeployHQ

  1. In DeployHQ, go to Settings → SAML SSO and click Configure SAML SSO (or Edit Configuration if one already exists).
  2. Enter the values you copied from Okta into the form:
    • Issuer → Okta Identity Provider Issuer
    • Login URL → Okta Identity Provider Single Sign-On URL
    • Certificate → Paste the full X.509 certificate, including the BEGIN CERTIFICATE and END CERTIFICATE lines
  3. Ensure the Enable SAML SSO checkbox stays selected and click Save Configuration.

Step 5: Test and enforce (optional)

  1. Open an incognito browser and navigate to the DeployHQ login screen.
  2. Click Sign in with SSO, enter your DeployHQ subdomain, and complete the Okta login flow.
  3. After confirming that sign-in works for several users, you can optionally enable Enforce SSO (disable password login) on the SAML SSO page to prevent password-based logins.

Troubleshooting tips

  • Users redirected back to the login page: Verify the user is assigned to the Okta application and that their email matches the DeployHQ user record.
  • Invalid certificate errors: Copy the complete certificate block from Okta, including header/footer lines, and ensure it has not expired.
  • NameID mismatch: Confirm the Name ID format is EmailAddress and the Application username is set to email.

Official resources