Configuring Single Sign-On for Terraform Cloud

Oladipupo Olimene
5 min readJun 25, 2023

Terraform Cloud allows organisations to configure SAML single sign-on (SSO), an alternative to traditional user management. SSO gives owners more control to secure accessibility to your organisations Projects, Workspaces, and Managed Resources.
Ref: https://developer.hashicorp.com/terraform/cloud-docs/users-teams-organizations/single-sign-on

Single Sign-On (SSO) enables users to use their own authentication server to sign into Terraform Cloud. By implementing SSO, organisations can centralize user management and authentication processes, making it easier to manage access and permissions across multiple systems and services.

When SSO is enabled for Terraform Cloud, users can log in using their existing credentials from the identity provider (IDP) associated with the organisations authentication server. This eliminates the need for separate usernames and passwords for Terraform Cloud, streamlining the login experience for users.

Supported Identity Providers (IdPs)

For this demo, I’ll be configuring SSO using Microsoft Azure AD

Configuration on Microsoft Azure AD

  1. Sign in to the Azure Portal, select the Azure Active Directory service, Navigate to Enterprise Applications and then select All Applications, To add new application, select New application.

2. In the Browse Azure AD Gallery section, type Terraform Cloud in the search box. Select Terraform Cloud from results panel and then click on Create to add the app. Wait a few seconds while the app is added to your tenant.

3. On the Terraform Cloud application integration page, find the Manage section and select single sign-on, On the Select a single sign-on method page, select SAML. In the SAML Signing Certificate section (you may need to refresh the page) copy the App Federation Metadata Url.

Configuration on Terraform Cloud

4. Visit your organisation settings page and click SSO, Click Setup SSO. Select Azure and click Next

5. Provide your App Federation Metadata URL from previous steps. Save settings, and you should see a completed Terraform Cloud SAML configuration. Copy Entity ID and Reply URL.

Configuration on Microsoft Azure AD

6. Back to the Azure portal, on the Terraform Cloud application integration page, find the Manage section and select single sign-on. On the Select a single sign-on method page, select SAML. On the Set up single sign-on with SAML page, click the edit/pen icon for Basic SAML Configuration to edit the settings.

7. In the Identifier text box, paste the Entity ID. In the Reply URL text box, paste the Reply URL. For Service Provider initiated SSO, type https://app.terraform.io/session in the Sign-On URL text box. Otherwise, leave the box blank then Select Save.

8. On the Single sign-on page, download the Certificate (Base64) file from under SAML Signing Certificate.

9. In the app’s overview page, find the Manage section and select Users and groups. Select Add user, then select Users and groups in the Add Assignment dialog.

10. In the Users and groups dialog, select your user from the Users list, then click the Select button at the bottom of the screen. If you are expecting a role to be assigned to the users, you can select it from the Select a role dropdown. If no role has been set up for this app, you see “Default Access” role selected. In the Add Assignment dialog, click the Assign button.

Configuration on Terraform Cloud

11. Edit your Azure SSO configuration settings, Go to Public Certificate, paste the contents of the SAML Certificate you downloaded from Microsoft Azure AD and Save Settings.

12. Verify your settings by testing a completed SSO configuration, click Test on the SSO settings page.

Before Testing
After Testing

13. Then you can complete the configuration by clicking on Enable

14. Your Azure SSO configuration is complete and ready to use.

Signing in with SSO

15. Visit https://app.terraform.io and sign out if you’re signed in. Click Sign in via SSO. Provide your organisation name and click Next

16. If you’ve signed in to Terraform Cloud with SSO before, proceed to the next step.

17. If you’re signing in for the first time under this account or for the first time accessing this organisation, you’ll be required to create a new account (1) or link to an existing account (2). Use the links below the account creation form if you want to link your SSO identity to an existing account, then fill out and submit the relevant form.

18. You will be redirected to your SSO identity provider. Authenticate your account as necessary. You are now signed in to Terraform Cloud.

By leveraging SSO, organisations can enforce their security policies and access controls consistently across different applications and platforms, including Terraform Cloud. This ensures that users’ access privileges and permissions are managed in a centralized manner, reducing the administrative overhead associated with managing multiple user accounts.

If you found this guide helpful, please consider following me on Twitter and connecting on LinkedIn. Don’t forget to give this article a 👏 if you enjoyed reading it as a show of support. Thanks! ✌️

--

--

Oladipupo Olimene

Cloud || Dev Ops || IAC || Security || Automation || Monitoring