Understanding Macro Identities in Kentico 11


Macros have long been a friend to any Kentico developer. Whether it’s one of many built-in methods or a custom one, these little code blocks can be powerhouses when it comes to developing your applications. One of their best aspects is their ability to be contextual, based on the user that inserted it.  While this very powerful, using macros between instances often resulted in broken or invalid macros, when it came to security. In Kentico 11, we’ve solved that challenge with macro identities.

If you’re a Kentico developer and you want to show dynamic content, chances are you’ve used macros. These expressions allow you to evaluate data and convert it to text to display. This may be the current time, the user’s location, or any other type of information within the system. Kentico comes packed with many macros out of the box, but the seasoned developer surely has made a few themselves over time. Based on K#, creating macros is an easy process and one that bring some powerful capabilities to your applications.

As developers have used macros, they’ve often run into issues when it came to moving data between environments. Because macro security is contextual, the user must exist in all installations in order for the system to resolve them properly. Because of this, companies have developed various workarounds to get handle the issue. Some synced all users to all installations. Others simply used the Global Administrator account for all macros. Luckily, in te Kentico 11 we’ve included a great new feature to handle this right out of the box: Macro Identities.

The problem

Before I get into the solution, let me talk a little more about the issue. Unless you’ve used macros heavily and realized on contextual security, you may not even know there was anything missing in the platform. Let’s take the following scenario:

  • DEV contains DevUser1
  • PROD does not have DevUser1
  • DevUser1 inserts a macro into some content element on DEV
  • The system signs macro with DevUser1 credentials / username
  • The content is moved to from DEV to PROD via Staging
  • The macro security/signature check fails to resolve due to the DevUser1 account not existing on PROD

Because the macro was inserted on DEV using the DevUser1 account, the signature will be specific to that user. On DEV, the macro will resolve correctly, because the system can locate DevUser1 and resolve the value.

When the content is moved to PROD, the macros fail. This is because the DevUser1 account doesn’t exist in that environment, however, the macro contains the signature for the account. This can cause all sorts of issue within the site and the reason we came up macro identities.

The Solution

Now that you understand the issue, let give you a little more information on the macro identities. Because each macro signature contains an identifier for the user that entered it, updating this value to a universally available value is key. In Kentico 11, you can create a new macro identity that is associated with an effective user. This is the user the system will use to evaluate the security of the macro. By choosing an account that exists in all environments you can ensure the macro evaluate will always have an account to evaluate.

New Identity

What’s powerful about the new identities is that they can be assigned to multiple users. This means you can have a single identity for all your developers, with 1 common user account between your environments. This means no more failed macro evaluations and a lot less calls to your when content is published.

Here is an updated scenario, using macro identities.

  • DEV contains DEVUser1
  • PROD does not contain DEVUser1
  • DEV and PROD contain CONTENTUser1
  • Admin creates a new macro identity (IDENTIY1), with CONTENTUser1 as the “effective” user
  • Admin assigns the IDENTIY1 identity to DEVUser1
  • DEVUser1 inserts a macro in a content element
  • The macro is signed using the IDENTIY1 identity
  • The content is moved from DEV to PROD via Staging
  • The macro is successful resolved because IDENTIY1 exists in both environments

In this scenario, everything works great because the new macro identity allows the macro to be resolved in both environments. Even if the user accounts are different between DEV and PROD, the macro will still resolve. This allows you to keep your DEV and PROD environments separate and secure, while keeping your macros working smoothly.


Moving forward

With every new version of Kentico, we release improvements to make developers’ lives better. For version 11, we recognized that the existing macro system could cause issues if accounts were consisted across environments. With macro identities, we feel we have solved all these issues and provided you a great solution for your applications. We hope you love using and thanks for the great feedback!

Learn more

Share this article on   LinkedIn

Bryan Soltis

Hello. I am a Technical Evangelist here at Kentico and will be helping the technical community by providing guidance and best practices for all areas of the product. I might also do some karaoke. We'll see how the night goes...