Skip to main content

IDAM Terraform App Registration Setup Guide

This guide walks engineers and developers through using Terraform in the staff-identity-idam-entra-infra repository to create app registrations in Azure Entra ID.

Prerequisites

If you have already cloned the repo, skip ahead to step 4 and commit and push your changes.

If you have not yet cloned the repo, follow the steps below.

Step 1: Clone the Repository

Open Visual Studio Code and start a new terminal session. Then enter:

mkdir $env:userprofile\git
cd $env:userprofile\git\
git clone git@github.com:ministryofjustice/staff-identity-idam-entra-infra.git
cd staff-identity-idam-entra-infra
code .                   # Opens VS Code in this location
git checkout -b "branch-name"    # Create a new branch

Step 2: Update Repo and Create Feature Branch

If youve already cloned the repo locally, open the repo in VS Code (or IDE of your choice) and run the following in the terminal:

git pull
git checkout -b "IDAM-xxxx-name-of-your-feature-branch"
Replace IDAM-xxxx with the Jira ticket number linked to your change.

Step 3: Create the Terraform Folder Structure

Navigate to: STAFF-IDENTITY-IDAM-ENTRA-INFRA/TERRAFORM/ENVS/REQUIRED_ENV

Then complete the following:

  1. Create a new folder using your department/team name. image showing how to create the folder

  2. Copy contents from the terraform-template folder. image showing how to copy the templated files

  3. Paste the contents from the terraform-template folder into your new folder. image showing how to paste the templated files

  4. Update these files:

    • state.config: Update the key to match the new folder name. Specifically the DEPARTMENT_NAME-TEAM_NAME placeholder. hcl staff-identity-idam-entra-infra-DEAPRTMENT_NAME-TEAM_NAME-environmentName.tfstate
    • variables.tf:
      • Set default values based on your Jira ticket.
      • Update graph_delegated_permissions—leave as [] if none are needed.
    • main.tf:
      • Set appropriate tags.
      • Update the module source to the latest version. This can be found in the Modules folder, in the root of the directory.

Step 4: Commit and Push Your Changes

Once updates are complete, run:

git add .
git commit -m "xxxx"      # Replace xxxx with a descriptive commit message
git push

Step 5: Create a Pull Request

  1. Visit the repo: staff-identity-idam-entra-infra
  2. You should see Compare & pull request — click it.
  3. Complete the PR form:
    • Purpose of the change
    • Jira ticket reference
  4. Click Create pull request

Step 6: Review, Approve & Merge

  1. Wait for the GitHub Actions workflow to complete.
  2. Request ministryofjustice/eucs-idam-maintainers to review your PR, as per the below screenshot. image showing how to request a pull review
  3. Merge the pull request into main.

Step 7: Monitor Main Branch Actions

After merging:

  1. Confirm that GitHub Actions run successfully.
  2. If errors arise:
    • Create a new feature branch.
    • Fix the issue.
    • Raise another pull request.
    • Merge into main once fixed.

Step 8: Request Graph Permissions

If Graph permissions are needed (delegated or application):

  • Mention this in your pull request.
  • The IDAM team will handle the admin consent process.