Azure AD B2C: Custom policies – tools & resources

Welcome again to the Azure AD B2C post series!

Introduction

In this post I will tell about tools and resources that help (or are essential) while working with custom policies.

However, wanting this post to be as practical as possible I’ll start from tooling which will help in analyzing and moving around in the policy content we exported in ther first post of the series and list valuable resources at the end.

Tooling

The content we exported in the first post with a little help from browser’s Developer mode and Postman is an XML file. A rather big XML file for that matter, at least when it comes to being handled by a human. Although the sheer size and number of things inside can be a bit intimidating we will try to deal with it part by part, element by element and tools will help us.

If you’re determined enough you can use any text editor but in the long run you probably don’t want that.

What is important thing to know while choosing a tool is that there is an XSD scheme file published. It can be used for an offline validation and is also quite nicely commented so it can work one of documentation resources as well.

You can find the file here (more about the rest of the repository later in the post) – Custom policies XSD schema

Using the exported XML together with XSD file you can use any decent enough XML editor you like. Some of them are more sophisticated than others but as XML editors are not the main topic of this post I won’t get into details.

For the purpose of this blog series I’ll go with an editor, which supports some of nice-to-have features (like XML syntax highlighting and policy outlining) and which is multiplatform anyone reading this can try repeating the experience without looking for another tool regardless of the platform used.

Visual Studio Code

Let’s start with getting Visual Studio Code then – a code editor with Git support and lots of extentions which can prove useful.

Download Visual Studio Code here

After installing we will add some extensions to have the tool all up and running at full speed with all the toys in place right from the beginning.

XML Tool – support of XML, XPath, formatting etc.
Azure AD B2C (Beta)

The firts plugin is self-explanatory, it is just for adding XML support to editor. The second one is definitely more interesting in the long run. Some features that will prove useful later are

object outlining (Custom Policy Explorer)

some actions for quick object inserting

help with navigating around and peeking definitions

To use these features properly you just need to open folder containing your policy files from within Visual Studio Code and you’re ready to go.

Validation

When you play around with the policies you may want to validate them before trying to upload. As you can imagine they fail to upload when there’s something wrong with them so validating earlier saves time if you do experiment with something, especially using trial and error approach (which at some point you probably will do, despite the docs getting beter and better).

As I already mentioned there are XML tools which can do the validation. I haven’t found such a thing that would work nicely in Visual Studio Code
yet but while exploring the Internet I found an interesting solution I thought was worth showing. A Powershell script to validate XML against an XSD schema. Doesn’t it sound nice?

Here’s where I found it:
Born to Automate blog

Here’s my version after some minor modifications. It may not be that good for using within other scripts now (writes output instead of returning boolean) but does its job when checking the policy. Don’t judge me too harsh, I’m a PS newbie (which I’m a bit ashamed of).

Export-ModuleMember -Function Test-XmlSchema

function Test-XmlSchema {
    param
    (
        [Parameter(Mandatory = $true)]
        [String]
        $XmlPath,
       
        [Parameter(Mandatory = $true)]
        [String]
        $SchemaPath
    )

    $schemas = New-Object System.Xml.Schema.XmlSchemaSet
    $schemas.CompilationSettings.EnableUpaCheck = $false
    $schema = ReadSchema $SchemaPath
    [void]($schemas.Add($schema))
    $schemas.Compile()
      
    try {
        [xml]$xmlData = Get-Content $XmlPath
        $xmlData.Schemas = $schemas

        #Validate the schema. This will fail if is invalid schema
        $xmlData.Validate($null)
        Write-Output 'OK'
    }
    catch [System.Xml.Schema.XmlSchemaValidationException] {
        Write-Output $_.Exception.Message
    }
}

Function ReadSchema {
    param($SchemaPath)
    try {
        $schemaItem = Get-Item $SchemaPath
        $stream = $schemaItem.OpenRead()
        $schema = [Xml.Schema.XmlSchema]::Read($stream, $null)
        return $schema
    }
    catch {
        throw
    }
    finally {
        if ($stream) {
            $stream.Close()
        }
    }
}

Export-ModuleMember -Function Test-XmlSchema

function Test-XmlSchema {

param

(

[Parameter(Mandatory = $true)]

[String]

$XmlPath,

[Parameter(Mandatory = $true)]

[String]

$SchemaPath

)

$schemas = New-Object System.Xml.Schema.XmlSchemaSet

$schemas.CompilationSettings.EnableUpaCheck = $false

$schema = ReadSchema $SchemaPath

[void]($schemas.Add($schema))

$schemas.Compile()

try {

[xml]$xmlData = Get-Content $XmlPath

$xmlData.Schemas = $schemas

#Validate the schema. This will fail if is invalid schema

$xmlData.Validate($null)

Write-Output 'OK'

}

catch [System.Xml.Schema.XmlSchemaValidationException] {

Write-Output $_.Exception.Message

}

Function ReadSchema {

param($SchemaPath)

try {

$schemaItem = Get-Item $SchemaPath

$stream = $schemaItem.OpenRead()

$schema = [Xml.Schema.XmlSchema]::Read($stream, $null)

return $schema

}

catch {

throw

}

finally {

if ($stream) {

$stream.Close()

}

And here’s how it works:

That was after making a purposeful error in the XML file by duplicating an object that should appear once most.

Resources

Having the tooling ready, let’s take a look what the Internet has to give when it comes to seeking knowledge on custom policies.

Official documentation

Until recently the official documentation was rather scarce but it was fortunately extended (at last!) with a very nice description of the schema file. It is now a really good source of seeking info on how existing things work, what is responsible for what and how to do own things.

Custom policies docs “starting point”
https://docs.microsoft.com/en-us/azure/active-directory-b2c/active-directory-b2c-get-started-custom

Identity Experience Framework Schema docs (this is good!)
https://docs.microsoft.com/en-us/azure/active-directory-b2c/trustframeworkpolicy

Other resources

Besides the official docs there are also other places where you can find different details, sometimes quite sophisticated.

One of this places is part of the Azure-Samples Git repo – AAD B2C advanced policies.
https://github.com/Azure-Samples/active-directory-b2c-advanced-policies
There is so much content there I won’t even try describing it. I will just point to a single folder that I think is particularly worth checking – Documentation.

But that’s not all from Azure Samples. Besides advanced policies there is also starter pack, also rich with content and including an XSD schema for policy files.
https://github.com/Azure-Samples/active-directory-b2c-custom-policy-starterpack

There’s naturally Stackoverflow, but at this moment there’s not much there (for Stacoverflow standards)
It’s best to look for Azure-ad-b2c tag.

You can also find some blog posts scattered around the Internet but they are not many and can be badly outdated. I mean – the described solutions probably still work but there may already be better ways to achieve what they do.

What’s next?

In the next post I will tell a bit about how custom policies are organized according to documentation, how are they really organized and how can you organize them if you plan something serious with custom policies.

With a bit of luck I will also try to squeeze in a description of how to prepare the XML we exported in the first post for further work.

See you soon! Hopefully sooner then this time 😉