Resolving Issues with Terraform Enterprise Reaching an Old SSO URL

Introduction

This guide explains how to resolve an issue where Terraform Enterprise (TFE) attempts to use an old Single Sign-On (SSO) URL after an SSO configuration update.

Expected Outcome

After completing this procedure, TFE will use the new SSO URL for authentication, and the system will function correctly with the updated identity provider (IdP) configuration.

Prerequisites

• Administrative access to the TFE instance.
• A non-SSO local admin account for recovery purposes.
• The updated SSO URL and IdP certificate details from your identity provider.

Use Case

This procedure applies when you have recently updated your SSO configuration in TFE but notice it still attempts to use the old SSO URL, leading to authentication failures.

Procedure

Step 1: Disable SAML Single Sign-On

1. Navigate to the SAML settings page at https://<TFE_HOSTNAME>/app/admin/saml.
2. Uncheck the Enable SAML Single Sign-On checkbox.
3. Confirm the action, which will log you out from TFE.
4. Log back into TFE using a non-SSO local admin account.

Step 2: Verify Non-SSO Admin Account

If a non-SSO admin account does not exist, you must create one to ensure you can recover access if SSO fails.

1. Create a new account by navigating to https://<TFE_HOSTNAME>/signup/account.
2. Use an email address that is not associated with your identity provider (e.g., SAML).
3. After creating the account, grant it administrative access.
4. Test logging in with this new account to ensure recovery access is available.

Step 3: Reconfigure SSO Settings

1. Navigate back to the SAML settings page at https://<TFE_HOSTNAME>/app/admin/saml.
2. Update the following settings:
   • Single Sign-On URL: Enter the new URL provided by your IdP.
   • IdP Certificate: Upload the new PEM-encoded X.509 Certificate from your IdP. If a rotation period is active, an option to Revoke old IDP certificate may appear.
3. Click Save settings.

Step 4: Test SSO Configuration

1. Log out of your TFE session.
2. Attempt to log in again using the SSO option.
3. Verify that the login process correctly redirects to the new SSO URL.
4. After a successful login, confirm that other users can access TFE using the updated SSO configuration.

Additional Information

• For more details on SAML configuration, refer to the SAML Configuration for Terraform Enterprise documentation.