Zendesk Authentication Using JWT And Azure Active Directory

It’s been a while since my last post, so this is why this post will be a bit longer than usual, I hope that it can help you.

Today we’re going to learn how to build a Zendesk SSO (Single Sign-On) authentication using JWT (JSON Web Token) and AzureAD (Azure Active Directory) as an Identity Provider.

In this post, we will go through several steps, which are,

Zendesk sign up and configuration,
Azure Active Directory configuration,
ASP.NET Core 2.0 application.

Requirements

Microsoft Azure account (you can start your free trial from here.

Zendesk account (we’re going to understand how to create one).

Visual Studio 2017 (Community edition is free, click here to download it.

Zendesk signup

Zendesk is a customer service platform. It’s designed for companies that want to create customer relationships that are more meaningful, personal, and productive.

Zendesk provides a free trial to test all the product functionalities. To start your free trial, you should go to this link.

Rather than registering using your email address and your password, Zendesk provides other authentication options. You can use your Microsoft credentials or Google credentials to authenticate.

After choosing your preferred method, you will be asked to choose your subdomain (SUBSOMAIN.zendesk.com).

And that’s it, congratulations -- you have a Zendesk free account available for the next 30 days.

PS

You have to verify your account by clicking on the link sent to your email address.

Zendesk JWT configuration

After creating a Zendesk account, now we have to configure it in order to be able to authenticate using JWT.

By following this steps, we’ll be able to authenticate to our Zendesk using JWT authentication mode.

Go to Admin tab
Go to Settings > Security

By default, you will see your preferred authentication mode selected (in my case, I signed up using my Microsoft credentials).

Now, select single sign-on (SOO) , in this section you will find two SSO authentication types, please ignore SAML authentication and choose JWT (JSON Web Token).

We have to fill the login and the sign-out URL(s) but don’t worry we will finish this step later after we configure our Azure Active Directory (Azure AD).

And that’s it for Zendesk configuration.

In order to use Single Sign-On authentication, we have to add a new Zendesk user. Go to Dashboard > People and then add user.

And here, fill in the 3 required fields, but please in the email field choose one of your Azure Active Directory user's username. For example, I’m using this username: [email protected] as an email, and pick Agent as a role.

Now we have to focus on configuring our Azure AD and get it ready to use it as an identity provider.

Microsoft Azure Active Directory configuration

First of all, we have to get an active Microsoft Azure account, if you don’t have one you can easily create a free trial account from here.

After getting an Azure account up and running, we have to go to https://ad.portal.azure.com/ in order to configure our AzureAD. In order to add a user, you can just add an existing Microsoft account by clicking New Guest User. Enter a valid email address, [email protected] in my case, remember to add the same username that you already used as email in the Zendesk account that we created previously.

Now we’re done with Azure Active Directory, let’s jump to how to build the ASP.NET Core 2 application and connect it to Azure AD and Zendesk.

ASP.NET Core 2.0 application

Launch Visual Studio 2017, and go to File > New > Project and choose ASP.NET Core Web Application under Web section.

And then, please choose Web Application (MVC) and change the authentication to Work or School accounts with Cloud – Single Organization option. Before hitting OK, please enter your Active Directory Domain.

Visual Studio will generate a new ASP.NET Core application that supports AD authentication to your Azure AD. You can check the AccountController and the Startup class, you will find that everything related to the authentication process is in place. Run the project and try to authenticate using your Azure AD account.

OK, so one more step to go. Now, we have to connect our application to Zendesk and configure the JWT authentication. In this part, we will need to write some code. Let’s go to the home controller, specifically to the Index action, and change it a bit.

using System;
using System.Collections.Generic;
using System.Diagnostics;
using System.Linq;
using System.Security.Claims;
using System.Threading.Tasks;
using System.Web;
using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.Mvc;
using JWT;
using JWT.Algorithms;
using JWT.Serializers;
using Microsoft.Extensions.Configuration;
namespace ZendeskJWT.Controllers {
[Authorize]
public class HomeController: Controller {
private IConfiguration configuration;
private string SUBDOMAIN => "YOUR_ZENDESK_SUBDOMAIN";
private string SHARED_KEY => "YOUR_ZENDESK_SHARED_KEY";
public IActionResult Index() {
TimeSpan t = (DateTime.UtcNow - new DateTime(1970, 1, 1));
int timestamp = (int) t.TotalSeconds;
var email = HttpContext.User.Claims.Where(c => c.Type == ClaimTypes.Email).Select(c => c.Value).SingleOrDefault();
var payload = new Dictionary < string,
object > () {
{
"alg",
"HS256"
}, {
"typ",
"JWT"
}, {
"iat",
timestamp
}, {
"jti",
Guid.NewGuid().ToString()
}, {
"name",
HttpContext.User.Identity.Name
}, {
"email",
email
}
};
IJwtAlgorithm algorithm = new HMACSHA256Algorithm();
IJsonSerializer serializer = new JsonNetSerializer();
IBase64UrlEncoder urlEncoder = new JwtBase64UrlEncoder();
IJwtEncoder encoder = new JwtEncoder(algorithm, serializer, urlEncoder);
string token = encoder.Encode(payload, SHARED_KEY);
string redirectUrl = "https://" + SUBDOMAIN + ".zendesk.com/access/jwt?jwt=" + token;
string returnTo = HttpContext.Request.Query["return_to"].ToString();
if (returnTo != null) {
redirectUrl += "&return_to=" + HttpUtility.UrlEncode(returnTo);
}
return Redirect(redirectUrl);
}
public IActionResult Error() {
return View(new ErrorViewModel {
RequestId = Activity.Current ? .Id ? ? HttpContext.TraceIdentifier
});
}
}
}

view raw
Zendesk JWT hosted with by GitHub

You can get your ZENDESK_SUBDOMAIN and ZENDESK_SHARED_KEY from the Zendesk configuration, the security section. Please make sure to install the JWT NuGet package by taping

Install-Package JWT -Version 4.0.0

in the NuGet package manager console.

Let me explain what this piece of code does.

var email = HttpContext.User.Claims.Where(c => c.Type == ClaimTypes.Email).Select(c => c.Value).SingleOrDefault();

Here we get the current 'authenticated user’ email address from the Identity Claims object.

var payload = new Dictionary < string,
object > () {
{
"alg",
"HS256"
}, {
"typ",
"JWT"
}, {
"iat",
timestamp
}, {
"jti",
Guid.NewGuid().ToString()
}, {
"name",
HttpContext.User.Identity.Name
}, {
"email",
email
}
};

We are preparing our payload which is the data that we should send to Zendesk in order to authenticate our user, which is an Azure AD user.

IJwtAlgorithm algorithm = new HMACSHA256Algorithm();
IJsonSerializer serializer = new JsonNetSerializer();
IBase64UrlEncoder urlEncoder = new JwtBase64UrlEncoder();
IJwtEncoder encoder = new JwtEncoder(algorithm, serializer, urlEncoder);
string token = encoder.Encode(payload, SHARED_KEY);

This part aims to build our JSON Web Token (JWT), which contains the payload and the Zendesk shared key encrypted using SHA256 encryption algorithm.

string redirectUrl = $"https://{SUBDOMAIN}.zendesk.com/access/jwt?jwt={token}";

Now, all that we have to do is to redirect to Zendesk with our JWT token that contains all the required information to ensure the authentication process.

Finally, run the project and you will be redirected to Microsoft authentication page.

Voila!! We’re logged in to Zendesk using our Azure AD account.

Thank you for your attention and please let me know if this post helped you or if you have any questions. Don’t hesitate to share this post with your friends.

2 Comments

Join the conversation! Your thoughts help the community grow.

Niclas Kårlin6y ago
Hi! You never explained how to fill in the login and logout URL in the Zendesk settings. I found in this page https://blogs.sap.com/2019/09/03/part-2-configuring-jwt-token-verification-flows-for-azure-active-directory/ a hint that you could run this link and get some info, but I don't know which link to use where. https://login.microsoftonline.com/%7Byour_azure_active_directory_id%7D/.well-known/openid-configuration
Rique Aleman8y ago
Hello Majdi - I've been following this guide in an attempt to provide SSO for existing ZenDesk and Azure AD infrastructure and I've been able to resolve some of the errors except this one "The type or namespace name 'ErrorViewModel' could not be found (are you missing a directive or an assembly reference?)". I've gone over your guide several times but have I missed or overlooked something in this setup? I'm relatively new to Visual Studio and JWT but fluent in Visual Basic and PowerShell. Thanks for a great guide and appreciate your assistance.