» AAD Configuration

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

  1. In the Azure portal, navigate to "Azure Active Directory" > "Enterprise Applications" and select "Add an Application". Screenshot: AAD's "Add Application" page
  2. Select "Non-gallery application". Provide a name for the application and click "Add". Screenshot: AAD's dialog for beginning a new application
  3. AAD will automatically redirect to your new application settings. Navigate to "Single sign-on" and select "SAML". Screenshot: the first page of AAD's new app configuration workflow, called "General Settings"
  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>/ Screenshot: The "Configure SAML" page of ADD's new app workflow, with the specified settings entered.
  5. In the "User Attributes & Claims" section, select the pencil and configure the following items:
    • Name Identifier value: user.mail Screenshot: Modifying the name identifier value.
  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. Screenshot: Add MemberOf claim
  7. Under the "SAML Signing Certificate" header, download the signing certificate in base64 format. Screenshot: Download the SAML signing certificate
  8. Under the "Set up " header, copy the following urls that we will enter in our TFE configuration to link TFE to AAD:
    • Login URL:
    • Logout URL: Screenshot: Azure Login/Logout URLs
  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. Screenshot: Terraform Enterprise SAML Settings

» 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 Registration" page, and search for the application you created for TFE. Select your app and select "Manifest". Screenshot: AAD App Registration
  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. Screenshot: Manifest Editor
  4. The "appRoles" block may contain roles automatically generated by AAD. 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 these GUIDs. Click "Save" to add the roles.

    Example role configuration that creates a new role name Dev: json { "allowedMemberTypes": [ "User" ], "displayName": "Dev", "id": "d1c2ade8-98f8-45fd-aa4a-6d06b947c66f", "isEnabled": true, "description": "Dev Team", "value": "Dev" } Screenshot: New role in Manifest Editor

  5. Use the breadcrumb navigation to return to your application's settings. 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. Screenshot: Role Assignment

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