Using Acquia Single Sign-On | Resources | Acquia Product Documentation
Resources
Using Acquia Single Sign-On
Using Acquia Single Sign-On
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.
Select an account from the list to proceed to the Domains and Identity providers configuration tabs.
Adding a domain
To add a domain:
Select the Domains tab.
Select Add Domain.
In Domain Name, enter the corporate email domain.
Click Add.
The domain appears in the list with an Unverified status.
Click the Verify link next to the domain name.
Copy the TXT record (the string starting with acquia-domain-verification=) and add it to your DNS settings.
Click the Refresh icon in the list to update the status to Verified.
Removing a domain
To remove a domain:
Locate the verified or unverified domain in the Domains list.
Select the Delete icon.
Review the confirmation dialog box.
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:
Select the Identity Providers tab.
Select Add Identity Provider.
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.
Select Submit.
Copy the Entity ID and ACS link from the application to your identity provider settings.
Enabling or disabling an Identity Provider
Click the kebab menu in the top right corner of the IdP details page.
Click Enable or Disable.
The system displays the Enable or Disable dialog box.
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:
To edit: Select the Edit icon next to the provider, update the certificate or URLs, and select Save.
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.
Using Acquia Single Sign-On
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.
Select an account from the list to proceed to the Domains and Identity providers configuration tabs.
Adding a domain
To add a domain:
Select the Domains tab.
Select Add Domain.
In Domain Name, enter the corporate email domain.
Click Add.
The domain appears in the list with an Unverified status.
Click the Verify link next to the domain name.
Copy the TXT record (the string starting with acquia-domain-verification=) and add it to your DNS settings.
Click the Refresh icon in the list to update the status to Verified.
Removing a domain
To remove a domain:
Locate the verified or unverified domain in the Domains list.
Select the Delete icon.
Review the confirmation dialog box.
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:
Select the Identity Providers tab.
Select Add Identity Provider.
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.
Select Submit.
Copy the Entity ID and ACS link from the application to your identity provider settings.
Enabling or disabling an Identity Provider
Click the kebab menu in the top right corner of the IdP details page.
Click Enable or Disable.
The system displays the Enable or Disable dialog box.
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:
To edit: Select the Edit icon next to the provider, update the certificate or URLs, and select Save.
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.
Did not find what you were looking for?
If this content did not answer your questions, try searching or contacting our support team for further assistance.
Did not find what you were looking for?
If this content did not answer your questions, try searching or contacting our support team for further assistance.
