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.

Please note that for Enterprise Applications you will need to raise a request, via the demand process here New Demand Request

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

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 in the root of the environment directory that you are deploying to, in the format department-teamname.

  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: Please see the below screenshot. As per the instrustions at the top of the state.config file.
    • Please only keep the block of code needed for the environment that you are deploying to. image showing how to configure the state.config file

  5. Update the key to match the new folder name. -Specifically the DEPARTMENT_NAME-TEAM_NAME placeholder.

    staff-identity-idam-entra-infra-DEAPRTMENT_NAME-TEAM_NAME-environmentName.tfstate

    image showing how to configure the state.config file key

  6. variables.tf:

    • Set default values based on your Jira ticket.
    • Update graph_delegated_permissions—leave as [] if none are needed.

  7. 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 --set-upstream origin your-branch-name

If you recieve the following error: remote: Permission to ministryofjustice/staff-identity-idam-entra-infra.git denied to YOUR_USER_NAME. fatal: unable to access 'https://github.com/ministryofjustice/staff-identity-idam-entra-infra.git/%27: The requested URL returned error: 403 - Customers github team need access to our github repo - write perms You will then need to follow the following steps:

  1. Go to the slack channel here: staff-identity-authentication-services

  2. Click the Add team to staff-identity-idam-entra-infra workflow at the bottom of the screen, as seen below. image showing how to trigger Slack workflow

  3. Fill in the form that will appear on screen and click submit in the right hand corner, as per below. image showing how to trigger Slack workflow

  4. Wait around 1 minute for the workflow to run. You should then see a message in Slack regarding your request, as per below. image showing how to fill in Slack workflow form

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

Please ensure you add a business justification for each application and delegated permission. This should highlight what you are using the permission for, to allow us to understand your use case and approve the permissions. 4. Click Create pull request 5. Once you have created the pull

Step 6: Review, Approve & Merge

  1. Wait for the GitHub Actions workflow to complete. An example of this can be seen below, on a customers [Workflow] Pull Request run. image showing a successful Github Pull Request workflow run

  2. The IDAM team will automatically get notified to review your pull request.

  3. You will need to await for the IDAM team to approve your pull request, which may be delayed if we need to raise a change request for the permissions you have requested.

  4. You should be notified once we have merged your pull request

  5. Please check the deployed config in the Azure portal and ensure it aligns with your expectations. If not, please reach out to the IDAM team on Slack here: staff-identity-authentication-services

Step 7: Monitor Main Branch Actions

After merging:

  1. The IDAM team will confirm that GitHub Actions run successfully.
  2. If errors arise we will reach out to you regarding the error
  3. In these situation we will work collabratively with you in order to resolve the issue.

This will require us to do the follow:

  1. Create a new feature branch locally
  2. Create a new pull request from the feature branch to the main branch
  3. Check that the actions run was successful
  4. Obtain the required approvals before merging the pull request
  5. Monitor the main branch actions run, to ensure the error has been resolved

Should there be futher issues, we would need to go through steps 1 - 5 again, until the error has been resolved.

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.