Azure AD / Entra ID Users Terraform Module

Terraform module that manages cloud-based Azure AD / Entra ID user accounts

Inspired by the HashiCorp tutorial "Manage Microsoft Entra ID users and groups"

Description

This Terraform module allows you to manage Azure AD / Entra ID user accounts using a CSV file. The module reads user data from the CSV file and creates or updates user accounts in Entra ID based on the provided attributes. It supports setting various user attributes, including account status, password policies, and contact information.

User Data (users.csv)

The module requires a CSV file named users.csv to define the users to be created and their associated attributes. You can find a template users.csv file in the root directory of this repository containing the required headers and an example user. Additional user attributes can be set as seen in the Inputs section below. Reference the Resources section for links to the provider docs with further details.

To use the template:

1. Copy the users.csv file to the same directory as your main Terraform configuration file.
2. Modify the file to include your own user data.
3. Ensure that the file is saved in UTF-8 encoding.

User Generation

The user_principal_name is generated using the mail_nickname CSV input user values and the domain_name module value.

The display_name is generated using the first_name and last_name CSV input user values.

All users will be provisioned with a user principal name, or username, that follows the format: mail_nickname@domain_name

For example, user Michael Brown would have the following user principal name generated: mbrown@jennasrunbooks.com

Password Generation

The default behavior uses a password_generate_random flag set to true which generates a random, 32 character long password with a mix of lowercase letters, uppercase letters, numeric digits and special characters. A random_password resource will be created for each user. This approach allows for administrators to perform a password reset for the user once they're ready to login by providing them with a new, temporary password upon request. The auto-generated password is sensitive and therefore not output to console and only saved to terraform state. Ensure your state file is protected by storing it remotely with encryption!

The alternative method is to disable the password_generate_random flag and allow the module to auto-generate passwords for new users based on user attributes appended with a slug value. The following pattern shows an example using the default slug value: <lowercase_lastname><lowercase_first_letter_of_firstname><length_of_firstname>$^k&*3Ji_#@1U

For example, user Michael Brown would have the following password generated: brownm7$^k&*3Ji_#@1U

Upon initial authentication with the predictable auto-generated password and mail_nickname@domain_name user principal name, the user will be forced to change their password if the global_force_password_change boolean is set to true as seen in the example usage below.

Use extreme caution when disabling the password_generate_random flag which enables the predictable password generator approach! This should be used in homelab environments for testing purposes only.

Example Usage

# Using the default random password generator:

locals {
  users = csvdecode(file("${path.module}/users.csv"))
}

module "user_setup_production" {
  source                       = "../"
  domain_name                  = "jennasrunbooks.prod.com"
  users                        = local.users
}

# Using the predictable password generator appended with random slug

locals {
  users = csvdecode(file("${path.module}/users.csv"))
}

module "user_setup_homelab" {
  source                       = "../"
  domain_name                  = "jennasrunbooks.lab.com"
  users                        = local.users
  password_generate_random     = false
  slug                         = "A^et$&%$#.h"
  global_force_password_change = true
}

Requirements

Name	Version
terraform	>= 0.13
azuread	~> 3.1.0
random	~> 3.7.0

Providers

Name	Version
azuread	~> 3.1.0
random	~> 3.7.0

Modules

No modules.

Resources

Name	Type
azuread_user.this	resource
random_password.this	resource
azuread_domains.aad_domains	data source

Inputs

Name	Description	Type	Default	Required
domain_name	The domain name to use for managing the Azure AD / Entra ID users	string	n/a	yes
global_account_enabled	(Optional) Whether or not the account should be enabled. Defaults to true. Applies globally to all users.	bool	true	no
global_disable_strong_password	(Optional) Whether the user is forced to change the password during the next sign-in. Only takes effect when also changing the password. Defaults to false. Applies globally to all users.	bool	false	no
global_force_password_change	(Optional) Whether the user must change their password on next login. Defaults to false. Applies globally to all users.	bool	false	no
global_show_in_address_list	(Optional) Whether or not the Outlook global address list should include this user. Defaults to true. Applies globally to all users.	bool	true	no
password_generate_random	Generates a random 32 character long, unused password stored to terraform state.	bool	true	no
slug	(Optional) Random slug to be used with the predictable password generator based on user attributes.	string	"$^k&*3Ji_#@1U"	no
users	Values assigned to Entra ID users managed in the local csv file	list(object({ first_name = string last_name = string mail_nickname = string account_enabled = optional(bool) age_group = optional(string) business_phones = optional(list(string)) company_name = optional(string) consent_provided_for_minor = optional(string) cost_center = optional(string) country = optional(string) department = optional(string) disable_strong_password = optional(bool) division = optional(string) employee_hire_date = optional(string) employee_id = optional(string) employee_type = optional(string) fax_number = optional(string) force_password_change = optional(bool) given_name = optional(string) job_title = optional(string) mail = optional(string) manager_id = optional(string) mobile_phone = optional(string) office_location = optional(string) onpremises_immutable_id = optional(string) other_mails = optional(list(string)) postal_code = optional(string) preferred_language = optional(string) show_in_address_list = optional(bool) state = optional(string) street_address = optional(string) surname = optional(string) usage_location = optional(string) }))	n/a	yes

Outputs

Name	Description
domain_name	n/a
object_id	n/a
users	n/a

License

This project is licensed under the Mozilla Public License 2.0 - see the LICENSE file for details.