Branding policies pipeline configuration¶

Table of contents¶

Branding policies pipeline configuration
Table of contents
Introduction
Pipelines
How to work with an Azure DevOps repository
Recommended procedure

Introduction¶

Azure DevOps pipelines are used for deploying the B2C user interface (branding) and policy files (User Journeys). This increases the trust level for having a controlled and successful deployment across all environments.

Pipelines¶

There are two different types of pipelines for handling deployment:

branding
polices

For each of these deployment types there are three pipelines to support the various environments:

dev (development)
test
prod (production)

At minimum, there are six pipelines (2x3) registered for deployments dev, test and prod environments (plus for any additional set of policy files).

All these pipelines must use service principals to perform necessary configuration changes.
The service principals have been created by automation elsewhere, with credentials stored in DevOps Pipelines Library variable groups.

The variable group (which provides access to, and safe-keeps, credentials):

Customer b2c content deployment

Content refers to management of the branding and policy files.
Policy file management happens within the Identity Experience Framework blade, branding files are hosted on an Azure storage account (resource tenant).

Pipeline execution¶

The project repository is the place for all Identity Experience Framework files, User Journey code and configuration.

The configuration of pipelines triggers can be split into two categories:

Automatically triggered
Manually triggered

NOTE!

All pipelines are configured to require approval before running.
Members of project group Contributors can all approve runs, including their own.

The automated way¶

Using triggers enables automatic execution when working with Azure DevOps repositories and pipelines.

For pipelines used in development they will automatically trigger when uploaded changes are detected.
The pipelines are triggered but must be approved in order to start churning through steps and tasks.

The manual way¶

For pipelines in test and production they must be triggered manually.

This is a security measure, but also a necessary configuration as test and prod don't have their own files.
The policy and branding files from Environment\Development\policies\v1 are promoted and deployed to test and prod.

All pipelines must be approved to start running through steps and tasks.

Azure DevOps Pipelines Environments¶

There are three environments configured:

dev
test
prod

Each of these are referenced when pipelines are triggered.
Run history is saved to the respective environments, dev, test, prod.

The environments have Approvals and checks configured as follows:

All approvers must approve
Approvers: [IdentityPlatform]\Contributors
Allow approvers to approve their own runs

NOTE!

All approvers must approve does not mean that every member of the group must approve.
This can be confusing, but when using groups for approval, a single approval is sufficient.

Azure DevOps Pipelines Library¶

There are three variable groups defined in the library. These credentials are used for b2c policies and branding (content):

Customer b2c content deployment - Dev
Customer b2c content deployment - Test
Customer b2c content deployment - Prod

These credentials are loaded during pipeline execution and are necessary to perform the configured pipeline tasks.

Azure DevOps Pipelines variable group - content deployment¶

Customer b2c content deployment - <env> is used for deploying custom policies and custom styling (UI) files.

The content variable group holds credentials for the app registration used for content deployment for the specified environment.

IMPORTANT!

Using an app registration client_id and client_secret means that if the secret expires the pipeline will stop working.
It is important that secret management (key rotation) is established to avoid deployment disruption.
The app registration resides in the resource tenant and it is granted permission in the B2C tenant using admin consent.

Variable CONTENT_DEPLOYMENT_APP_REGISTRATION_CLIENTID refers to an app registration in the resource tenant.
Variable CONTENT_DEPLOYMENT_APP_REGISTRATION_CLIENTSECRET must be provided with the client_id for the pipeline to successfully authenticate with the Graph API and issue a token that must be presented when uploading files.

The app registration must be granted the following Graph API application permissions in the B2C tenant:

Policy.Read.All
Policy.ReadWrite.TrustFramework

The app registration service principal must also be granted requisite permissions on the blob container in the resource tenant, for uploading styling files.
The blob container branding is where the styling files used by the sign-in pages are stored and published.

The minimum requirement for managing files in the container is Reader and Data Access.

Branding¶

The branding pipelines are named <Environment> - branding and uses the variable group Customer b2c content deployment - <Environment>.

Upload branding files via Azure DevOps pipeline¶

Azure DevOps pipelines have been configured for uploading and publishing of branding files to the environments:

Dev - branding
Test - branding
Prod - branding

Development pipeline - branding¶

Automatic pipeline triggering is configured for deployment of branding in the development environment.
When the pipeline discovers changes committed to the branding folder, regardless of branch, the pipeline starts running.

This means that every for pull request (PR) merged, that makes modifications to files in the include path, triggers the pipeline to run, in the same goes for any branch making changes to these files.

This is the (current) configuration for the development environment:

trigger:
  batch: true
  paths:
    include:
      - Pipelines/Dev-branding.yml
      - Pipelines/Templates/Template-branding.yml
      - Environments/Development/branding

Test and Production pipelines - branding¶

For test and production, a manual action is required to trigger pipeline for deployment of branding files to respective environments.
There are no Environments/<Test/Production>/branding folders, the Development files are generalized so that they can be promoted to other environments using environment specific parameters.

This is the (current) configuration for the test and production environment (replace Test with Prod):

trigger:
  paths:
    include:
      - Pipelines/Test-branding.yml
      - Pipelines/Templates/Template-branding.yml

Pipelines in all environments are configured with includes to their own yaml pipeline configuration files.
With pipeline configuration changes, the pipelines will trigger and start (but will require approval to run).

Policies¶

The policies pipelines are named <Environment> - policies - vX and uses the variable group Customer b2c content deployment - <Environment>.

Polices - Dev¶

Two (sometimes three) sets of policy files are uploaded to the Development environment.

* - v1
* - v2
(* - v3)

Having multiple sets of policy files allows parallel development of custom policies without the risk of breaking the sign-in experience.

When working on different User Journeys working within a single set of policy files can be sufficient.
When updating a User Journey it is beneficial to be able to test the outcome to avoid disrupting authentication flows.
Breaking a User Journey can cause developers to get unexpected results and waste time troubleshooting errors that are not theirs.

Only a development environment will invariably have a need for more than two sets of policies.

Any v3 policies are totally experimental and usually only know to Identity Experience developers.
If present, v3 polices only live in the development environment and will not be promoted to neither Test nor Prod.

The v1 and v2 polices may both be used actively by integrated applications that are under development.
Usually only v1 policies are used, but when testing new User Journey functionality, v2 policies may be useful for developers.
Only Identity developers will know what v2 (and v3) polices are available, and so these policies will be used more sparsely.

Polices - Test¶

NOTE!

Policy files in Test and Prod environments are promoted from the repository Development\Policies - vX folder.

Two DevOps pipelines are configured for uploading two sets of policy files to the Test environment.

* - v1
* - v2

Policies v1 hold definitions and User Journeys that will be promoted to the Prod environment.
This is the stable set of policy files with User Journeys where developers, testers and end users will mostly interact.

Policies v2 may be useful to allow testing of new features or quick bugfix testing (without interrupting the existing flows).

Polices - Prod¶

NOTE!

Policy files in Test and Prod environments are promoted from the repository Development\Policies - vX folder.

One DevOps pipeline is configured for uploading policy files to the Prod environment.

* - v1

Policies deployed in production should have been thoroughly tested in other environments before being released here.

Upload policy files via Azure DevOps pipeline¶

Azure DevOps pipelines have been configured for uploading custom policy files to environments:

Dev - policies - v1
Dev - policies - v2
(Dev - policies - v3)
Test - policies - v1
Test - policies - v2
Prod - policies - v1

Development pipelines - policies¶

Automatic pipeline triggering is configured for deployment of custom policy files in the development environment.
When the pipeline discovers changes committed to the respective policy folder, regardless of branch, the pipeline starts running.

This means that every for pull request (PR) merged, that makes modifications to files in the include path, triggers the pipeline to run, in the same goes for any branch making changes to these files.

Pipelines in all environments are configured with includes to their own yaml pipeline configuration files.

This is the (current) configuration for the v1 (for v2 and v3, replace versions, and dev with test) policies in the development environment:

trigger:
  batch: true
  paths:
    include:
      - Pipelines/Policies dev v1.yml
      - Pipelines/Templates/Template-policies.yml
      - Environments/Development/policies/v1

Test and Production pipelines - policies¶

For test and production environments, a manual action is required to trigger pipeline for deployment of custom policy files.
There are no Environments/<Test/Production>/policies folders, the Development files are generalized so that they can be promoted to other environments using environment specific parameters.

This is the (current) configuration for the production environment:

trigger:
  paths:
    include:
      - Pipelines/Policies v1.yml
      - Pipelines/Templates/Template-policies.yml

Pipelines in all environments are configured with includes to their own yaml pipeline configuration files.
With pipeline configuration changes, the pipelines will trigger and start (but will require approval to run).

How to work with an Azure DevOps repository¶

Pushing changes to an central source controlled repository usually involves Git and an editor. Microsoft's Visual Studio Code is a good and lightweight alternative, albeit some extensions may improve the user experience.

The procedure for working with online repositories is very similar regardless of vendor.

The following (recommended) procedure uses an Azure DevOps repository (other popular alternatives are GitHub and Bitbucket).

Recommended procedure¶

Branch out from the main branch (using graphical user interface or shell / terminal)
Make code changes in the new branch
1. If environment is Development, it is convenient to manually upload files
2. Eventually, manual upload files will only be possible in Development as all changes to Test and Production should be fully automated
Upload changes and test Azure AD B2C pages to verify that modifications were successful
Now the working branch are ready to be merged to the main branch, so everyone with a copy of the repository can get the latest version
Create a pull request that pushes changes from the working branch into main
Double-check the proposed changes (Files), assign (one or more) Required reviewer and select Create
When the PR is created, make sure that there are *no* Merge conflicts
Inform reviewer(s) of PR (copy and share the web site link in the browser address field)
Configure Auto-complete (Merge type Merge - Delete <working branch> after merging) for automatic merge or wait for PR to be approved, then select Complete
Switch back to main branch, pull newly applied changes, delete working branch

Checking in files to git repository with Visual Studio Code¶

The following procedure is based on Visual Studio Code.

Any other editor of choice (often referred to as ISE - integrated scripting environment) can be used as git is installed and works independently.

How to Install Git (and / or download).

Branch out from the main branch¶

In Visual Studio Code create a new branch by following these steps:

TIP!

First clone the project repository (this will create a local folder).

Branching - graphical user interface¶

Press "F1" and type "create branch"
1. Select "Git: Create Branch..."
2. Enter the "working name" of the new branch
Make changes
Test changes by uploading files (for the Development environment)
Commit changes
Push changes
Create pull request (PR) in Azure DevOps, either yourself or have someone else create one
Approve and merge PR
Switch to main branch, pull changes, delete branch (optional, but recommended)

Branching - terminal / shell¶

By supplying the -c parameter the git switch command creates and switches to the branch:

git switch -c <new branch name>
Make changes
git add . (or git add *) (adds all changes, single files can be select instead)
git commit -m "<commit message>"
git status (see which files are committed)
git push --set-upstream origin <branch name>
(The -u == --set-upstream and is a one-time operation to create the new branch in Azure DevOps, new commits only need git push)
Create pull request (PR) in Azure DevOps
Approve and merge PR
git checkout main
git pull
git branch -d <new branch name> (deletes local branch, optional, but recommended)