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

- [Okta Help Center: Create SAML app integrations](https://help.okta.com/en-us/content/topics/apps/apps_app_integration_wizard_saml.htm) — outlines the Admin Console flow for building a SAML 2.0 app integration and gathering IdP metadata.