Configure an Azure Active Directory Identity Provider

Follow these steps to configure Azure Active Directory (AAD) as the identity provider (IdP) for Terraform Enterprise.

Configure a New AAD Non-Gallery Application

1. In the Azure Active Directory portal, navigate to Enterprise Applications and select New application.

2. Select Non-gallery application. Provide a name for the application and click Add. AAD automatically redirects to your new application's settings.

3. Navigate to Single sign-on and select SAML.

4. Click the pencil icon in Basic SAML Configuration and configure these settings:

   • Identifier (Entity ID): https://<TFE HOSTNAME>/users/saml/metadata, which is Metadata (audience) URL in TFE's SAML settings.
   • Reply URL (Assertion Consumer Service URL): https://<TFE HOSTNAME>/users/saml/auth, which is ACS consumer (recipient) URL in Terraform Enterprise's SAML settings.
   • Sign on URL: https://<TFE HOSTNAME>/

5. In the User Attributes & Claims section, click the pencil icon and configure these items:

   • Name Identifier value: user.mail

6. In the Manage user claim section, configure a user claim to map the team a user belongs to:

   • Name: MemberOf. This name is the default for TFE's group attribute. You can change this attribute's name in TFE's SAML settings if necessary.
   • Source attribute: (drop-down): user.assignedroles. This action creates custom roles in your Azure Active Directory that you use to map users and groups to Terraform Enterprise teams.

7. In the SAML Signing Certificate section, download the signing certificate in base64 format.

8. In the Set up <ABD App Name> section, copy these URLs to enter in your Terraform Enterprise configuration to link Terraform Enterprise to AAD:

9. In the Set up <ABD App Name> section, copy these URLs. You need them to link Terraform Enterprise to Azure Active Directory.

   • Login URL:
   • Logout URL:

10. Navigate to https://<TFE_HOSTNAME>/app/admin/saml and configure these settings:

    • Enable SAML single sign-on (check box): enabled.
    • Single Sign-On URL: Enter the login url.
    • Single Log-out URL: Enter the logout url.
    • IDP Certificate: Enter the contents of the PEM (base64) encoded X.509 certificate.

Configure Custom Roles for Team Membership Mapping

1. Create teams in Terraform Enterprise. Refer to Terraform Enterprise Team Membership for more information.

2. Return to the Azure Portal, and navigate to the App registrations page.

3. Go to the Enterprise applications* page, select your Terraform Enterprise application, and then select Manifest** in the sidebar.

4. In the manifest editor, locate the appRoles block. This block is where you add additional roles that map users and groups to teams in Terraform.

5. Leave any automatically generated role GUIDs with their default values. Add new roles after the system roles. The new roles must contain a unique GUID value for the ID value of the new role. You can use a tool such as GUID Generator to create the GUIDs for these new roles.

6. Click Save to add the roles.

   Note: You can add as many roles as your organization needs, such as the site-admins role. Azure AD sends the value of these roles as the claim value in the SAML response.

   Example role configuration that creates a new role named Dev:

   {
   "allowedMemberTypes": [
       "User"
   ],
   "displayName": "Dev",
   "id": "d1c2ade8-98f8-45fd-aa4a-6d06b947c66f",
   "isEnabled": true,
   "description": "Dev Team",
   "value": "Dev"
   }
   

7. Navigate to Enterprise applications and select the app you created for TFE. In the sidebar, under the Manage heading, select Users and Groups. You can enable access to Terraform Enterprise by adding either users or groups to your application. During the process of adding users or groups, you select a role to assign to the user or group. Select the role that matches the user or groups Terraform Enterprise team.

8. Navigate to Enterprise applications and select the app you created for Terraform Enterprise.

9. Select Users and Groups in the sidebar, under the Manage heading. You can enable access to Terraform Enterprise by adding either users or groups to your application. During the process of adding users or groups, you select a role to assign to the user or group.

10. Select the role that matches the user or groups Terraform Enterprise team.

Once you add users, the initial configuration is complete, and they can begin logging into Terraform Enterprise with their AAD username and password.