DeployHQ supports SAML 2.0, so you can integrate it with Microsoft Entra ID (formerly Azure AD) for centralized sign-on and enforcement of your corporate security controls.

## Prerequisites

- DeployHQ Enterprise plan with access to **Settings → SAML SSO**
- Microsoft Entra ID tenant where you are a Global Administrator or have Application Administrator permissions
- Users or groups that should be granted access to DeployHQ

## Step 1: Register a non-gallery application

1. Sign in to the [Microsoft Entra admin center](https://entra.microsoft.com/).
2. Go to **Applications → Enterprise applications** and click **New application**.
3. Choose **Create your own application**, name it "DeployHQ", and select **Integrate any other application you don't find in the gallery (Non-gallery)**.

## Step 2: Configure SAML single sign-on

1. Inside the new application, open **Single sign-on** and choose **SAML**.
2. In the **Basic SAML Configuration** panel click **Edit** and set:
   - **Identifier (Entity ID)**: `deployhq`
   - **Reply URL (Assertion Consumer Service URL)**: `https://identity.deployhq.com/authentication/saml/acs`
   - Leave **Sign on URL** blank (DeployHQ starts the flow itself).
3. Under **User Attributes & Claims**, ensure **Name ID** is set to **user.mail** or another email attribute that matches DeployHQ user accounts.
4. (Optional) Add additional claims for name data:
   - `FirstName` → `user.givenname`
   - `LastName` → `user.surname`
5. Click **Save** when the SAML configuration is complete.

## Step 3: Download certificate and endpoints

Still within the SAML configuration page, use the **SAML Signing Certificate** section to download the **Certificate (Base64)**. In the **Set up DeployHQ** panel copy:

- **Login URL** (also called SAML Single Sign-On Service URL)
- **Microsoft Entra Identifier** (the issuer URL)

You will paste these values into DeployHQ later.

## Step 4: Assign users and groups

1. Open the **Users and groups** menu under your DeployHQ enterprise application.
2. Click **Add user/group** and pick every user or Entra ID group that needs DeployHQ access.
3. Click **Assign** to finalize the selection. Unassigned users will not be able to sign in.

## Step 5: Configure DeployHQ

1. In DeployHQ go to **Settings → SAML SSO** and choose **Configure SAML SSO** (or edit the existing configuration).
2. Fill in the fields using the values from the Entra ID portal:
   - **Issuer** → **Microsoft Entra Identifier**
   - **Login URL** → **Login URL** from the Set up DeployHQ section
   - **Certificate** → Paste the Base64 certificate contents including the header/footer lines
3. Leave **Enable SAML SSO** checked and click **Save Configuration**. You can enable **Enforce SSO** after successful testing if you plan to disable password logins.

## Step 6: Test the sign-in flow

1. Open a private browser session.
2. Navigate to the DeployHQ login screen, click **Sign in with SSO**, and enter your DeployHQ subdomain.
3. You should be redirected to the Microsoft sign-in page. After authenticating, DeployHQ should open automatically.

## Troubleshooting tips

- **AADSTS50011: Reply URL mismatch**: Double-check the Reply URL is exactly `https://identity.deployhq.com/authentication/saml/acs`.
- **User not assigned** errors: Verify the user (or their group) is assigned under **Users and groups** for the DeployHQ application.
- **NameID missing**: Ensure the Name ID claim uses an email attribute and that every assigned user has a value populated for the chosen attribute.
- **Certificate expired messages**: Download a new Base64 certificate from Microsoft Entra and update the DeployHQ configuration before the expiry date shown in the portal.

## Official resources

- [Microsoft Learn: Quickstart – Add an enterprise application](https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/add-application-portal) — covers creating a non-gallery application, assigning it to users/groups, and launching the SAML configuration blade inside the Entra admin center.