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).

Accessing SSO

To access SSO:

1. Log in to Acquia Launchpad.
2. Navigate to Account Settings.

3. Select Acquia SSO.

   

4. Select an account from the list to proceed to the and configuration tabs.

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).

Accessing SSO

To access SSO:

1. Log in to Acquia Launchpad.
2. Navigate to Account Settings.

3. Select Acquia SSO.

   

4. Select an account from the list to proceed to the Domains and Identity providers configuration tabs.

    

   

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. 

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.

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:

The exact steps to map these attributes depend on the IdP. For more information, refer to Configure Microsoft Entra ID as an Identity Provider and 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 [email protected], 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.