Tag: XM Cloud

Sitecore Webhook – Authorise event processing app with Auth0 by Okta

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

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

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

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-