How to connect to SharePoint search API using certificate authentication

Hello everyone and welcome to my blog. Today’s blog is going to be bit different from my usual blogs on Power Apps and SharePoint. In this blog I will discuss on how to connect to SharePoint Search API using POSTMAN

At the end of the article you will also learn the following topics.

Authenticate using grant_type=client_credentials with a certificate
Connect to SharePoint search API using POSTMAN
How to use client_assertion with POSTMAN to connect to REST API’s
Generate client_assertion using a certificate and use it in POSTMAN/ HTTP methods.

So let’s get started on our journey. We will use an APP to connect to SharePoint Search API and retrieve the results. So the first step is to create an APP in Azure AD. Navigate to Azure Active Directory -> App Registrations and create an APP.

OAuth2.0 authentication with grant_type = client_credentials using a certificate

As mentioned earlier, I will use certificate authentication here. So I navigate to Certificates and Secrets and upload a certificate. You need to use X509 certificate for this purpose.

For this demo I have used a self signed X509 certificate which I created using OpenSSL. Follow this link here to generate a self signed X509 certificate.

Although you shall be required to upload .crt or .cer file here, please keep the .pfx file and the password handy. You shall need it later to get the client assertion.

Make sure to provide the APP the following API permissions. And also grant admin consent. Be careful with the API permissions.

Application permissions
- Sites.Read.All
- User.Read.All
Delegate permissions
- Sites.Search.All

Now the most important part. How to authenticate and get the data? As I said earlier, I am going to use POSTMAN. If I can make it work with postman, it will work with any HTTP client.

The first and most important thing is to generate an authentication token. Remember we are using a certificate and not client secret. So we need to use client_assertion in the request body instead of client_secret.

URL >>> https://login.microsoftonline.com/{tenantid}/oauth2/v2.0/token
Request Body as show in the screenshot below.

As you can see, we now have two new properties. One is client_assertion and the other is client_assertion_type. client_assertion_type is hardcoded value and you should use the same for your requests.

Don’t forget the scope parameter. The scope parameter format is – <sharepoint_site_url/.default

We need the assertion value. And this is where you will have a challenge. First you need to have the certificate .pfx file and the password. From that you can generate the assertion using code of your choice or from JWT website.

Below is the code which shall help you to generate the client assertion. I have built the code with C# console application but you can use Power Shell too.

Before you copy and paste this code, you should add the following Nuget Package references to your project.

Microsoft.IdentityModel.Logging
Microsoft.IdentityModel.JsonWebTokens
Microsoft.IdentityModel.Tokens

using Microsoft.Xrm.Sdk;
using Microsoft.Xrm.Sdk.Messages;
using SPTokenGenerator;
using System;
using System.Collections.Generic;
using System.IO;
using System.Linq;
using System.Net;
using System.Text;
using System.Threading.Tasks;

internal class Program
   {
      static void Main(string[] args)
      {
         AcquireToken();
      }

      static void AcquireToken()
      {
         string clientId = "<your application id>";
         string tenantId = "<your tenant id>";
         string aud = $"https://login.microsoftonline.com/{tenantId}/v2.0/";
         s
         X509Certificate2 certificate = new X509Certificate2("<your .pfx file path>", "<Your certificate password>");
         var claims = new Dictionary<string, object>();

         claims["aud"] = aud;
         claims["sub"] = clientId;
         claims["iss"] = clientId;
         claims["jti"] = Guid.NewGuid().ToString();

         var signingCredentials = new X509SigningCredentials(certificate);
         var securityTokenDescriptor = new SecurityTokenDescriptor();
         securityTokenDescriptor.Claims = claims;
         securityTokenDescriptor.SigningCredentials = signingCredentials;

         var tokenHandler = new JsonWebTokenHandler();
         var clientAssertion = tokenHandler.CreateToken(securityTokenDescriptor);

         Console.WriteLine(clientAssertion);

         Console.Read();
      }
   }

When I run this piece of code, I get the client assertion value. And we are going to use the assertion value in our request to generate the bearer token.

Once I have the bearer token I will now use the SharePoint search API to query results. I use the below URL to search for the text ‘portal’.

https://aibuilderdd.sharepoint.com/_api/search/query?querytext='portal'&selectproperties='Title'

This blog is more on how to connect to SharePoint search API using certificate authentication. You can learn in detail regarding Search API in Microsoft documentation.

Hope you liked this post. If this post has helped, you can buy me a coffee. Link on the right pane.