Azure CIP

It provides preconfigured Azure subscriptions including security guardrails.

It provides access to most Azure resources including App Services, Container Instances, Virtual Networks, managed databases, Front Door, Key Vault, storage accounts, etc.

Portal: https://portal.azure.com/

Platform documentation

CIP platform docs

Onboarding users

Use this IT Help Centre form to create the onboarding request:

From Request type dropdown, select: Azure Portal and DevOps User Account Request
From Add/Change/Remove dropdown, select: Add
Enter new users’ email addresses

Ask in #cloud-platform on Slack if more help is required.

The new user will receive an invitation by email. Then the service administrators can add them to the service Azure Active Directory groups of the subscriptions: Managers and Delivery team.

To access Azure DevOps, the new user must access the Azure DevOps CIP instance. This will register them in the system then the service administrator can add them to the project.

Privileged Identity Management (PIM) Requests

Privileged Identity Management (PIM) is a service in Azure Active Directory (Azure AD) that enables you to manage, control, and monitor access to important resources at DfE such as access to staging and production environments. We use it for Azure resources and Groups.

To request access to your eligible assignments, follow the steps below:

Navigate to the Azure Portal and login using the email you registered with your CIP account
Click on Directories + subscriptions, this is the icon to the left of the notification bell icon in the blue navigation bar
Ensure you are in the DfE Platform Identity directory, if you are not, switch to it. You may be prompted to verify your identity with 2FA
Search for PIM in the search bar at the top of the page and select Azure AD privileged Identity Management
Click on My roles on the left hand side of the page, under Tasks
Click on either Azure resources or Groups under Activate
You may have to lengthen the resource section in order to see the full resource name, including the environment
Click Activate under Action for the relevant resource
Select a duration (maximum 8 hours), enter a reason for the request and click Activate
The test subscription, which usually includes the staging and preprod environments is self approving and you should see your request approved shortly
An email will be sent to the administrators for the production subscription, they will then be able to approve or deny the request. There can sometimes be a delay with this email, however an administrator can navigate to PIM using the search box (as documented above), then click Approve requests and Azure resources. The administrator should then see the request

Onboarding a service

Use this IT Help Centre form to create the onboarding request and choose Request type: On-Boarding request. It should be filled in by a senior civil servant (G7 or above). This includes an onboarding form to attach. Finance must be agreed beforehand.

You will be given:

2 default subscriptions: dev and test
3 Active directory groups: Reader (read only), Delivery team (developers) and Managers (can approve PIM requests). The original requestor will be owner of these groups.
PIM (Privileged Identity Management) set up: members of the Delivery team can elevate their access themselves in staging, and request approval from a Manager in production.
A new project in Azure DevOps dfe-ssp organisation and corresponding service connections to the subscriptions

The production subscription can be requested via the same IT Help Centre form. Choose Request type: Request production subscription.

Provisioned Azure DevOps

This is the default platform for automation and continuous integration in DfE: see.

When a service is onboarded to CIP, an Azure DevOps project is automatically provided, including service connection to the CIP subscription.

Azure Development

Deployments should always be done via infrastructure as code. We recommend using Terraform or ARM templates.

Azure service principal

To be able to access Azure from an external system like Github actions, a service account is required. It is called a service principal in Azure, or App regisration. See the Azure documentation.

Create service principal

In this example we create a service principal which has a custom role created in Managing secrets. Submit a CIP Request on Service Now. Example:

Please create a new service principal named [subscription-prefix]-[service-abbreviation]-contributor. It will be used to deploy Azure resources from GitHub repositories in the DFE-Digital Github organisation.

Assign the following:
- Custom role "s189-Contributor and Key Vault editor" on subscription [subscription]
- "Directory.Read.All" Microsoft Graph API Application permission, this will need to be approved by a Domain Admin. Required for automation to validate secrets.

Add the following users as Owners on the Service Principals: [Azure users]

Add permissions

Add the service principal to groups or access policies to give it access to particular resources.

To assign more roles, request CIP to add them. You may need approval from Security, ie the allocated ISO.

Use the service principal in external systems

The following values are required for the external system to authenticate against the service principal:

clientId: From App registration overview that we are creating the secret for, use the Application (client) ID
clientSecret: Access key generated above, retrieve it from the key vault secret (e.g. SPReadonlyCredentials) or update it if renewing the secret
subscriptionId: Get the subscription id at the subscription level
tenantId: From App registration overview, use Directory (tenant) ID

To simplify, you can use the new_aad_app_secret script to generate a formatted json with the required information as per the example below.

{
    "clientId": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
    "clientSecret": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
    "subscriptionId": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
    "tenantId": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
}

Before running the script:

Ensure you are logged in to the tenant containing the app registration and have selected the subscription which contains the resources that the app registration needs access to
Ensure you a member of the app registration’s ‘Owners’
Obtain the Application (client) ID of the app registration you want to add to the GitHub secret

Run the script with ./new_aad_app_secret.sh <CLIENT_ID> "<DISPLAY_NAME>"

CLIENT_ID is the Application (client) ID from the app registration overview screen
DISPLAY_NAME is the credential display name (docs) in the app registration’s Certificates & secrets blade. Since a service principal may have multiple secrets, it should uniquely identify where it is used, such as: <SERVICE_NAME>-<ENVIRONMENT> (e.g. register-production)

It should then output the required information as formatted JSON. This can be pasted in as the value for the GitHub secret for example.

GitHub Actions

The credentials may be used in Github actions for the workflow to connect to Azure. As a standard, create a AZURE_CREDENTIALS secret containing the json string.

When using multiple Github deployment environments, each one may require its own set of credentials from different service principals. Configure AZURE_CREDENTIALS as environment secret for each Github environment and make sure the job is configured with the corresponding environment.

Use in Azure login action:

  - uses: Azure/login@v1
    with:
      creds: ${{ secrets.AZURE_CREDENTIALS }}

Configure ARM variables for terraform backend:

  - name: Set ARM environment variables
    uses: DFE-Digital/github-actions/set-arm-environment-variables@master
    with:
      azure-credentials: ${{ secrets.AZURE_CREDENTIALS }}

  terraform {
    ...
    backend "azurerm" {}
  }

Configure ARM variables for the terraform ARM provider to create resources in Azure

  - name: Set ARM environment variables
    uses: DFE-Digital/github-actions/set-arm-environment-variables@master
    with:
      azure-credentials: ${{ secrets.AZURE_CREDENTIALS }}

  provider "azurerm" {
    features {}
  }

Terraform

In Github actions, use the ARM variables as described above.

The json may also be passed as a terraform variable. Then the jsondecode function can be used to extract the values and configure the provider explicitly.

Access key expiration

The Operations team will alert you to the prospect of these secrets expiring, but will not update the credentials. If GitHub actions are used for example and the GitHub secret is not updated, then there is a risk of the CI/CD pipelines failing.

See above to recreate the access keys and make sure to update them in key vault and in the systems using them.

For more control there is a github_action developed to enable periodic checks.

For the GitHub action to work, the API Permission Microsoft Graph Directory.Read.All needs to be granted in App Registrations. Request the CIP team to add the permissions.