AAD Configuration

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 portal, navigate to "Azure Active Directory" > "Enterprise Applications" and select "Add an Application".
2. Select "Non-gallery application". Provide a name for the application and click "Add".
3. AAD will automatically redirect to your new application settings. Navigate to "Single sign-on" and select "SAML".
4. Select the pencil within "Basic SAML Configuration" and configure these settings:
   • Identifier (Entity ID): https://<TFE HOSTNAME>/users/saml/metadata (listed as "Metadata (audience) URL" in TFE's SAML settings).
   • Reply URL (Assertion Consumer Service URL): https://<TFE HOSTNAME>/users/saml/auth (listed as "ACS consumer (recipient) URL" in TFE's SAML settings).
   • Sign on URL: https://<TFE HOSTNAME>/
5. In the "User Attributes & Claims" section, select the pencil and configure the following items:
   • Name Identifier value: user.mail
6. Still in the "User Attributes & Claims" page, under "Manage user claims", configure a user claim to map the team a user belongs to:
   • Name: MemberOf. This is the default name for TFE's group attribute; the name of this attribute can be changed in TFE's SAML settings if necessary.
   • Source attribute: (drop-down): user.assignedroles. Custom roles will be created in Azure Active Directory that will be used to map users and groups to TFE teams.
7. Under the "SAML Signing Certificate" header, download the signing certificate in base64 format.
8. Under the "Set up <ABD App Name>" header, copy the following urls that we will enter in our TFE configuration to link TFE to AAD:
   • Login URL:
   • Logout URL:
9. Navigate to https://<TFE_HOSTNAME>/app/admin/saml and configure the following:
   • Enable SAML single sign-on (check box): enabled.
   • Single Sign-On URL: Enter the login url from step 8.
   • Single Log-out URL: Enter the logout url from step 8.
   • IDP Certificate: Enter the contents of the PEM (Base64) encoded X.509 certificate captured in step 7.

Configure Custom Roles for Team Membership Mapping

1. Create teams in TFE as outlined in TFE Team Membership.

2. Return to the Azure Portal, navigate to the "App registrations" page, and search for the application you created for TFE in the "Enterprise applications" page. Select your app and in the left sidebar select "Manifest".

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

4. The "appRoles" block may contain roles automatically generated by AAD. Leave the automatically generated role GUIDs with their default values. New roles should be added after the system roles and 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. 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 will send 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"
   }
   

   

5. Go back to "Enterprise applications", and select the app you created for TFE. In the left sidebar, under the "Manage" heading, select "Users and Groups". This is where you will enable access to TFE by adding either users or groups to your application. During the process of adding users or groups you will select a role to be assigned to the user or group. Select the role that matches the user or groups TFE team.

Once users have been added, the initial configuration is complete, and they can begin logging into TFE with their AAD username and password.