--- title: "Using Acquia Single Sign-On" date: "2026-02-19T10:53:16+00:00" summary: "Learn to configure Acquia SSO, manage identity providers, add domains, and troubleshoot errors with this step-by-step guide." image: type: "page" url: "/resources/using-acquia-single-sign-on" id: "2022d14b-f305-482e-921f-afb18b01dba0" --- This document provides instructions for the complete workflow to manage Acquia Single Sign-On (SSO). Use these steps to configure your identity provider (IdP) and manage the domains that require single sign-on (SSO). Note To enable Acquia SSO, contact your Account Manager. Accessing SSO ------------- To access SSO: 1. Log in to [Acquia Launchpad](https://launchpad.acquia.com/.). 2. Navigate to **Account Settings**. 3. Select **Acquia SSO**. ![Acquia dashboard with product options: Cloud Platform, Source, Web Governance, DAM, Content Optimization, and Conversion Optimization. Includes launch and explore buttons.](https://acquia.widen.net/content/ckjoozxcnp/web/acquia_sso-access.png?w=720&v=27b8534c-d21f-4491-a367-352f36cd9b5a&itok=UycxegSJ) 4. Select an account from the list to proceed to the ****Domains**** and ****Identity providers**** configuration tabs. ![Dashboard displaying Acquia products, including Acquia Cloud Platform and various optimization tools, with options to launch or explore each product.](https://acquia.widen.net/content/124susfhyf/web/cloud-platform_acquia-sso.png?w=720&v=29e3acb9-d896-4961-a843-c3370eb604ec&itok=uaY5qrVl) Adding a domain --------------- To add a domain: 1. Select the ****Domains**** tab. 2. Select ****Add Domain****. 3. In ****Domain Name****, enter the corporate email domain. 4. Click ****Add****. The domain appears in the list with an ****Unverified**** status. 5. Click the ****Verify**** link next to the domain name. 6. Copy the ****TXT record**** (the string starting with `acquia-domain-verification=`) and add it to your DNS settings. 7. Click the ****Refresh**** icon in the list to update the status to ****Verified****. Removing a domain ----------------- To remove a domain: 1. Locate the verified or unverified domain in the ****Domains**** list. 2. Select the ****Delete**** icon. 3. Review the confirmation dialog box. 4. Select ****Remove****.  Note You cannot delete an email domain after it links to an identity provider. You must unlink the identity provider before you delete the domain. Managing domain errors ---------------------- Review the following information to resolve domain errors: * ****Domain already exists****: You cannot add a domain already associated with another IdP. * ****Verification Failed****: Ensure that the TXT record is correctly added to the DNS because DNS propagation can take up to 48 hours. * ****Invalid Format****: Ensure that the domain name does not include `https://` or sub-pages. Note You can configure a maximum of 3 IdPs and 10 domains by default. To add more domains and IdPs, contact your Account Manager. Adding an Identity Provider --------------------------- To add an IdP: 1. Select the ****Identity Providers**** tab. 2. Select ****Add Identity Provider****. 3. Complete the following fields: * ****Label****: A label for your reference, such as Main Okta. * **Domains**: The verified domains that the IdP supports. * ****Entity ID****: The unique ID that the IdP provides. * ****SSO URL****: The sign-on URL that the IdP provides. * ****Public Certificate****: Paste the X.509 certificate in PEM format. 4. Select ****Submit****. 5. Copy the **Entity ID** and **ACS** link from the application to your identity provider settings. Enabling or disabling an Identity Provider ------------------------------------------ 1. Click the kebab menu in the top right corner of the IdP details page. 2. Click **Enable** or **Disable**. The system displays the Enable or Disable dialog box. 3. Click **Enable** or **Disable** in the confirmation dialog box. The system displays the success notification, and the status changes to **Enabled** or **Disabled**. Configure SAML attribute mappings --------------------------------- After you add and enable the IdP, you must map SAML attributes to identify users correctly in Acquia. The IdP must send the following three attributes with the exact names specified, if the attribute names do not match, Acquia cannot create or update user profiles correctly: **Attribute name** **Description** `firstName` The first name of the user. `lastName` The last name of the user. `email` The primary email address of the user. The exact steps to map these attributes depend on the IdP. For more information, refer to [Configure Microsoft Entra ID as an Identity Provider](/resources/configure-microsoft-entra-id-identity-provider "Configure Microsoft Entra ID as an Identity Provider") and [Configure Google Workspace as an Identity Provider](/resources/configure-google-workspace-identity-provider "Configure Google Workspace as an Identity Provider"). Editing or deleting an Identity Provider ---------------------------------------- To edit or delete an IdP: 1. To edit: Select the ****Edit**** icon next to the provider, update the certificate or URLs, and select ****Save****. 2. To delete: Select the ****Delete**** icon. You cannot delete an IdP if verified domains remain attached to it. You must remove the domains first. Managing Identity Provider errors --------------------------------- Review the following information to resolve IdP errors: * ****Field is required****: You must complete all fields including ****Name****, ****Entity ID****, ****SSO URL****, and ****Certificate**** before you submit. * ****Invalid Certificate****: The certificate must be a valid PEM file. Ensure that no extra spaces exist and the `---BEGIN CERTIFICATE---` headers are present. * ****SSO Connection Failed****: Ensure that the ACS URL that Acquia provides is correctly entered in the IdP configuration. Frequently asked questions -------------------------- ### What is domain verification? Domain verification serves as the security foundation of the Acquia SSO workflow. This process is an initial check to ensure that your organization possesses legitimate ownership of the domain before authentication occurs. ### How does the Acquia SSO authentication workflow use the domain? Acquia SSO uses the domain portion of a user email address, such as `employee@yourcompany.com`, as the core routing mechanism. After a user enters an email address to log in, Acquia SSO reads the domain to determine the corporate identity provider that must handle the authentication request. ### What are the risks of leaving a domain unverified? Without a secure domain claim step, technical proof of ownership does not exist. An external organization or a malicious actor can list `yourcompany.com` as a custom domain in an unauthorized Acquia account. This action misroutes corporate login requests to an identity provider under external control. As a result, malicious actors can block legitimate employees from company resources and create severe security vulnerabilities. ### How do DNS TXT records provide security during this process? To prevent domain hijacking, Acquia requires the IT administration team to add a unique Domain Name System (DNS) TXT record to the public routing configuration of the domain. This action serves as proof of ownership because only authorized infrastructure owners possess the access required to modify corporate DNS settings. This verification ensures that only authorized administrators can configure, modify, or map yourcompany.com to a specific identity provider, which keeps corporate identities and Acquia environments secure.