Single Sign-on: Microsoft Entra ID
The Microsoft Entra ID (previously Azure Active Directory) SSO integration currently supports the following SAML features:
- Service Provider (SP) initiated SSO
- Identity Provider (IdP) initiated SSO
- Just-in-Time Provisioning
For more information on the listed features, visit the Microsoft Entra ID SAML Protocol Documentation.
Configuration (Microsoft Entra ID)
- Sign in to the Entra portal.
- On the left navigation pane, select the Microsoft Entra ID service.
- Navigate to Enterprise Applications and then select All Applications.
- To add new application, select New application.
- In the Add from the gallery section, type Terraform Cloud in the search box.
- Select Terraform Cloud from results panel and then add the app. Wait a few seconds while the app is added to your tenant.
- 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 (HCP Terraform)
Visit your organization settings page and click "SSO".
Click "Setup SSO".
Select "Microsoft Entra ID" and click "Next".
Provide your App Federation Metadata URL.
Save, and you should see a completed Terraform Cloud SAML configuration.
Copy Entity ID and Reply URL.
Configuration (Microsoft Entra ID)
- In the Entra 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.
- 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. - Select Save.
- On the Single sign-on page, download the
Certificate (Base64)
file from under SAML Signing Certificate. - 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.
- 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 (HCP Terraform)
To edit your Entra SSO configuration settings:
Go to Public Certificate.
Paste the contents of the SAML Signing Certificate you downloaded from Microsoft Entra ID.
Save Settings.
Verify your settings and click "Enable".
Your Entra SSO configuration is complete and ready to use.
Team and Username Attributes
To configure team management in your Microsoft Entra ID application:
- Navigate to the single sign-on page.
- Edit step 2, User Attributes & Claims.
- Add a new group claim.
- In Group Claims, select Security Groups.
- In the Source Attribute field, select either sAMAccountName to use account names or Group ID to use group UUIDs.
- Check Customize the name of the group claim.
- Set Name (required) to "MemberOf" and leave the namespace field blank.
Note: When you configure Microsoft Entra ID to use Group Claims, it provides Group UUIDs instead of human readable names in its SAML assertions. We recommend configuring SSO Team IDs for your HCP Terraform teams to match these Entra Group UUIDs.
If you plan to use SAML to set usernames in your Microsoft Entra ID application:
- Navigate to the single sign-on page.
- Edit step 2, User Attributes & Claims.
We recommend naming the claim "username", leaving the namespace blank, and sourcinguser.displayname
oruser.mailnickname
as a starting point. If you have a Terraform Enterprise account, you can sourceuser.mail
oruser.userprincipalname
. Note that HCP Terraform usernames only allow lowercase letters, numbers, and dashes.
If you namespaced any of your claims, then Microsoft Entra ID passes the attribute name using the format <claim_namespace/claim_name>
. Consider this format when setting team and username attribute names.
Troubleshooting the SAML assertion
Use this guide to verify and validate the claims being sent in the SAML response.