That sounds fantastic until you try to do the one thing everyone actually uses these platforms for: collecting a custom field during sign-up and shoving it into the token.

I recently spent way too long trying to get a simple custom attribute (MemberId) to show up in a JWT. Here is the breakdown of how to do it, and more importantly, how to actually get the data out without losing your mind.

The New World (Briefly)

If you are coming from B2C, forget the Identity Experience Framework. CIAM uses User Flows (the easy GUI ones) for almost everything.

If you need custom logic (like validating a Member ID or generating one), you don’t call a REST API from an XML policy anymore. You use Custom Authentication Extensions. These trigger Azure Functions at specific events, like OnAttributeCollectionSubmit.

It’s cleaner, honestly. I wired up a Function to validate my MemberId and it worked immediately. The data was saved to the user profile.

The Problem: The Case of the Missing Claim

I had the MemberId in the directory. I verified it via Graph Explorer. It was there, staring me in the face with its ugly extension name:

But when I logged in? My ID Token looked like this:

{
  "aud": "efe03d75...",
  "iss": "https://...",
  "email": "steve@example.com",
  "name": "Steve"
}

No Member ID. Nothing. Just standard claims.

Trap #1: The Null Value

First technical “gotcha” of CIAM: If a custom attribute is null, it is dropped.

It doesn’t send a null value. It doesn’t send an empty string. The claim just ceases to exist. So if your Azure Function fails to write the data, or you mess up the casing on the attribute name (it’s case-sensitive, by the way), you will be debugging a phantom.

Always check Graph Explorer first. If the data isn’t on the user object, stop debugging the token. Fix the save.

Trap #2: The Red Herring (App Registration)

If you Google this, you will find documentation telling you to manually edit the optionalClaims in the App Registration Manifest. Don’t. That is a rabbit hole of case-sensitivity issues and source: null errors.

You only need to do two things in your App Registration:

1. Permissions: Ensure your app has User.Read permission on Microsoft Graph and—crucially—Grant Admin Consent.
2. Manifest: Toggle one specific flag to allow the token issuer to accept custom maps.

"acceptMappedClaims": true

That’s it. Close the App Registration. You are done there.

The Real Fix: Enterprise Applications

The actual working UI for mapping and renaming claims in CIAM is hidden in the Enterprise Application blade (the service principal instance), not the App Registration definition.

Go to Enterprise Applications -> Find your app.

Click Single sign-on (even if you are using OIDC/OAuth, this is where the UI lives).

Click Edit on the Attributes & Claims box.

This is the only place that actually lets you see the hidden b2c-extensions-app schema without using PowerShell.

When you add a new claim, change the Source to Directory schema extension. You will be able to select the backend extension app that holds your custom data.

Select your attribute from the list.

Finally, give it the clean name you actually want in your code (e.g., memberId instead of extension_<your-app-guid-here>_MemberId).

The Result

Once I saved that mapping in the Enterprise App, the token finally respected the data.

{
  "email": "steve@example.com",
  "memberId": "ASD123"
}

It works, but man, they really make you dig for it.

I also assume if you have gotten to this post, you are either looking to change that approach on your own, have been told by your “security team” to do better or maybe some of both.

A lot of what I am going to detail below is lifted from here but with a UI and some screenshots to help.

To preface some of what I will show here, the example project is using the following:

• dotnet 5
• EFCore
• Windows App Service
• Azure Sql Serverless

I won’t be going into detail on how to setup EFCore using SqlServer as there are plenty of other examples, but I do want to focus on how to get your App Service talking to your Azure Sql Database using a managed identity.

Azure Sql Authentication Method

If you are just creating your Azure Sql Server now, make sure you select Use Azure Active Directory (Azure AD) authentication:

If you already have an Azure Sql Server and Database, go to your server and click on Settings -> Azure Active Directory:

By selecting this option (for either) you are effectively disabling the Sql Authentication for the server. You will also have to assign an AD Admin for the server, make sure to assign an admin account you have access to as you will need it shortly…

Enabling Managed Identity

This should be pretty straightforward, go to your App Service, find Settings -> Identity and click Status -> On:

Your app service now has a proper identity.

Creating the Contained User

For this next step, you will need to make sure you have the server Firewall opened up enough for you to access the database and run some Sql, but you might as well grant access for the Azure Services too:

Now that you have line of sight to the server, open the database and you can either open up the Query Editor:

Or if you rather Sql Server Management Studio:

Regardless, you need to execute the following Sql:

-- WITH OBJECT_ID only needed if you have names not unique between app services and app registrations.
CREATE USER [your-app-service] FROM EXTERNAL PROVIDER WITH OBJECT_ID = 'a290ccc0-6142-4ff6-9620-7ea2393e6ed2';

ALTER ROLE db_datareader ADD MEMBER [your-app-service];
ALTER ROLE db_datawriter ADD MEMBER [your-app-service];
ALTER ROLE db_ddladmin ADD MEMBER [your-app-service];

Where your-app-service is the actual name of your App Service in Azure (please make sure this is unique, both within App Services but also within Active Directory -> App Registrations). You will get an error upon creation if it can not find the actual resource by name, so you won’t have to worry about botching it up yet… Also make sure to use applicable roles for your App Service.

Alright so we have Active Directory Authentication enabled for the Sql Server, a Managed Identity for our App Service, an actual user in the database for that Identity with roles, we have the database server Firewall accepting traffic from Azure resources, all we need now is a proper connection string:

ConnectionString

Server=tcp:yourDbServer.database.windows.net;Authentication=Active Directory Default; Database=YourDatabase;

And realistically, at this point, you should be done!

Additional note, I ran into some odd errors about authentication is 'unknown_type' specifically for the ConnectionString. It had seemed to be an issue with the Microsoft.Data.SqlClient that is included in the EFCore SqlServer package. Simply by adding the Microsoft.Data.SqlClient package to the solution/project, to its latest version resolved this error. You may or may need to follow suit.

Happy Breaking.

First, the code I was using as a guide was using the authorizationCode form the original sign in to obtain an access token for graph. That is just fine and acceptable, until you need to make another call. Simply put, sometime in Sept of 2018, AAD stopped letting Auth codes be reused.

Frustrated but not defeated, I found a super helpful post on working thru this change.

Startup.Auth.cs

Close but not quite…

// Within OpenIdConnectAuthenticationNotifications()
AuthorizationCodeReceived = (context) =>
{
    // Get these for later
    var redirectUri = new Uri(HttpContext.Current.Request.Url.GetLeftPart(UriPartial.Path));
    string signedInUserObjectId = context.AuthenticationTicket.Identity.FindFirst("http://schemas.microsoft.com/identity/claims/objectidentifier").Value;
    string userTenantId = context.AuthenticationTicket.Identity.FindFirst("http://schemas.microsoft.com/identity/claims/tenantid").Value;

    // Like a good kid, we are going to store our secrets in Azure KeyVault
    var redirectUri = new Uri(HttpContext.Current.Request.Url.GetLeftPart(UriPartial.Path));
    KeyVaultService keyVaultService = new KeyVaultService();
    var secureString = await keyVaultService.GetAsync(ApplicationConfig.ActiveDirectoryPortalKey);
    SecureClientSecret clientSecret = new SecureClientSecret(secureString);

    // Obtain an access token for the current application using the authorization code (modified from that Linkedin Post)
    ClientCredential credential = new ClientCredential(ApplicationConfig.ActiveDirectoryClientID, clientSecret);
    AuthenticationContext authContext = new AuthenticationContext($"{ApplicationConfig.ActiveDirectoryEndPoint}{userTenantId}");
    AuthenticationResult result = authContext.AcquireTokenByAuthorizationCodeAsync(context.ProtocolMessage.Code, redirectUri, credential, context.Options.ClientId).Result;

    // Obtain and cache access tokens for additional resources using the access token
    // from the application as an assertion (modified from Linkedin Post)
    UserAssertion userAssertion = new UserAssertion(result.AccessToken);
    AuthenticationResult graphResult = authContext.AcquireTokenAsync("https://graph.microsoft.com", credential, userAssertion).Result;
    
    // Actual calls to Graph, blows up before even getting here...
    IGraphClient graphClient = new GraphClient(userTenantId, graphResult);
    List<RoleModel> roles = await graphClient.GetDirectoryRolesAsync(signedInUserObjectId).ConfigureAwait(false);
...

It got me about 90% of the way there, but as we all know, it is that last 10% that is the hardest. The part that was failing hard was the graphResult = authContext.AquireTokenAsync call. I kept getting a terribly vague Object reference not set to an instance of an object. error from a proper MS class, which only added to the frustration. Finally after hours of debugging, searching and all those things devs do when they can’t figure something out, I found a trail leading SecureClientSecret being one time use…

Startup.Auth.cs

Much betta!

AuthorizationCodeReceived = async (context) =>
{
    // Same as above
    var redirectUri = new Uri(HttpContext.Current.Request.Url.GetLeftPart(UriPartial.Path));
    string signedInUserObjectId = context.AuthenticationTicket.Identity.FindFirst("http://schemas.microsoft.com/identity/claims/objectidentifier").Value;
    string userTenantId = context.AuthenticationTicket.Identity.FindFirst("http://schemas.microsoft.com/identity/claims/tenantid").Value;

    // Same as above
    KeyVaultService keyVaultService = new KeyVaultService();
    var secureString = await keyVaultService.GetAsync(ApplicationConfig.ActiveDirectoryPortalKey);
    SecureClientSecret clientSecret = new SecureClientSecret(secureString);

    // Same as above
    ClientCredential credential = new ClientCredential(ApplicationConfig.ActiveDirectoryClientID, clientSecret);
    AuthenticationContext authContext = new AuthenticationContext($"{ApplicationConfig.ActiveDirectoryEndPoint}{userTenantId}");
    AuthenticationResult result = authContext.AcquireTokenByAuthorizationCodeAsync(context.ProtocolMessage.Code, redirectUri, credential, context.Options.ClientId).Result;

    // Create a SECOND SecureClientSecret, just for the Graph calls...
    SecureClientSecret graphClientSecret = new SecureClientSecret(secureString);
    ClientCredential graphClientCredential = new ClientCredential(ApplicationConfig.ActiveDirectoryClientID, graphClientSecret);
    UserAssertion userAssertion = new UserAssertion(result.AccessToken);
    AuthenticationResult graphResult = await authContext.AcquireTokenAsync("https://graph.microsoft.com", graphClientCredential, userAssertion);
    
    // No explosions, works as expected...
    IGraphClient graphClient = new GraphClient(userTenantId, graphResult);
    List<RoleModel> roles = await graphClient.GetDirectoryRolesAsync(signedInUserObjectId).ConfigureAwait(false);
...

Not going to lie, I feel a bit miffed at all of this. There is some weak documentation supporting this was done “intentionally” for security purposes. Having it documented in the class metadata itself or make it disposable if you are that concerned, anything along those lines would have saved me several hours of hair pulling.

Don’t worry MS, I won’t send you the bill.

Thankfully there is a nice little cli for ef; dotnet-ef. The cli made it easy to include new migrations/features into the project and also help us facilitate getting those changes out into the wild. Below are a few of the commands and snippets we used to accomplish this:

Basic usage

Below covers just some of the basic cli commands to get up and running.

Installing dotnet-ef

Pretty basic, but just getting it installed for use later…

dotnet tool install --global dotnet-ef

Adding a migration

Adding a new migration; could be a new “feature” or a set of significant changes

dotnet ef migrations add FeatureName

Updating database

This command will actually update the database that is part of the current project, given the current migration files.

dotnet ef database update --project .\src\YourProject.csproj

DevOps usage

Assuming you are now at a point where you have your migrations in source and are ready to deploy, below should help guide you thru getting those changes out onto servers.

Create a migration script

After all your standard dotnet core build tasks, add a powershell task like so:

- task: PowerShell@2
  inputs:
    targetType: 'inline'
    script: |
      dotnet tool install --global dotnet-ef
      dotnet ef migrations script --idempotent --project $(Build.SourcesDirectory)\src\YourProject.csproj --output $(Build.ArtifactStagingDirectory)/db.sql
 

What the above does is install the dotnet-ef cli within the context of the hosted agent and then use it to create a single script to encompass all the migration changes. As you can see we specify the --project, the --output folder so it gets picked up by the publishBuildArtifacts task and a --idempotent flag. The --idempotent flag encompasses all changes with a check to the __EFMigrationsHistory to see what version of migration it is on, thus allowing you to both create from scratch and iterate over an existing database with the same script:

IF NOT EXISTS(SELECT * FROM [__EFMigrationsHistory] WHERE [MigrationId] = N'20200923211638_InitialCreate')

Now that we have a single script that can handle all things database schema, let’s make sure the release is capable of executing this.

Deploy database changes in Release

Assuming you are at a point where all your web assets are already being deployed successfully, let’s find the SQL Server database deploy task. Search for it by name in the task search and add it to your release. This task is able to deploy dacpac files as well as sql scripts, we will be using the latter. After adding the task, populate it using the following:

• Deploy SQL using: Sql Query File
• Sql File: $(System.DefaultWorkingDirectory)\_YourProject\drop\db.sql
• Execute within a transaction: true
• Server Name: <the sql server instance, with respect to where your release agent is running>
• Database Name: NameOfYourDatabase
  • Make sure the database at exists
  • If using Windows Authentication, make sure the user that the release agent runs as has access to this database.

Send it.

You should now be able to encompass all your database changes in source control, generate a change script that respects the database version and effectively deploy those changes to the database.

Enjoy!

Ultimately in order to validate this webhook, we needed to know the following:

• The header (or query parameter) that the signature was being stuffed in
• The secret that was being used to create the signature

If we know that, we can

• create the signature, given the payload of the body
• can compare the signatures
• pass or fail the request based on comparison

Webhook Signature Verification Policy

<policies>
    <inbound>
        <base />
        <!-- Grab the signature from the header and stuff it in a variable -->
        <set-variable name="requestSignature" value="@{
            return context.Request.Headers["X-Hub-Signature"][0].Replace("sha1=","");
            }" />
        <!-- Take the payload and the Secret (which should be in a KeyVault or at least a secret Named value) 
            and generate a hash to compare to the original.-->
        <set-variable name="compareHash" value="@{
            byte[] keyByte = System.Text.ASCIIEncoding.ASCII.GetBytes("NotASecret!");
            byte[] messageBytes = System.Text.ASCIIEncoding.ASCII.GetBytes(context.Request.Body.As<string>());
            var hash = new HMACSHA1(keyByte);
            var hashBytes = hash.ComputeHash(messageBytes);
            StringBuilder hex = new StringBuilder(hashBytes.Length * 2);
            foreach (byte b in hashBytes){
                hex.AppendFormat("{0:x2}", b);
            }
            return (string)hex.ToString();
        }" />
        <choose>
            <!-- Cast as strings and comapare the signature/hashes -->
            <when condition="@((string)context.Variables["requestSignature"] != (string)context.Variables["compareHash"])">
                <!-- The return response stops all further processing and in this case returns a 401 -->
                <return-response>
                    <set-status code="401" reason="Not Authorized" />
                    <!-- Uncomment if you need to debug -->
                    <!-- <set-body template="none">@{
                        return context.Variables["requestSignature"] + "::" + context.Variables["compareHash"];
                    }</set-body> -->
                </return-response>
            </when>
            <otherwise>
                <set-backend-service base-url="http://yourbackend.service/notreal/" />
            </otherwise>
        </choose>
    </inbound>
    <!-- The backend and outbound nodes, ie: the rest of the stuff -->
</policies>

Thru the variables and then the choose/when condition, we can short circuit any invalid signatures before going any further and in the event it is valid, the body of the original request will continue to the backend-service url for further processing. In this case it was a repository that handled resource orchestration on an internal network (Ansible, Puppet or Chef I don’t recall which).

This is just one of many ways that Azure APIM can prove it’s power and flexibility!

PS: Anyone looking for a way to “sanity check” or simply test the validation logic of the policy, check out the Postman collection here. Before anything, swap out the baseurl, apimsubscriptionkey and secret Collection variables to meet your needs. Then, swing over to the Pre-request Scripts to see exactly how the entire signature is generated.

Unlike proper Web Application projects, Website projects in Visual Studio just take everything under a folder and assume that is the project. And 9 times out of 10 (based on the handful of times I have dealt with them) these projects, when in source control, have all binaries checked in as well.

References can be sorta made using NuGet on the Bin folder, but in my experience this only sort-of works: .refresh files are added to the folder as a kind of redirect to the original file located elsewhere (like the ../packages directory. These refreshes are triggered at certain times like when the project is opened or switching between projects. It also does not care about any folders nested underneath like the Bin/roslyn folder.

That kinda stinks.

The Solution

A single Powershell file to help facilitate the restore and frankly, copying of dlls locally so we can work without having to shove binary files in source. In addition to the script, I also included a custom nuget.config to allow for other NuGet feeds (like Telerik).

Folder Structure:

• Project/ (root)
  • .nuget/nuget.config
  • lib/
  • packages/
  • src/
  • restore.ps1

.nuget/nuget.config

Make sure we have all the dependencies we need, in our case we needed Telerik as well, which happens to be authenticated.

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <packageSources>
    <add key="Telerik" value="https://nuget.telerik.com/nuget" />
    <add key="nuget.org" value="https://api.nuget.org/v3/index.json" />
  </packageSources>
  <activePackageSource>
    <add key="All" value="(Aggregate source)" />
  </activePackageSource>
  <packageSourceCredentials>
    <Telerik>
      <add key="Username" value="bob@pizza.co" />
      <add key="ClearTextPassword" value="NoToppings!" />
    </Telerik>
  </packageSourceCredentials>
</configuration>

restore.ps1

Handle what the package manager in a website project can’t:

set-location $PSScriptRoot
Write-Host "Executing NuGet self update and restore" -ForegroundColor Green
nuget update -self
nuget restore .\src\packages.config  -PackagesDirectory packages

set-location $PSScriptRoot\src
Write-Host "Copying files for .refresh" -ForegroundColor Green
Get-ChildItem -Path ./ -Filter *.refresh -Recurse -File -Name | ForEach-Object {
    $referenceFile = Get-Content $_
    $destinationFile = $_.Replace(".refresh", "")
    Write-Host $referenceFile " -> "   $destinationFile
    Copy-Item $referenceFile -Destination $destinationFile
}

Executing this script does the following:

• NuGet self update
• NuGet restore using the packages.config maintained by the project and puts them one layer up in the ../packages directory
• Iterates thru all of the .refresh files in the project and copies over the original *.dll file to the location of the .refresh file.

This helped a lot for local development, particularly for the initial environment setups. Queue the next step…

CI/CD

Along with this effort, we also helped set up CI/CD within Azure Devops. We used a very similar principle in resolving the dependencies during the Build pipeline:

• Use NuGet 5.5.0 task
• NuGet restore task
  • Path to NuGet.config $/Project/.nuget/nuget.config
  • Destination Directory $(UserProfile)/.nuget/packages
• PowerShell Script task (inline)

  • Write-Host $PSScriptRoot
    Write-Host "Copying files for .refresh" -ForegroundColor Green
    Get-ChildItem -Path ./ -Filter *.refresh -Recurse -File -Name | ForEach-Object {
     $referenceFile = (Get-Content $_).Replace("..\packages","$(UserProfile)\.nuget\packages")
     $destinationFile = $_.Replace(".refresh", "")
     Write-Host $referenceFile " -> "   $destinationFile
     Copy-Item $referenceFile -Destination $destinationFile
    }
    
    

• Build Solution task
• Solution: $/Project/src/website.publishproj
• MSBuild Arguments
  • /p:deployOnBuild=true
  • /p:publishProfile=Project
  • /p:publishUrl="$(build.artifactstagingdirectory)\\"
• Publish Artifacts task

The result of the above pipeline and really the entire effort is a solution that doesn’t involve checking in binaries, uses NuGet and overall feels just slightly closer to normal Web Application development.

Hope this helps!

Ultimately I wanted something like SitecoreUnicorn but for Kentico. In my quest to find this tool, I didn’t find many that checked all these req’s so I decided to just start throwing things at a wall to see what stuck. After some dev effort and show and tell with colleagues, I have what I consider not even a beta solution yet.

Let me introduce to you Bridge for Kentico!

-|–|- Bridge

Github Repository

The what?

• A Yaml based service for handling the promotion of Kentico CMS based items thru source control.

The why?

• Because XML is terrible to read and even harder to merge. The reason I created this was to allow us to not only break down features modularly thru some basic configs, but I wanted to make sure it was easy to adopt and that means making it easy to use with source control.

The when?

• Use this either along side an existing Kentico build using the nuget or standalone by cloning this repo and updating the connectionString parameters to match your Kentico db.

The how?

• Installation:
  • Standalone: clone, compile and run the app. Fire up a browser and go to localhost/bridge/index
  • Alongside: install via nuget and navigate to yourKenticoUrl/Admin/BridgeUI/index
• The configs:
  • CoreConfig: one or more core config can be specified. They contain a list of classtypes to care about and a list of ignoreFields on the item to simply ignore when serializing/syncing.
  • ContentConfig: one or more content config can be specified. Contains a list of pagetypes to care about and a list of ignoreFields on the items to not serialize/sync. This also will handle all custom fields. Also, a query attribute allows you to pick which content within the tree to focus on. This should support a basic Kentico Query.
• Using the GUI:
  • Core Configs:
    • Core Configs Serialize All: iterates thru all of the defined coreConfig nodes and fetches all the corresponding classes, and stuffs them into the serialization/core/{coreConfigName} folder.
    • Core Configs Sync All: this is the inverse of the Serialize All task, it takes what’s in the file system and pushes it to the Kentico DB.
    • “Named Core Config” Serialize: pulls just the specified config down to the file system
    • “Named Core Config” Sync: pushes just the specified config up to the database
    • “Named Core Config” Diff: does a temp serialize of the current Kentico DB and compares it to what’s in the filesystem and spits out a diff.
  • Content Configs:
    • Content Configs Serialize All: iterates thru all of the defined contentConfig nodes and fetches all the corresponding classes, and stuffs them into the serialization/content/{contentConfigName} folder.
    • Content Configs Sync All: this is the inverse of the Serialize All task, it takes what’s in the file system and pushes it to the Kentico DB.
    • “Named Content Config” Serialize: pulls just the specified config down to the file system
    • “Named Content Config” Sync: pushes just the specified config up to the database
    • “Named Content Config” Diff: does a temp serialize of the current Kentico DB and compares it to what’s in the filesystem and spits out a diff.
• The Endpoints:
  • Within a dev-ops cycle (ie a release to a dev or test environment) make a call to the Bridge endpoints using an authenticated call (using something like curl, wget or Invoke-WebRequest).
  • The response itself should be a stream so it will respond as things occur rather than processing everything and responding.
  • The endpoints are as follows:
    • yourUrl/bridge/diffcore?/{configName}: returns the comparison between the serialized DB and what is in the file system for the optional core configName
    • yourUrl/bridge/diffcontent?/{configName}: returns the comparison between the serialized DB and what is in the file system for the optional content configName
    • yourUrl/bridge/serializecore?/{configName}: serializes the specified core config (or all if none specified) to the filesystem
    • yourUrl/bridge/serializecontent?/{configName}: serializes the specified content config (or all if none specified) to the filesystem
    • yourUrl/bridge/synccore?/{configName}: syncs the specified core config (or all if none specified) to the database
    • yourUrl/bridge/synccontent?/{configName}: syncs the specified content config (or all if none specified) to the database
  • My ultimate goal is to leverage the endpoints in order to promote a continuous integration and deployment methodology within the Kentico community

The dev questions?

• What kind of Class Types do the CoreConfigs include?
  • Any custom class you create in Kentico should be covered: page types, custom tables etc.
• What are the ignoreFields?
  • Fields that we are just going to ignore, either they are tied to users, sites, timestamps or other content.
  • We strip them so we can insert the content cleanly without reference to the originating source site.
• What fields do ContentConfigs include?
  • Anything not in the ignoreFields should be written to YAML.
  • This includes custom fields.
• Security?
  • Bridge actually ties into the Kentico membership provider.
  • Standalone: Using the NancyFx Basic Auth provider, it forwards the basic auth creds into the Kentico Provider to validate you are a user.
  • Alongside: it picks up the HttpContext.CurrentUser.IsAuthenticated from your logged in Kentico session.
  • Security wise, this is really just checking to make sure you are an authenticated user, nothing more, but we could in the future check for roles or claims.
  • If installing this in (eventually) a staging or production environment, you may want to consider using it only during the release process and then (programmatically) deleting the /Bridge folder and/or removing the NancyHttpRequestHandler entry in the web.config
• Why Nancy?
  • Low-ceremony dependency injection: so I could see about making this tool more universal
  • Lightweight and self-contained: I don’t know how people want to use this tool: standalone, alongside kentico?
  • Simple request control: I didn’t want to have to worry about the routes someone was using in their Kentico site.
• Why YAML?
  • Easy to read, easy to merge. I wanted to defer as much of this process to standard tooling like merging item conflicts using Kdiff/WinMerge etc.
  • Smaller file footprint: I didn’t need all of the wrapper XML nodes.
• Future plans?
  • Please feel free to hit me up if you like the tool but are having issues or would like to see any new features
  • If you feel inclined to contribute, forks and pull requests are always welcomed.
  • One thing I have already kinda planned for is allowing for multi-site configs, allowing you to handle different sites all within one GUI.
  • I have also considered abstracting out the Kentico libraries and making this into a tool that could handle a raw database as well, time will tell.

Disclaimer

This is in alpha for a reason: it’s incredibly green and raw. I am hoping over time it ages like a fine wine. With that said, use at your own risk until you are comfortable with the changes you are making.

Anyways, thanks for reading!

I had seen this before: <a class="nav-link" asp-controller="Account" asp-action="SignOut">Logout</a> so I thought it was worth a try. What I wanted was a way to explicitly hide or show a menu item, a button, a link or any DOM element really for certain users.

Since I already had the user and role management pieces sorted out, and some constants for these roles, I figured I could pass them in to my tag helper to denote which one(s) to show or hide for.

PermissionConstants.cs

public static class PermissionConstants
{
    public static class Job
    {
        public const string Create = "JobCreate";
        public const string Read = "JobRead";
        public const string Update = "JobUpdate";
        public const string Deactivate = "JobDeactivate";
    }

    public static class User
    {
        public const string Create = "UserCreate";
        public const string Read = "UserRead";
        public const string Update = "UserUpdate";
        public const string Deactivate = "UserDeactivate";
        public const string ManageRoles = "UserManageRoles";
    }
}

The above roles were associated with a user and acquired by doing a _userService.GetCurrentUserPermissionsAsync(), of course with some proper caching so we weren’t hammering a database with every instance of the tag helper.

ShowForTagHelper.cs

[HtmlTargetElement(Attributes="show-for-permission")]
[HtmlTargetElement(Attributes="hide-for-permission")]
public class ShowForTagHelper : TagHelper
{
    private readonly IUserService _userService;
    public ShowForTagHelper(IUserService userService)
    {
        _userService = userService;
    }

    /// <summary>
    /// Show this html element for a particular permission type
    /// </summary>
    [HtmlAttributeName("show-for-permission")]
    public string ShowForPermission { get; set; }

    /// <summary>
    /// Hide this html element for a particular permission type
    /// </summary>
    [HtmlAttributeName("hide-for-permission")]
    public string HideForPermission { get; set; }

    public override async Task ProcessAsync(TagHelperContext context, TagHelperOutput output)
    {
        base.Process(context, output);
        var currentUserPermissionsAll = await _userService.CurrentUserPermissionsAsync();
        if (currentUserPermissionsAll != null && currentUserPermissionsAll.Any())
        {
            var currentUserPermissions = currentUserPermissionsAll.Where(x => x.Value).Select(p => p.Key);
            bool showForUser = (ShowForPermission != null) ? currentUserPermissions
				.Intersect(_getPermissionsList(ShowForPermission)).Any() : true;
            bool hideForUser = (HideForPermission != null) ? currentUserPermissions
				.Intersect(_getPermissionsList(HideForPermission)).Any() : false;
            if (!showForUser || hideForUser)
            {
                output.SuppressOutput();
                //since at this point the output is suppressed, it doesn't pay to continue checking...
            }
        }
        else
        {
	    // if attribute exists, but user has no roles: hide
            output.SuppressOutput();
        }
    }

    private IEnumerable<string> _getPermissionsList(string permAttr)
    {
        return permAttr.Split(',');
    }
}

A quick unpacking of the above:

• _userService is injected into the constuctor
• two distinct attributes defined
  • HtmlTargetElement decorator associates the attributes to the helper
  • HtmlAttributeName associates the attributes to to concrete properties
• override the ProcessAsync method to do your thing
  • output.SuppressOutput() is the magic that hides this from ever being rendered

The last thing we need to do before we actually use this in markup is to register the namespace in the _ViewImports.cshtml:

ViewImports.cshtml

@using YourNamespace
@using StackExchange.Profiling
@addTagHelper *, MiniProfiler.AspNetCore.Mvc
@addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers
@addTagHelper *, SmartBreadcrumbs
@addTagHelper *, YourNamespace.Helpers

Yes, I know, there are a few other tag helpers registered, but for good reason: I love the MiniProfiler and use it on my local/dev/test instances as a sanity check and the SmartBreadcrumbs is handy for generating a breadcrumb nav by controller and action auto-magically..

SomeMarkup.cshtml

<!-- other markup, then an action link that only shows for people who have 
		the roles needed to view or update a Job -->

<a class="nav-link" asp-area="" asp-controller="Jobs" asp-action="Index" 
show-for-permission="@(PermissionConstants.Jobs.Read +","+PermissionConstants.Jobs.Update)">Profile</a>

<!-- more arbitrary markup, then an entire div hidden based on role -->

<div show-for-permission="@(PermissionConstants.User.Read +","+PermissionConstants.User.Update)">
    <!-- cool things only a user with User read/update perms can see or do -->
</div>

Hopefully the above shows you a real world case for using a custom TagHelper. Not only does it seem pretty clean and heavily reusable, but honestly it feels like it separates the concern of hiding or showing content based on a users permissions to a separate handler (almost AOP-esq, don’t quote me on that tho!).

In this case, I want a simple Http Triggered function with with Function auth level and supported GET|POST http methods. I gave it a name (WebhookPayloadEmail), dropped the below code in the run.csx and added entries for SmtpServer, SmtpUserName and SmtpPassword to the Application Settings of the Function App itself. Once done with all that, I ran it a few times locally to make sure it compiled, threw a few arbitrary values in the query, headers and request body to make sure they all got caught and once I confirmed that working, I figured we were ready to go and grabbed the Function url (</> Get function URL).

WebhookPayloadEmail Function

#r "Newtonsoft.Json"

using System.Net;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Primitives;
using Newtonsoft.Json;
using System.Net.Mail;

public static async Task<IActionResult> Run(HttpRequest req, ILogger log)
{
    log.LogInformation("C# HTTP trigger function processed a request.");
    var smtpHost = GetEnvironmentVariable("SmtpServer");
    var smtpPort = 587;
    var smtpEnableSsl = true;
    var smtpUser = GetEnvironmentVariable("SmtpUserName");
    var smtpPass = GetEnvironmentVariable("SmtpPassword");
    string requestBody = await new StreamReader(req.Body).ReadToEndAsync();
    string serializedQuery = JsonConvert.SerializeObject(req.Query);
    string seralizedHeader = JsonConvert.SerializeObject(req.Headers);

    using (var client = new SmtpClient(smtpHost, smtpPort))
    {
        client.UseDefaultCredentials = false;
        client.Credentials = new System.Net.NetworkCredential(smtpUser, smtpPass);
        client.DeliveryMethod = SmtpDeliveryMethod.Network;
        client.EnableSsl = smtpEnableSsl;
        MailMessage message = new MailMessage("from@test.test", "to@test.test");
        message.Subject = "Test Submission";
        message.IsBodyHtml = false;
        message.Body = requestBody + "\n\n" + serializedQuery + "\n\n" + seralizedHeader;
        
        try
        {
            client.Send(message);
            log.LogInformation("Success.");
            

            return (ActionResult)new OkObjectResult(
                new {
                    status = true,
                    message = string.Empty
                });
        }
        catch (Exception ex)
        {
            log.LogError("Failure: " + ex.ToString());
            return new BadRequestObjectResult(new
                {
                    status = false,
                    message = "Check Azure Function Logs for more information."
                });
        }
    }
}

public static string GetEnvironmentVariable(string name)
{
    return Environment.GetEnvironmentVariable(name, EnvironmentVariableTarget.Process);
}

Above is the main guts of this post but to round things out, in my Azure B2C scenario, I created a ClaimsProvider (see below) to trigger on the last OrchestrationStep of the Invitation of the invitation UserJourney:

<ClaimsProvider>
    <DisplayName>Azure Functions</DisplayName>
    <TechnicalProfiles>
        <!-- The following technical profile sends a mail message to a user. -->
        <TechnicalProfile Id="AzureFunctions-SendMailWebHook">
            <DisplayName>Send Mail Web Hook Azure Function</DisplayName>
            <Protocol Name="Proprietary" Handler="Web.TPEngine.Providers.RestfulProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />
            <Metadata>
                <Item Key="ServiceUrl">https://yourtenant.azurewebsites.net/api/WebhookPayloadEmail?code=T4Isi2N0tAR3L1C0D3==</Item>
                <Item Key="AuthenticationType">None</Item>
                <Item Key="SendClaimsIn">Body</Item>
                <Item Key="AllowInsecureAuthInProduction">true</Item>
            </Metadata>
            <InputClaims>
                <InputClaim ClaimTypeReferenceId="objectId" />
                <!--<InputClaim ClaimTypeReferenceId="anotherValue" PartnerClaimType="claimNameInPayload" />-->
            </InputClaims>
            <UseTechnicalProfileForSessionManagement ReferenceId="SM-Noop" />
        </TechnicalProfile>
    </TechnicalProfiles>
</ClaimsProvider>

And there you have it, an Azure Function that could funcition as a Webhook recipient or a ServiceUrl for an Azure B2C Policy!

I realize this discusses the Azure Function more than Azure B2C, but after a little bit of headache and following this tutorial and this codebase pretty closely, I found Azure B2C to be extremely powerful for handling authentication (just in case you stumble on this page looking for help on B2C and not Azure Functions)…

</message>

For the sake of this blog post, I am going to try and lay out the base implementation details needed to both inject the Kentico services and your own custom ones. Our solution will be Kentico 12 using Autofac as our DI container. Before anything, we must get the application to pick up and register the services at application start:

DependencyInjectionConfig.cs

namespace YourNamespace.App_Start
{
    public static class DependencyInjectionConfig
    {
        public static void RegisterDependencies()
        {
            // Initializes the Autofac builder instance
            var builder = new ContainerBuilder();

            // Adds a custom registration source (IRegistrationSource) that registers Kentico Services
            builder.RegisterSource(new CMSRegistrationSource());
            builder.RegisterControllers(typeof(MvcApplication).Assembly);

            // Find all `Service` classes by their interface and resolve the attribute/class types
            var serviceIntefaces = Assembly.GetExecutingAssembly().GetTypes()
					.Where(x => x.IsInterface && x.Name.EndsWith("Service"));

            var serviceClasses = Assembly.GetExecutingAssembly().GetTypes()
					.Where(x => !x.IsInterface && x.Name.EndsWith("Service"))
					.Select(x => 
					    new ServiceRegistration { 
					        Service = x, 
					        Interface = x.GetInterfaces().FirstOrDefault(i => serviceIntefaces.Contains(i)) 
					    });
            
	    // Find all Service that is assignable from IService and register them
            foreach(var serviceClass in serviceClasses.Where(x => x.Interface != null))
            {
                builder.RegisterType(serviceClass.Service).As(serviceClass.Interface);
            }

            // Autowire Property Injection for controllers (in case they aren't using constructor injection)
            var allControllers = Assembly.GetExecutingAssembly().GetTypes()
					.Where(type => typeof(BaseController).IsAssignableFrom(type));
            foreach (var controller in allControllers)
            {
                builder.RegisterType(controller).PropertiesAutowired();
            }

            // Resolves the dependencies
            var container = builder.Build();
            DependencyResolver.SetResolver(new AutofacDependencyResolver(container));

            var allRegs = container.ComponentRegistry.Registrations;
        }
    }

    public class ServiceRegistration
    {
        public Type Service { get; set; }
        public Type Interface { get; set; }
    }

    public class CMSRegistrationSource : IRegistrationSource
    {
        /// <summary>
        /// Gets whether the registrations provided by this source are 1:1 adapters on top of other components (I.e. like Meta, Func or Owned.)
        /// </summary>
        public bool IsAdapterForIndividualComponents => false;

        /// <summary>
        /// Retrieves registrations for an unregistered service, to be used by the container.
        /// </summary>
        /// <param name="service">The service that was requested.</param>
        /// <param name="registrationAccessor">A function that will return existing registrations for a service.</param>
        public IEnumerable<IComponentRegistration> RegistrationsFor(Service service, Func<Service, IEnumerable<IComponentRegistration>> registrationAccessor)
        {
            // Checks whether the container already contains an existing registration for the requested service
            if (registrationAccessor(service).Any())
            {
                return Enumerable.Empty<IComponentRegistration>();
            }

            // Checks that the requested service carries valid type information
            var swt = service as IServiceWithType;
            if (swt == null)
            {
                return Enumerable.Empty<IComponentRegistration>();
            }

            // Gets an instance of the requested service using the CMS.Core API
            object instance = null;
            if (CMS.Core.Service.IsRegistered(swt.ServiceType))
            {
                instance = CMS.Core.Service.Resolve(swt.ServiceType);
            }

            if (instance == null)
            {
                return Enumerable.Empty<IComponentRegistration>();
            }

            // Registers the service instance in the container
            return new[] { RegistrationBuilder.ForDelegate(swt.ServiceType, (c, p) => instance).CreateRegistration() };
        }
    }
}

Now let’s invoke the config class to register those Services at startup:

Global.asax.cs

namespace YourNamespace
{
    public class MvcApplication : HttpApplication
    {
        protected void Application_Start()
        {
            // Register services both CMS and custom
            DependencyInjectionConfig.RegisterDependencies();

	    /// ... all the other things
        }
    }
}

The above will do two very key things:

• Register all Kentico Services for injection
• Register all custom Services we create
  • This keys specficially on naming conventions, if you have a Service end it with the word Service. ExampleService will implement IExampleService (below).

Doing this on Application_Start will take a little time on initial load, but no time during runtime.

Alright, let’s go over an example of a service. Below will be a service Interface with an Implementation:

IExampleService.cs

namespace YourNamespace.Services.Interfaces
{
    public interface IExampleService
    {
        ITreeNode GetCurrentNode();
        IEnumerable<SubNav> GetSubNavFromAliasPath(string nodeAliasPath, CultureInfo cultureInfo, ISiteInfo siteInfo = null);
    }
}

ExampleService.cs

namespace YourNamespace.Services.Implementation
{
    /// <summary>
    /// This class is an example of how to use Dependency Injection to get common classes and services without having instantiating them on your own.
    /// Some high level reasons that may prove useful: reusability/replaceability (forces modular development)
    /// and testability (you can mock interfaces in order to properly test your written code)
    /// </summary>
    public class ExampleService : IExampleService
    {
        // Below are Kentico classes that are coded to an intercace and can be injected via Constructor Injection
        public ISiteService _siteService;
        public IEventLogService _eventLogService;
        public IHttpContextAccessor _httpContextAccessor;

        /// <summary>
        /// Any parameters in the signature should be injected via constructor injection, 
        /// if invoking this service direclty you will need to instantiate your own
        /// </summary>
        /// <param name="siteService"></param>
        /// <param name="eventLogService"></param>
        /// <param name="httpContextAccessor"></param>
        public ExampleService(ISiteService siteService, IEventLogService eventLogService, IHttpContextAccessor httpContextAccessor)
        {
            _siteService = siteService;
            _eventLogService = eventLogService;
            _httpContextAccessor = httpContextAccessor;
        }

        /// <summary>
        /// Simply gets the current node using the absolute path of the HttpContext.
        /// </summary>
        /// <param name="context"></param>
        /// <returns></returns>
        public ITreeNode GetCurrentNode()
        {
	    /// Using the injected _httpContextAccessor to get the request path
            var absolutePath = _httpContextAccessor.HttpContext.Request.Url.AbsolutePath;
            ITreeNode FoundNode = DocumentQueryHelper.GetNodeByAliasPath(absolutePath);
            return FoundNode;
        }

        /// <summary>
        /// Gets a list of `SubNav` items under the `Node` passed in.
        /// </summary>
        /// <param name="node"></param>
        /// <returns></returns>
        public IEnumerable<SubNav> GetSubNavFromAliasPath(string nodeAliasPath, CultureInfo cultureInfo = null, ISiteInfo siteInfo = null)
        {
            if (siteInfo == null)
            {
                // If site is not provided, get the current site from the injected SiteService
		// and log (may be overkill but using it as an example)
                siteInfo = _siteService.CurrentSite;
                _eventLogService.LogEvent("GetSubNavFromAliasPath", "ExampleService", "GET", "Using current site");
            }
            else
            {
                _eventLogService.LogEvent("GetSubNavFromAliasPath", "ExampleService", "GET", "Using passed in site");
            }

            if(cultureInfo == null)
            {
                cultureInfo = LocalizationContext.GetCurrentCulture();
                _eventLogService.LogEvent("GetSubNavFromAliasPath", "ExampleService", "GET", "Using current culture");
            }
            else
            {
                _eventLogService.LogEvent("GetSubNavFromAliasPath", "ExampleService", "GET", "Using passed in culture");
            }

            var subnavList = new List<SubNav>();
            try
            {
                foreach (ITreeNode Node in DocumentQueryHelper.RepeaterQuery(
                Path: nodeAliasPath + "/%",
                CultureCode: cultureInfo.CultureCode,
                SiteName: siteInfo.SiteName,
                ClassNames: "CMS.MenuItem",
                OrderBy: "NodeLevel, NodeOrder",
                Columns: "MenuItemName,NodeAliasPath"
                ))
                {
                    subnavList.Add(new SubNav()
                    {
                        LinkText = Node.GetValue("MenuItemName").ToString(),
                        // You have to decide what your URL will be, for us our URLs = NodeAliasPath
                        LinkUrl = Node.NodeAliasPath
                    });
                }
            }
            catch (Exception ex)
            {
                _eventLogService.LogException("ExampleService", "GET", ex);
            }
            return subnavList;
        }
    }
}

Above is a trimmed down (for the sake of demonstration) version of what you will see in here. Using the Service naming convention, we can pick it up in the DependencyInjection.RegisterDependencies() (line 15) method and register it with its similarly named Interface. I generally use this approach as a form of lazy-registering-by-naming to get off the ground fast within development, but when it comes to replace an implementation I usually will create a new Service and manually register it until it is fully fleshed out and then potentially rename it so it continues to get picked up by this method.

Now, back to the ExampleService, this service leverages the following Kentico Services:

• CMS.Base.ISiteService to get the current site info
• CMS.Core.IEventLogService to allow us to log events
• CMS.Base.IHttpContextAccessor to access the http context

The ExampleService itself illustrates using Constructor Injection where already instantiated services are passed in thru the constructor. This ExampleService is ultimately used in a controller, ExampleController:

ExampleController.cs

namespace YourNamespace.Controllers.Examples
{
    public class ExamplesController : BaseController
    {
        public IExampleService _exampleService;
        public ExamplesController(IExampleService exampleService)
        {
            // Use constructor injection to get a handle on our ExampleService
            _exampleService = exampleService;
        }

        // GET: Examples
        public ActionResult Index()
        {
            return View();
        }


        /// <summary>
        /// This Repeater "Webpart" Relies on just a path that would be provided through the View's context.  Does not rely on passing
        /// the ViewBag like the NavigationByContext, but does then require the calling View to provide the properties, and if ever more
        /// properties are needed, would need to adjust both Controller and View alike.
        /// </summary>
        /// <returns></returns>
        public ActionResult NavigationByPath(string Path, string Culture, string SiteName)
        {
            // Build the actual Partial View's model from the data provided by the parent View
            ExampleMVCWebPartsSubNavs Model = new ExampleMVCWebPartsSubNavs();
            // Get the Sub Nav Items from the ExampleService
            Model.SubNavigation = _exampleService.GetSubNavFromAliasPath(Path, CultureInfoProvider.GetCultureInfo(Culture));
            return View("Navigation", Model);
        }
    }
}

So at this point, we have a Controller with an injected dependency, IExampleService, that is registered at startup and that class itself uses some injected Kentico services. So one thing that may be apparent, this example is not perfect as some of the dependencies like DocumentQueryHelper are both static and not injected, but that is something we hope to have ironed out in the future. The only thing left that I would love to illstrate and, in my opinion, is one of the biggest benefits to leveraging DI is testing (but that will have to be for a later blog post!)

And like I mentioned before, this is all publicly accessible and brought to you from the beautiful Kentico minds at Heartland Business Sytems.

I am hoping this post helps you put some of the pieces together on how to use Dependency Injection in your next Kentico project and reap the benefits in all their glory!

</message>