KB-2343 Transferring SAML after domain change

Purpose

SAML is tied to the Service Provider Hostname, hence when changing to a custom domain there will be required changes to reconfigure aspects of SAML.  

The required steps may vary with the Identify Provider (IDP) or custom configurations, and this KB article is intended to be a guide to assist with the common changes. For further assistance please consult your IDP provider, and reach out to Appian Support through a support case. 

Table of Contents:

• For Appian SAML configurations
• SP Metadata
• IDP
• Saving Changes to SAML Configuration in Appian
• User Start Pages
• Recommended 

For Appian SAML configurations

The hostname is referenced in: 

1. Service Provider (SP) Metadata

The hostname may also be referenced in: 

1. Identity Provider (IDP) Metadata
2. Service Provider PEM file Signing Certificate 
3. User Start Pages 

SP Metadata

To regenerate the SP Metadata with the new customer domain: 

By Preference: 

1. Review the Entity ID, and Service Provider Signing Certificate, and change as preferred. These will typically reference the Appian Hostname.
   1. The Entity ID does not have to reflect the Hostname, as the Entity ID is a text value. It is important that this value aligns between SP and IDP. 
   2. The Signing Certificate may reflect the hostname in the Common Name.

Required:

Even if there are no manual changes to the SP Settings, you will still regenerate the SP Metadata to point to the new domain, this is because the location attributes for the SAML assertion reference the hostname. 

1. Once the SP settings are updated, regenerate the SP Metadata, this will download a XML file with the required connection information. 
2. Review the XML metadata file to ensure the old domain is replaced with the new domain, and upload this SP metadata to you IDP.

Please see the following resource for more information on service provider metadata.

Additionally, please see the following for more assistance regenerating the certificate.  

IDP

If you have made any changes to the SP configurations, these should be matched in the IDP. 

1. If you have changed the Entity ID, signing certificate or otherwise, you will need to update this on the IDP side
2. After uploading the SP Metadata, and changing any IDP configurations,  regenerate the IDP Metadata and download the XML file. If the Metadata is changed, upload the IDP Metadata to the Appian Admin Console. 

External to Appian, please work with your IDP provider to determine where the IDP references the domain of the SP and change the value to reflect the new hostname.

If your IDP does not have a field to upload the service provider metadata file. Please see the following resource to assist with updating the configurations in the IDP. 

Saving Changes to SAML Configuration in Appian

After changing the SAML configuration in Appian:

1. Test the connection, using the “ Test This Configuration” button in the top right hand corner of the SAML Configurations page. 
   1. This is mandatory to save changes if you are signed in with a user in the SAML group, to ensure you do not accidentally log yourself out. 
   2. This is not mandatory if you are not in the SAML group, however it is highly recommended to test with a user in the SAML group, to ensure you do not save invalid configurations. You will be able to save invalid configurations if the user is not in the SAML group. 
2. Choose “Done” and “Save Changes” in the lower right hand corner of the “SAML Authentication” page. 

For further guidance, please see SAML configuration in Appian. 

User Start Pages 

If you have a User Start Page configured, change the user start page configuration to reflect the new domain.

Recommended 

Prior to changing the Domain, we recommend ensuring a system administrator user is outside the SAML group. If any issues occur the user can access the admin console and disable SAML to allow user access. 

For further questions on SAML see our SAML FAQ. 

Affected Versions

This article applies to all versions of Appian Cloud.

Last Reviewed: July 2025