terraform-azuread-ms365-hass

Infrastructure-as-Code to assist with setup for @RogerSelwyn's MS365 Home Assistant integrations - deploy from Azure Cloud Shell or locally!

Note

Cost Disclaimer

This module creates Azure AD resources that may incur costs depending on your Azure subscription and licensing. While Azure AD Basic features are typically included with most subscriptions, premium features, API call volumes, or specific tenant configurations might result in charges.

The maintainers of this module are not responsible for any Azure costs incurred by using this Terraform configuration. Please review your Azure subscription billing and Azure AD pricing before deployment. Monitor your Azure consumption through the Azure portal.

✨ Features

• ⚡ Minimal Setup - Single selected_service parameter configures appropriate permissions automatically
• 🚀 Multiple Deployment Options - Deploy directly from Azure Cloud Shell with zero local installations or do it locally for free
• 🔄 Automatic Secret Rotation - Built-in credential rotation with configurable windows
• 🔍 Transparent Configuration - All permissions and settings clearly documented with Microsoft Graph IDs
• 🎯 Service-Specific Apps - Creates focused applications per MS365 integration (calendar, mail, todo, teams, contacts) that can be managed from a single command!
• 🔧 Customizable Inputs - Add custom redirect URIs as needed, set additional Owners for the AzureAD app, or override default permissions with custom Microsoft Graph scopes entirely

Quick Start

Basic Usage

Please see the examples folder for a configuration example (that calls this module), take a look at the a fancy rendering of the inputs on the module's Terraform Registry page or peep the variables page directly to see the inputs supported by this module.

Setup

You can choose to set this up in either Azure Cloud Shell (easiest, but may have associated cloud cost) or by downloading the tools and running them from your machine (free).

Option 1: Azure Cloud Shell

Pros: No software installation, always up-to-date tools, integrated authentication
Cons: Minimal storage costs for Cloud Shell usage (~$1-2/month typical)

Start by clicking this button or link to Azure Cloud Shell and choose Bash as the shell if prompted.

Continue with Shared Setup Steps below

Option 2: Locally Installed (free)

Download the following tools and make them accessible to your shell:

• terraform (>= 1.9)
• az
• git (helpful, but you could also copy a zip of the files or copy/paste if needed)

Run the following command & follow steps as needed to auth to Azure

Note

If you are using a sovereign cloud, you may need to run az cloud set -n NameOfCloud as referenced in the az cli sovereign cloud docs.

az login

Shared Setup Steps

Start by fetching the code from the examples/multi_service folder

# this is just an easy way to fetch the example code - you can also directly download the repo as a zip if you prefer
git clone https://github.com/codycodes/terraform-azuread-ms365-hass.git

After downloading the code, please continue with the README on how to deploy: examples/multi_service/README.md

FAQ

How Does Auto-Rotation Work?

This module implements an auto-rotation of the client secret (as they have a maximum expiry of two years) while allowing for a defined "grace period" window in which the secret should be considered "rotate-able" (meaning a new one will be generated). From that point forward, the cycle restarts.

The benefit of the grace period is that you get a window in which you can decide when you want to perform secret rotation prior to the actual secret expiring.

Here's some ascii showing what the defaults do:

Day 0    Day 365                Day 730
 │         │                      │
 │    [Rotation Window Opens]  [Secret Expires]
 │         │<---- 365 days ---->│
 │<------- 730 days ------------->│

Important

Terraform needs to be executed in order to determine whether the token needs to be rotated and to optionally perform rotation.

How Can I Remove The Resources Created by Terraform?

To remove, you can simply cd to where your Terraform is stored and run terraform destroy. For more info please refer to the command reference

Troubleshooting

I'm Receiving a 409 Error - What Can I Do?

Error: Error_MsaAppDoesNotExist or similar 409 conflict errors during terraform apply

Root cause: Azure AD application provisioning can take time to propagate across Microsoft's infrastructure. This creates race conditions where Terraform tries to configure permissions / create client secrets before the application is fully provisioned in all Azure AD subsystems.

Solution:

1. Wait 5-10 minutes for Azure AD propagation to complete
2. Re-run terraform apply
3. The resources should create successfully on the retry

Why this happens: This is a known behavior with Azure AD's eventual consistency model and is outside the control of the azuread Terraform provider. While all resources are configured correctly in your Terraform code, Microsoft's backend provisioning timing causes these temporary conflicts.

Note: If the error persists after 15-20 minutes, check the Azure Status page for any ongoing service incidents.

Still Not Working?

Please create an issue and I'll respond when able to assist with troubleshooting. If you can get a working configuration by manually setting up per Roger's instructions, please share that in the issue and it will help improve the IaC for everyone!

Happy Automating! 🤖