Page 2 of 19

Secure Sitecore Webhooks using Microsoft Azure AD B2C

April 20, 2024 /

Few months back I was trying to Authorize Sietcore Webhooks using Microsoft Actice Directory B2C and found issue that it wasn’t working.

After creating a support ticket, Sitecore logged this as a bug.

This was resolved and release on 20th Feb 2024.

This blog helps on how to configure MS AD B2C and configure in Sitecore as Client Credential grant to generate an access token so the Event receiver can authorize and process the request.

Note- text highlighted in red is required later to configure in Sitecore.

Reference-

https://doc.sitecore.com/xp/en/developers/103/sitecore-experience-manager/webhook-authentication-types.html

https://developers.sitecore.com/changelog/xm-cloud/1.5.69-base-image-update%3a-resolved-issues

Pre-requisite

You should have your Azure AD B2c tenant. See this link on how to set this – Tutorial – Create an Azure Active Directory B2C tenant | Microsoft Learn

Once configured you see the options to register your app.

Before registering app note down the highlighted. This should be available as the part of Endpoint-

Microsoft Entra ID OpenID Connect metadata document.

This is Authority URL in Sitecore Webhook.

Step 1 – Register App

Click on New registration

Provide the App registration name and selected supported account types. In this case I have given name – SCXMCWebhook and selected “Accounts in this organizational directory only (SC XM Org only – Single tenant)“

Register App and it should show the registered app-

Application (Client) ID – Required to configure in Sitecore

It should also list your newly created app-

Step 2 – Add an Application URI

Click on Application ID URI “Add”link and then “Add a scope”

This should create a URI –

Step 3 – Add a scope

Now create a scope “Add a scope”. Enter scope name, admin consent and description. Ensure you enable the scope.

A new scope isadded . Copy the scope as highlighted –

required in Sitecore Auth Scope field

Step 4 – Create Secrets

Copy the secret value. This value won’t be shown again. This is required to configure in webhook Client Secret field

Navigate to Overview tab and you should see all the configured details.

Step 5 – Create a Client Credential Grant Authorization in Sitecore

Sitecore Client CredentialMicrosoft AD B2C
Authority URL Microsoft Entra ID OpenID Connect
metadata document. (Check Endpoints)
Client IDApplication (client) ID
(Check Overview tab)
Client SecretClient Secret Value
(Check Certificates & Secrets tab)
Scope
(Append /.default)		Application ID URI
(Check Overview tab)
Header Prefix
(Bearer)
Additional Endpoint Base Addresses
(See Semicolon seperated values below)		Directory (tenant) ID
(Part of the url- Check Overview tab)
e.g.:- 10d**************1b4c

Additional Endpoint Base Addresses–

https://login.microsoftonline.com/10d**************1b4c/discovery/v2.0/keys
https://login.microsoftonline.com/110d**************1b4c/oauth2/v2.0/token
https://graph.microsoft.com/oidc/userinfo
https://login.microsoftonline.com/10d**************1b4c/oauth2/v2.0/authorize
https://login.microsoftonline.com/10d**************1b4c/oauth2/v2.0/devicecode
https://login.microsoftonline.com/10d**************1b4c/oauth2/v2.0/logout
https://login.microsoftonline.com/10d**************1b4c/kerberos

Client Credential Grant Authorization Item should look like this-

Please note Additional Endpoint Base Address are Semicolon seperated.

Step 6 – Create a Webhook Handler in Sitecore

Create Webhook handler at this location- /sitecore/system/Webhooks/

Provide the Description, Select the events the webhook should trigger, Add any rules as per your requirements, Ensure to Enable the Webhook, provide the Url the webhook should send the item data, select the newly created Authorization and Selrialization type (JSON).

Step 7 – Save an Item in Sitecore

Update an Item, in this case I updated Home item

You should see the webhook sends the request to defined Url with Access Token, as highlighted below-

Hope this helps to cionfigure MS AD B2C in your Sitecore instance

More reads-

Configure Sitecore XM Cloud webhook for Authorization using Auth0 by Okta
Sitecore Webhook – Authorise event processing app with Auth0 by Okta
Automation with Sitecore XM Cloud Webhooks and Zapier

Loading

XM Cloud Dev Error: Hydration failed – while using XMC with Nextjs

March 20, 2024 /

Recently, I started receiving error-

Unhandled Runtime Error

Error: Hydration failed because the initial UI does not match what was rendered on the server.

This error was specifically while using RichText field.

Resolution-

Hyderation is when React converts the pre-rendered HTML from the server into fullly interactive application by attaching event handlers.

The common casue of this issue is incorrect nesting of HTML tags.

RichText is wrapped in div tag and received this error when the RichText was wrapped in <p> tag

Example where React throws error-

Incorrect way of wrapping RichText-
<p className="page-desc text-white mb-0"> 
   <RichText field={props.fields.Description} />
</p>

Remove the <p> tag or wrap RichText in <div> tag

Correct way-
<RichText className="page-desc text-white mb-0" field={props.fields.Description} />

Remvoing <p> might removing spacing between fields/components, this needs to be adjusted using CSS.

Reference-

https://nextjs.org/docs/messages/react-hydration-error

Loading

XM Cloud local environment – Setup local development instance

February 22, 2024 /

This blog post will guide you through the local environment setup for XM Cloud. You may refer this documentation to do this your own way. Althoug the documentation covers most of the setup, this blog post provides visual on the steps and errors with the resolution.

https://doc.sitecore.com/xmc/en/developers/xm-cloud/walkthrough–setting-up-your-full-stack-xm-cloud-local-development-environment.html

Once the Foundation Head from Sitecore Labs is forked s(se more details here) clone the copy to the local machine for creating a local instance required for XM Cloud development.

Pre-requisite –

You can find the pre-requisite in this documentation. Ensure your machine has this before setting the local development environment. Just noting down here-

https://doc.sitecore.com/xmc/en/developers/xm-cloud/walkthrough–setting-up-your-full-stack-xm-cloud-local-development-environment.html

Also make sure you are using Docker v.2, as explained here.

Access to XM Cloud – This blog post assumes you have admin access to XM Cloud where you should be able to craete/update/delete projects environments and deployment in your organisation.

I have this ready on my machine.

1. Clone the forked Foundation head repo.

I named the folder same as the repo on my local machine i.e. xmcloud-foundation-head. the same will be refered thoruhg this post.

Will see the following folder structure after cloned.

I use Visual Studio Code to make any environment related changes. You may use either Visual Studio 2022 or your choice of editor.

2. Open the .env at the root folder and you will see REPORTING_API_KEY, TELERIK_ENCRYPTION_KEY etc. empty.

3. Start the containers.

Prepare the environment

Before doing so make sure you stop the IIS and check if the port 443 (IIS Website) and 8984 (Solr service)is not used and the docker is running in Windows Containers mode. If not switch to Windows cotainers.

iisreset /stop

Get-Process -Id (Get-NetTCPConnection -LocalPort 443).OwningProcess
Get-Process -Id (Get-NetTCPConnection -LocalPort 8984).OwningProcess

Stop-Service -Name "<the name of your service>"

Copy the license file to c:\license folder. If you wish to have this in other folder you also have to change the HOST_LICENSE_FOLDER in .env(root folder) with the path where the license resides.

To prepare the Sitecore container environment, run the script init.ps1 from the root directory of the project along with the license path and desired passowrd for your instance. this form the root folder from the downloaded the repo.

.\init.ps1 -InitEnv -LicenseXmlPath "C:\license\license.xml" -AdminPassword "b"

Required certificates added.

You may also noticed .env in root folder have added values in REPORTING_API_KEY, TELERIK_ENCRYPTION_KEY and MEDIA_REQUEST_PROTECTION_SHARED_SECRET, which was earlier empty.

Download the Sitecore Docker images, install and configure the containers and client application

Run the up.ps1 to download and install containers and client application

.\up.ps1

This is should download the images and start the containers

Once the containers are started, it should ask to confirm to login to Sitecore with the Device confirmation code. Confirm if this matches. It should also ask to login to XM Cloud isntance and confirm.

One this is done indexes will be rebuilt and the Sitecore instance should be up and running.

Also notice that any items in this case none is pushed to Sitecore instance and an api key is genereated with the name xmcloudpreview-

You may also notice a jss editing secret and SITECORE_API_KEY_xmcloudpreview are updated in .env fiel in root folder along with the Sitecore Admin password which was set whilst initialising the environment.

Your local instance should now be up and running-

https://xmcloudcm.localhost/sitecore/

The highlighted key shoulld match the key while spinning up the containers.

Taking down the containers

To take down the containers run the down.ps1 from the root folder.

.\down.ps1

Errors

Invoke-RestMethod : Unable to connect to the remote server

This should be ideally staright forward but if you see any issues whilst getting CM instance up and runing. take down the container with down.ps1 command and delete any docker network.

docker network prune

Hope this helps to setup local Sitecore instance for XM Cloud development.

Loading

Automation with Sitecore XM Cloud Webhooks and Zapier

February 2, 2024 /

With Zapier you can inspect and create customised workflow in munites without wirting any code. Its a good way to automate any actions required once the webhooks in Sitecore are triggered.

In this blog post will quickly create a workflow in Zapier to send mail when a webhook event is trigerred.

Will take a scenario when a Home page is updated, so that the concern team knows about this change.

This is not a fully customised solution but you can extend this as per your requirements.

Create a Zapier account

Create a Zapier account if you don’t have already. There is free subscription available to try out.

Login to Zapier and create a new Zap

Configure a trigger- Select Webhook by Zappier

When a new zap is created select a Catch Hook event in App & Event section

In the test section it should provide the URL its listening to execute any autmation if applicable.

Test the trigger by copying the s URL and setup the same in your Webhokk Handler in Sitecore XM CLoud or local instance. See this blog post on how to create a webhook handler.

Update content in Home page and Save. This should triggere the webhook and call the Zapier endpoint configured in handler.

Test trigger and should see the request available to this endpoint-

Continue with Selected Record if you are happy with the request-

Apply Filter

We want to send mail only when Home page is changed, so lets apply filter

Configure the filter

Add the condition

Further action will be taken only if Item name is Home. This just an example you can select the list of action available.

Continue and select next action and in this case I selected to send a mail to Gmail

Select the event “Send Mail”

Setup your account.

Setup the action to whom the mail should be sent and other information required for the mail

Continue and Test the Step

Now you should have the Zap configured-

Publish the Zap

Change the name of the Zap and should be available in Dashboard-

Change a home page content in Sitecore XM Cloud-

In the Zap runs you should be able to see a mail is triggered-

Thats it. This took me few minutes to configure and test the mail for a simple sceanrio.

Zapier gives you full flexibility to configure the triggers without writing any code based on the conditions to tak action when a Webhook event is triggered in Sitecore XM Cloud.

Hope this helps.

Loading

Sitecore Webhook – Authorise event processing app with Auth0 by Okta

January 15, 2024 /

In the previous posts we saw how to setup the local environment or XM Cloud to debug Webhook handler event processing app i.e. web api using ngrok in this blog post and also checked how to configure the authorization using Auth0 by OKTA in this blog post using OAuth2ClientCredentialsGrant authorization.

Continuation to this we will now extend the Web Api to authorize the endpoint called from the Sitecore Webhook handler.

We already configured Auth0 to have API and Machine-to-Machine application we will configure this in Web API and setup the authorization.

The authorization in Web API will be done to check of the request cam from the valid domain i.e. dev-your_dev_id.uk.auth0.com and valid audience i.e. https://sc-xmcloud which should be part of the token.

Lets configure Web API .env file. Create a .env file and add the following-

CLIENT_ORIGIN_URL can aslo be your XM Cloud instance.

"CLIENT_ORIGIN_URL": "https://xmcloudcmsdfsdfsd.localhost",
"AUTH0_AUDIENCE": "https://hello-world.example.com",
"AUTH0_DOMAIN": "dev-your_dev_id.uk.auth0.com"

Setup the authentication –

    public static void AddAppAuth(this IServiceCollection services, IConfiguration configuration)
    {
        services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
            .AddJwtBearer(options =>
            {
                var audience =
                    configuration.GetValue<string>("AUTH0_AUDIENCE");

                options.Authority =
                    $"https://{configuration.GetValue<string>("AUTH0_DOMAIN")}/";
                options.Audience = audience;
                options.TokenValidationParameters = new TokenValidationParameters
                {
                    ValidateAudience = true,
                    ValidateIssuerSigningKey = true
                };
            });
    }

Create a builder to add Authentication service- 

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddAppAuth(builder.Configuration);

Decorate the controller wiht Authorize attribute-

The endpoint for local is – https://localhost:7024/api/Item/handler

Setup ngrok to listen to this endpoint

ngrok http --host-header="localhost:7024" https://localhost:7024

ngrok listening now listening on this URL-

https://8a18b6e7e0c1.ngrok.app

Configure the ngrok endpoint in Sitecore Webhook handler

OAuth2ClientCredentialsGrant authorization looks like this-

Webhook Event

Webhook will fire when the Home item or its descendants are saved

Once saved local instance should Authorize and start executing the action method

We can also see the token and the request successfully processed.

Negative testing-

If the audience and the domain doesn’t match should not execute the action method.

I changed the same in .env file.

CLIENT_ORIGIN_URL=https://xmcloudcmxmcloudcm.localhost
AUTH0_AUDIENCE=https://sc-xmcloud-fake-audience
AUTH0_DOMAIN=dev-fakedomain.uk.auth0.com

Sitecore logs also show the request was failed and this due to incorrect domain and audience configured in Web Api-

3896 16:00:20 ERROR Webhooks: Request is not successfull https://8a18b6e7e0c1.ngrok.app/api/Item/handler. Response code was Unauthorized

ngrok helps debug the event processing app to check the authorization.

Hope this helps.

Loading

Configure Sitecore XM Cloud webhook for Authorization using Auth0 by Okta

January 2, 2024 /

In previous blog post we saw how to create a Webhook and debug, inspect and test the Webhook handler using ngrok.

Continuation to the previous blog post lets see how to configure the Webhook to use Client Credential grant and secure the Webhook handler in this blog post with Auth0 by Okta.

Register and Login to Auth0

I used free (development) plan to register to Auth0 if you don’t have the account already. This should create a dev id based on the region you selected and should look like this – dev-your_dev_id

https://auth0.com/pricing

Create a API

Navigate to Applications ==> APIs and Create a new API

Provide the name and identifier-

Once created note down the Identifier-

You will also notice that a new Machine To Machine (M2M) Application is created and is mapped and authorized in this API-

Navigate to Applications ==> Applications to see the M2M application-

Note the Domain, Client ID and Client Secret in this application, as this will be required when configuring the Autjorization is Sitecore.

Generate token using postman

Lets test the API and application ocnfigured correctly by generating token using postman-

You will following from above-

Domain Name- dev-your_dev_id.uk.auth0.com

client_id – cC6kPo4AJvY2spdWqZQVuEOjWTMfUZIo

client_secret- wXmuRusYhjJOF12RljeJ5WiJDL6vXnUKuUJO6961CeKG6xafRJpEuBZh_FAbl617

identifier/audience – https://sc-xmcloud

Post request to generate token – https://dev-your_dev_id.uk.auth0.com/oauth/token

Create a Authorization in XM CLoud-

Craee a new OAuth2ClientCredentialsGrant in Authorization folder. This should be available in following path in Sitecore-

/sitecore/system/Settings/Webhooks/Authorizations

Setup the OAuth2ClientCredentialsGrant –

Setup the Authority URL, Client ID, Client Secret, Header Prefix and OptionalParameter as follows- This values we noted above whilst creating a API and Application in Auth0.

Setup Webhook Handler

Create a new Webhook handler and provide the newly created authorization –

For testing purpose I have set the

Event – item_saved, Rule – When the Home Item or its descendants are changed

Url – https://webhook.site/a4624c9e-7dda……

Webhook.site should listen to any calls from Sitecore for testing purpose. This can be your Webhook handler app.

Authorization – Select the newly created authorization to Auth0 which create a token

Serialization Type- JSON

Fire a webhook

Save a home or its descendants to fire a webhook

On save it should fire a webhook which can be seen in webhook.site which should also pass the newly created token.

We can see the token was successfully created and a webhook was fired on saving a Home item as configured in Auntorization and Webhook Handler.

Errors-

If the request to Auth0 fails you should be able to see the same in logs- something like this due to configuration-

4016 12:37:00 INFO  AUDIT (sitecore\sandeep@): Save item: master:/sitecore/content/scxmcloud/sxastarter/Home, language: en, version: 1, id: {0B5C4B64-2A85-4F98-B928-0E0B40C68AEA}
1928 12:37:01 ERROR Webhooks: Token request failed with error: Unauthorized

I have tried this in my local instance but the same can also be done in XM Cloud.

Next we will create a Web Api which should be able to validate the token and executes any custom implementation. This will be in next blog.

Hope this helps.

Loading

Debug, inspect, test and run the request triggered by XM Cloud Webhook using ngrok

December 22, 2023 /

Sitecore Webhooks allows to receive real-time notification about events to the web api that can handle these requests.

In this blog post will see how to debug such handlers in local environment, events triggered by XM Cloud or from the local instance using ngrok.

What is ngrok?

ngrok allows to connect external netwroks in a consistent, secure and repeatable manner without changing any network configurations.

Pre-requisite-

Sitecore Instance-

Either have a local Sitecore instance or XM Cloud instance. See how to setup local XM Cloud instance

Create a Webhook Handler(Web Api)

For this blog post I have created a simple Web Api with a endpoint /api/item/handler which receives POST requests with a Item payload and just return OK or Badrequest response.

We are going to create a Webhook with item:saved event in Sitecore. 

using Microsoft.AspNetCore.Mvc;
using Sitecore.Webhook.Handler.Models;

namespace Sitecore.Webhook.Handler.Controllers;

[ApiController]
[Route("api/[controller]")]
public class ItemController : Controller
{
    [HttpPost("handler")]
    public async Task<IActionResult> ItemHandler(ItemPayload? payLoad, 
        CancellationToken cancellationToken)
    {
        if (payLoad == null)
        {
            return BadRequest();
        }

        // Process the item handler
        return Ok();
    }
}

When I run this from VS the endpoint listens on the port 7024 for me.

Host Name:- https://localhost:7024/

Endpoint: /api/item/handler

Install ngrok on dev machine

Use choclatey to install ngrok on local machine

choco install ngrok

Check the ngrok once installed 

ngrok -v

IMP– Antivirus might block executing the ngrok. For me I had to turn off the real time scan. Do this at your own risk based on your antivirus software this might be different.

Execute ngrok http command to listen to the api endpoint-

ngrok http --host-header="localhost:7024" https://localhost:7024

In this example https://1a319cf7d867.ngrok.app should forward request’s to https://localhost:7024 where the Web Api is running on my local machine.

Also note the Web Interface – http://127.0.0.1:4040/

Create a Webhook Handler

Navigate to /sitecore/system/Webhooks and create a webhook handler. In this case will create a item:saved handler.

In the newly created handler select the event the webhook should trigger and call the endpoint created by nrgok (i.e. web api)

Setup the rule – “where the item is the Home item or onle of its descendants”

Means Home or any of its child items when saved this event will be triggered.

Also setup the Url the webhook should call when this event fires.

IMP – Ensure the handler is enabled or it won’t fire the event.

Save the Home or any of its child to fire the event

I changed a field in Home item and Saved the item-

Ensure your Web Api solution is running in debug mode.

And now you should be able to debug, inspect and test the handler. This was done in local Sitecore instance but can also be done in XM Cloud.

ngrok helps to forward the requests to the localy hosted web api running in debug mode.

Now you can handle what should happen on item:saved event.

XM Cloud

I did the same process in XM Cloud-

Updated the Home item and Saved. Note the item id

The event is fired and web api in my local machine is called-

Also the ngrok also shows the calls it is listening.

Web interface should also show the request and payload details-

Hope this helps debuging your Webhook requests fired from Sitecore local or XM Cloud.

If you want to see the webhook payload and perform further actions, like sending mails etc there are online tools availabl e-

https://webhook.site/

https://zapier.com/

https://hookdeck.com/

https://ifttt.com/

Hope this helps.

Loading

XM Cloud local environment – Fork Foundation template

December 16, 2023 /

This is first part for setting up the XM Cloud local environment. As a part of this we will first fork the foundation template from reporsitory. This will help you setup sitecore local instance and head your own copy without affecting the Foundation head from Sitecore labs. Note this repo keeps updating and the steps below may differ after any updates.

This post refers following documentation is you want to do your own way-

https://doc.sitecore.com/xmc/en/developers/xm-cloud/walkthrough–setting-up-your-full-stack-xm-cloud-local-development-environment.html

Fork the XM Cloud Foundation Template source for initial deployment from following git repo-

To fork the same you need to have first have git account.

Follow the steps to fork the source code- https://github.com/sitecorelabs/xmcloud-foundation-head

Create a new fork –

Provide a valid repo name and create fork-

You should now a have a main branch forked in your account-

Sitecore Send Custom Automation – Email when user subscribes to specific mailing list

November 8, 2023 /

If you want to send welcome email to the user subscribed to the specific mailing list in this example to a Newsletter, you can do so using Sitecore Send Automation.

In this case there is no OOTB automation available. Will crate a custom automation instead

To see how to setup a Subscribe abd Unsubscribe using javascript see this blog

Setting up Custom Autmation to Thanks user for subscribing to the Newsletter

Navigate to Automation and New –> Custom automation

Setting up Automation for welcome email-

This is avaiable in automation recipe-

Navigate to Automation and New –> From recipe

Update title and description of automation-

Select the trigger-

Choose the List Engagement option – When someone subscribes to a specific list

In this case I am choosing the Newsletter Email List- created in my other blog

This should update the automation-

Next add the condition or control step

For this example will choose – Wait a specific time interval-

So after the user subscribes to Newsletter the wokflow will wait for 1 minute to perform further action.

Select Send mail campaign action-

Fill in the appropriate fields and create action-

Automation Worflow should look like this-

Imp- do not forget to activate the automation workflow.

On subscribing to newsletter-

You should be able to see the user added to the Newsletter mailing list-

After a minute you should be able to see custom automation is triggered-

Result- Email been sent after subscription-

You can also choose the exisitng recipe but this has the trigger to send mail if the user subscribes to any list.

Choose Welcome email sequence option-

This should ne now available in Automation Workflows in an Incomplet state-

Should show up with the option to setup the Automation Workflow-

Might see mulitple such steps- update as per your requirements

Click on the Trigger – When someone subscribes to any list as highlighted

Loading

Siecore Send – Setup re-direction to a custom webpage after unsubscription

November 4, 2023 /

To setup subscription and un-subscription see this blog

In this case I am setting up the Newsletter mailing list if user un-subscribed redirects to the custom page.

Navigate to the mailing list to setup the unsubscription redirect page-

Select Set your settings option

Enter the Redirect page URL –

When the user unsubscribes to the email list, it will be re-drected to your custom page.

When the user unsubscribes to the mailing list-

Will be redirected to the configured custom page instead of standard Sitecore page.

Loading