Introduction

Page template is a great feature in SharePoint online and helps users save a lot of time. In some scenarios, for example — rolling up site pages in a web part, we might have to exclude these page templates as it wouldn’t make sense to display them in such scenarios.

Options to exclude page templates

SharePoint REST API

If we are using SharePoint REST API to get the site pages, then we can add the filter OData__SPSitePageFlags ne "Template" to our query. The details of this property is explained in detail by Beau Cameron in this blog post.

SharePoint search

If we are using SharePoint search to get the site pages, then we have a couple of options to exclude page templates

Option 1 — Excluding the “templates” folder (not preferred)

With this option we can exclude the “path” of the templates folder in our search query. This can be done by adding -Path:"https://yourtenant.sharepoint.com/sites/yoursite/sitepages/templates" . This will exclude all the pages under the “templates” folder in “Site Pages” of a given site.

Option 2 — Using the “SitePageFlags” managed property (preferred)

As mentioned in Beau’s blog post there is an internal column called “OData__SPSitePageFlags” which will have the value as “Template” for a page template. The corresponding managed property for this column is “SitePageFlags”. By adding -SitePageFlags:"Template" to our search query, we can exclude all the page templates in our search results.

GitHub Actions

GitHub Actions can be thought of as a workflow that runs when certain event occurs in GitHub. An event might be for e.g. someone pushes code to a repository, or someone creates an issue etc. When such events occur, we can run some tasks or actions — e.g. sending an email or deploying code to a site etc.

If GitHub Actions are new to you, please have a quick look at this short video to understand what GitHub actions are and then have a look at this video by GitHub to understand more details.

In this post we will create a workflow that will run on a schedule. The action that it will perform are:

1. Get all the issues in the repository that are marked as important
2. Pass those issues to a Power Automate flow
3. The flow then posts a message in a Teams channel and sends a notification

The diagram below shows the overall process.

Power Automate

Let’s start by creating a flow. Note: We use a trigger that requires a premium license. So please make sure a right license has been purchased/subscribed to. (If premium features of Flow need to be avoided then we can think of using SharePoint list item triggers.)

You can import the flow provided here so that everything will be setup. Once imported, the flow should look as shown below (The flow uses simple steps and is self-explanatory)

There are 2 items that need to be done after importing:

1. Edit the “Post issues in a Team channel” step in the flow to point to the required Team and channel.
2. Save the flow so that it generates the HTTP POST URL in the first step. Please copy this URL as it will be needed later.

GitHub workflow

Now we need to create a workflow in GitHub which will send the required issues to the flow we created above.

To do that, navigate to the GitHub repository from which you need to send weekly report of the issues. Click on “Actions” tab. GitHub will recognize project type and will show us some predefined workflows which can be used. However, we will not use a predefined one and instead start from scratch. So, click on “Set up a workflow yourself”.

This will open a YAML file with some code in it. Delete all the code and enter the following

This is a YAML file in which we do the following:

1. Run the workflow on every Monday at 9AM
2. While running

• Use latest version of Ubuntu OS
• Calls a GitHub action (anoopt/get-issues-and-call-flow) which will
• Get all the issues that are open and have the label as ‘bug’
• Build an object to hold all the issues and some other information
• Post all the issues to the flow we created earlier

We need to update the following lines in the file as per our requirement:

1. Line number 16 — At the moment this says ‘bug’ which means we get the issues that are labelled with ‘bug’. If a different label is needed, please change this accordingly.
2. Line number 18 — Please enter the flow HTTP POST URL that was copied in the previous section.

Commit this file to save the changes.

Performing a quick test

If a quick test needs to be performed, then please we need to update the trigger in the YAML file. To do that, please comment line number 4 and 6 and write “push” instead — which means every time a file is pushed, the workflow runs.

Save that file and then click on “Actions” tab, we should the see the workflow running

Once the run is complete, make sure that the message is posted in Teams and a notification is received.

If all is ok, please revert the workflow file (YAML) to the way it was earlier i.e. removing the push trigger and uncommenting lines 4 and 6.

Other options for workflow

In the workflow above we are using a GitHub action which gets all the required issues and posts some JSON data (in a particular format) to a Flow. If this feels a bit restricted i.e. if the JSON format needs to be updated or say if the Flow can be skipped entirely then the following options can be looked at.

Writing custom script in the workflow

Instead of calling the action in the workflow, we can write our script which gets the required issues and then we build the JSON in the format we need. After that we can post that JSON to Flow. One such sample workflow can be found here.

Creating an Action using Graph API

The action used in the workflow (anoopt/get-issues-http-post) calls a Flow using the flow URL. Instead of that, we can think of creating a new Javascript action or Typescript action which uses Graph API to post a message to Teams. So, the idea would be to get all the required issues first like “anoopt/get-issues-and-call-flow” does and then post that JSON to Teams using Graph API. Once that action is built, we can use that new action in the workflow.

Creating an Action using Teams API

This option is similar to the previous one except that we use Teams API instead of Graph API.

Using Logic App

Instead of a the Power Automate flow, a logic app can be used which performs similar steps.

Using adaptive cards

The Power Automate flow can be edited and actions related to adaptive cards can be added to post to Teams.

Details of the GitHub Action

The code for the get-issues-http-post GitHub Action is written in Typescript. The important file in the project is main.ts . This file has code to get issues of the repository where the workflow runs. This is done with the help of octokit client as shown in the code below.

Once the issues are obtained, we extract only the required properties, form an array of the same and send it to the HTTP endpoint using node-fetch.

Summary

GitHub Actions are very powerful and provide a fantastic ability to automate lot of tasks. In this post we have seen how we can communicate between GitHub and Teams via Actions and Power Automate. Communicating between GitHub and Microsoft 365 becomes much simpler as soon as Actions and Power Automate come into picture. Hope in future more and more workflows and actions get developed so that more and more tasks can be automated.

In this post, we look at a GitHub Action that creates an event in a user’s Outlook calendar with Microsoft Graph using MSAL for Node.

In a related post published previously, I have explained how we can do the same using PnP JS. In this post we will be modifying that approach to use MSAL for Node instead of PnP JS.

Example scenario

An example usage might be — when a pull request is submitted in the MAIN branch on the GitHub repository, an event is created in the repository owner’s calendar on the next day which contains the details of the pull request. The owner will get a reminder on the next day at the specified time and then the owner can review the pull request and can the required take action.

Setup

Firstly, if GitHub Actions are new to you, please have a quick look at this short video to understand what GitHub actions are and then have a look at this video by GitHub to understand more details.

Pre-requisites for using the action

App registration

Since the GitHub Action explained in this post uses Microsoft Graph, we need to create an app registration in Azure AD so that we can communicate with Office 365. To do that please follow the instructions mentioned in this video by Microsoft. Provide the app “Calendars.ReadWrite” permissions and create a client secret for that app.

Repository secrets

In the GitHub repository where this action will be used, create the following 3 secrets by navigating to “Settings > Secrets”

1. CLIENT_ID : The Id of the app registration created above
2. CLIENT_SECRET : A secret of the app registration created above.
3. TENANT_ID : The Id of your Microsoft 365 tenant.

Using the action in workflow

In the GitHub repository, click on “Actions”. GitHub will recognize project type and will show us some predefined workflows which can be used. However, we will not use a predefined one and instead start from scratch. So click on “Set up a workflow yourself”.

This will open a YAML file with some code in it. Delete all of and enter the following

When there is a pull request, the above workflow will create an event for user ‘user@contoso.onmicrosoft.com’ on the next day from 12:00 to 13:00 (automatic as no start or end is specified).

If more information about the event is needed then, all of the information attached to an event is available in the github.event variable. We can use github.event object in the required steps — e.g. in the body of the calendar event github.event.compare .

More details on the usage of this action can be found here.

Repo related to the action

The entire code of the action can be found here. Please feel free to fork it and make changes accordingly.

The process-related to developing an Action (Node js) is similar to developing any Node js project. Once we are happy the code does what it is should do, we add some files related to make the code into a GitHub action. Instead of me rewriting the whole process, here is an article from GitHub which explains on how to create a simple JavaScript action.

Packages

The same concept was used to create the “Create an event with Microsoft Graph using MSAL” action. Once the base setup is ready, we install the MSAL for node package

npm install @azure/msal-node

We also install

1. The package related to Microsoft Graph so that we can use the Graph client.
2. date-fns package to help with the date related functionality

npm install @microsoft/microsoft-graph-client isomorphic-fetch date-fns

To make use of the code related to actions i.e. say getting inputs or providing outputs we install the ‘@actions/core’ library

npm install @actions/core

There are more such packages provided by the GitHub team which can be found here which will help in creating the code for Actions.

We can instead download the repository and install all the packages by running npm i .

Code

The repo contains 3 typescript files.

1. main.ts — Gets the inputs from the workflow and passes them to helper methods in other files.
2. graph.ts — Has methods to create an event in a person’s calendar with the help of Graph client.
3. auth.ts — Makes use of MSAL to get an access token which will then be used by methods in graph.ts

In main.ts we get the input variables using the example code shown below:

const subject = core.getInput('subject');

We do the same for all the inputs.

Once we have all the inputs, we perform the authentication with the help of client id, client secret and the tenant id. After that we compose the event object and pass it to the Graph API /users/{username}/calendars/events .

Summary

What we have seen above is a simple action that uses the power of MSAL and Microsoft Graph to create an event. With Microsoft Graph there are endless possibilities that we can think of developing.

Note: The details that we will see below are the ones that I tend to follow for remote development. The approach mentioned is not the only approach. There are several other setup options that can be utilized for remote development.

Setup

In this setup we will be using a Linux based Azure VM. The access/interaction with the VM will not be via GUI. Instead it will all be via commands. We will be installing node js on the VM and all our SPFx code will reside on the VM. For developing SPFx solutions we need to access port 4321 on the VM. This is taken care by VS code remote-SSH with the help of port forwarding.

In summary, all the development is done on a remote machine, we do not access the UI of that machine, we consume only the files on that machine and with VS code the experience will be as if we were writing code on our local machine.

The setup in brief consists of the following:

1. VM in Azure with SSH configured.
2. VS code Remote-SSH extension to connect to the VM.
3. Commands to execute to get started with SPFx development.

Azure VM

If we have a Visual Studio subscription, then we get a certain amount of free Azure credits per month that we can use for development. The amount of credit depends on the subscription. More details can be found here. So, let’s take that opportunity to create resources in Azure. One such resource is an Azure VM.

To get started with the setup we need to create a VM in Azure and configure it so that we can connect to it using SSH. Microsoft VS code team have written a nice post on how to do that. So, we can follow all the instructions in that post except for the last 2 sections (creating a Node.js app).

Creating a VM in Azure

SPFx setup

Once we have our VM up and running and we are able to communicate with it via SSH, we need to start the setup related to SPFx.

In the VS code terminal window let’s run the following command to re-sync the package index files from their sources.

sudo apt-get update

After that let’s install the curl package using the following command

sudo apt install curl

Next step is to install node js. We have a couple of options for that

1. We can install a specific version of node js by following the instructions here.
2. We can install nvm and then choose a version of node js we want.

We will use the NVM option (so that we have multiple versions of Node js if needed in the future). So run the following command to install nvm

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/0/37.2/install/sh | bash

We will then install node js version 14.15.5 (one of the supported versions for SPFx development)

nvm install 14.15.5

If there is an error while installing, trying restarting the terminal in VS code

Check if the correct version of node js is installed with the following command

node -v

Now that we have node js setup, let’s install the packages needed for SPFx. They are gulp, yeoman, yeoman generator for SPFx projects. Let’s also install an SPFx development utility tool called “spfx-fast-serve” which helps us in saving time while development.

npm i -g gulp yo @microsoft/generator-sharepoint spfx-fast-serve

Once that is done we can start creating SPFx projects. Let’s run the following commands:

mkdir projects && cd projects

mkdir spfx-hello-world && cd spfx-hello-world

This will create folder named “spfx-hello-world” and we will create our project in that folder. To that run the command:

yo @microsoft/sharepoint

Follow the instructions and wait for the command to complete. Once done, run the following:

spfx-fast-serve

npm i

This will configure spfx-fast-serve for the project.

Let’s now run the project with the following command

npm run serve

This will build the project and open browser window pointing to “https://localhost:4321/temp/workbench.html”.

VS code automatically takes care of forwarding the port with number 4321 i.e. the port number 4321 from the Azure VM is forwarded to our local machine and we can continue working in the same way like we do on our local machine.

If the SPFx web part / extension is present on a page in SharePoint site then we can debug the web part / extension directly by appending the following to the page URL

?loadSPFX=true&debugManifestsFile=https://localhost:4321/temp/manifests.js

With spfx-fast serve, if we make any changes to the code, the SharePoint page which has the webpart (or the workbench page) is automatically refreshed to reflect the changes.

Watching file changes

In case changing the code in the files, doesn’t refresh the page to show the changes and/or a waring like below is seen in VS code then this is related to file watcher running out of handles because of the large workspace.

To resolve that issue we need to update a system file with the following commands:

cd /

sudo vi /etc/sysctl.conf

This will open the sysctl.conf file in the terminal. Type

i

to enter in insert mode. Scroll down to the bottom of the file and add the following

fs.inotify.max_user_watches=524288

Press esc to come out of insert mode.

Type :wq! to save and quit.

Verify the changes by executing the following command

sudo sysctl -p

If we then navigate to our project directory and run the project, we should not see the VS code warning and changing the code should be reflected on the page.

Summary

With the help of Azure machines, VS code and Remote-SSH extension we can easily set up a remote development environment. We can then install the packages required for SPFx development and start developing SPFx projects. The development experience is very smooth and since the VMs are powerful the build and debug time will be very less. With VS code in picture, the remote development experience feels the same as local development experience.

Taxonomy Graph API

The Microsoft Graph API for taxonomy helps us to perform CRUD operations on the taxonomy data present in our Microsoft 365 tenant. More details about this can be found here.

The taxonomy data can be used in several places for several purposes in SharePoint sites. It helps us in classifying the SharePoint content in such a way that users will be able to get to the content they require faster. Since taxonomy plays an important role in SharePoint, understanding how to interact with taxonomy in SPFx would be very helpful for us so that we can develop web parts / extensions to handle various scenarios related to taxonomy.

Sample code

In this blog we will look at a scenario in which we will read the data from taxonomy using Microsoft Graph. All the code explained in the blog can be found here.

Cascading taxonomy dropdowns using SPFx

In order to explain the usage of the taxonomy API, let’s assume the following:

1. A term group named “1 company”
2. A term set named “Our location”
3. Parent terms as countries — France, Germany, India and UK
4. 1st level Child terms as cities — London and Manchester.

We will see how to read all the parent terms (countries) from a term set and then how to read all the child terms (cities) under a parent term.

Using the taxonomy API

The SPFx web part is developed using React hooks and accepts only one property as input and that is the ID of the term set (Our locations).

When the web part loads, we get all the countries (parent terms) present under “Our location” (term set). This can be seen in the getCountries method. In that method we call the List children endpoint of the term set taxonomy API which will list the first level children under a term set — which in this is case is all the countries. We then populate those countries in a country dropdown.

When a country is selected from a the dropdown, we get all the cities (child terms) of the selected country — the _onCountryChange method. We call the List children endpoint of the term taxonomy API which will list the first level children present under a term — in this case all the cities. These are the populated in the city dropdown.

At the time of writing this post getting the custom properties of a term from taxonomy API was not possible. Hence description of a term was used to store data associated with a term.

However we can now access “Shared Custom Properties” of a term using the taxonomy API by adding “properties” to the “$select” clause.

In this scenario we store the co-ordinates of a city in the description. We use that data to show the exact location in the PnP SPFx map control.

To send a request to Microsoft Graph, we use a helper class. This was created by Mikael Svenson and it can be used in any SPFx project. This class has 4 methods to perform CRUD operations using Microsoft Graph.

Caching

In the scenario explained here, the data in the taxonomy doesn’t change when the user is interacting with the web part. Hence to improve performance, it makes sense to cache the data instead of calling the taxonomy API each and every time. When we get the city terms under a country we can store them in cache (local storage). To do that we use a class that has methods related to adding data to local storage and fetching data from local storage when needed.

Summary

Thanks to the Microsoft Graph team we are now able to interact with the taxonomy data. In this blog post we have seen a simple way to read the data in SPFx web part. This web part can be easily extended to create/update/delete taxonomy data as well. All this is now easily possible with the help of the various taxonomy endpoints provided by this API.

Microsoft Graph API for taxonomy (beta) + SPFx was originally published in Geek Culture on Medium, where people are continuing the conversation by highlighting and responding to this story.

PnP search web parts

PnP search web parts are a set of modern web parts which help us a lot in providing a smooth search experience in modern SharePoint sites. More information about those web parts can be found here.

Editing the settings

In a SharePoint site we can create pages based on a template that might have these web parts on them. Say for example, we might have PnP search results web part(s) on the pages at a particular location, to roll up content based on the metadata of the page. If we want to change the settings in those results webpart across all the pages, then we have a couple of options:

1. Manually edit each page that has these webparts and update the settings.
2. Change the settings in one page, export the settings and import those settings, in all the other pages manually. This is with the help of “Import / Export settings” capability seen in the web part property pane.

This blog post aims to introduce a 3rd option to update the settings of the PnP search results webpart across all the pages.

Copy PnP search results web part settings SPFx extension

We now have a list view command set available to carry out the above task. Let’s establish a scenario to see how this extension works.

Say we have created hundreds of department pages in our site that have a PnP search results webpart in the second column of the first section. This web part rolls up all the documents of department content type. A new requirement comes up to say each of these department pages must roll up only documents belonging to that department. We then come up with a query/settings to do solve this requirement. Now our task is to apply that query/settings to the web part in all the pages.

That is when we can use the copy PnP search results web part settings SPFx extension. If we change the query/settings in one page, then using this extension we can copy those changes to all other pages.

Using the extension

After the query/settings is changed in a page (source) we need to do the following:

1. Navigate to the pages library and select all the other pages (destination) where the web part query/settings needs to be changed.
2. Select “Copy PnP search settings” from the command.
3. Provide the name of the source page and location of the web part on the source page i.e. the section, column and order.
4. Provide the location of the web part in the destination pages.
5. Press submit.

This will then copy the query/settings of the PnP search results web part from the source to the web part in all destination pages and output the result by showing which pages were successfully updated and which were not.

Details of the code

Based on the details provided the extension uses PnP JS to get the properties of the web part where the query was updated. This can be seen in the getSourceWebpartSettings method. We get the json of the web part using PnP JS and then webPartData.properties.

After that, in the updateDestinationWebpartSettings method, we can see that the extension uses PnP JS to update the properties of the webparts in the destination pages. The extension also provides to perform this operation in batches using the PnP JS batching capability. This can be seen in upddateDestinationWebpartSettingsUsingBatch method.

The extension also provides an option to export the PnP JS code. This code can be copied and then tweaked as per the requirement. After that the SP editor browser extension can be used to run the code.

Enhancements

Currently this SPFx extension is developed such that it works with PnP search results web part only. It can be changed to work with other web parts if needed. This would involve updating the code to get and set intended web part properties (from the web part json) based on the type of the web part.

Summary

Settings/properties of a web part in a modern page can be easily copied from one page to other pages using PnP JS. We need to get the web part object first based on it’s location and then get the webPartData.properties property of that object. This data then needs to be set as the properties of the web part on other pages. We saw how we can do the same for PnP search results web part using an SPFx extension.

The script

The script to set the author byline in the header can be found here.

_AuthorByline field

Modern pages have a field called _AuthorByLine. When we set the value of this field of a page to the login name (or the email address) of a user, we will see the user details appear in the page header byline. However, as soon as we edit the page those details disappear (or the details of the user that were set before are shown).

It appears that when in view mode of the page, the page header byline loads the data from _AuthorByLine field of the page. (If no data is found then the page header byline tries to get user data from LayoutWebpartsContent field of the page.) Whereas in edit mode, page header byline tries to get user data directly from LayoutWebpartsContent field of the page. Since LayoutWebpartsContent will not have the details of the user the header byline won’t show anything in edit mode.

In the image below we set the _AuthorByLine field of Page-1.aspx and then we get the LayoutWebpartsContent field of the page. We can see that the authors data in the HTML is empty.

So to make this work, along with the _AuthorByLine field, we also need to set LayoutWebpartsContent field of the page with the details of the user.

PnP Core SDK

LayoutWebpartsContent field contains HTML content and to update that field we can rely on the PnP Core SDK. PnP have made our task easy by extracting the HTML content from LayoutWebpartsContent field and mapping them to properties in the PageHeader property of the page. The properties that we are interested in are Authors and AuthorByLine. We need to set these properties and save the page. This will then set the LayoutWebpartsContent property of the page.

When we set the Authors property of PageHeader , PnP Core SDK will also set the _AuthorByLine field of the page. So there is no need for us to worry about setting the _AuthorByLine field separately.

Setting Authors and AuthorByLine properties

The Authors and AuthorByLine properties of PageHeader are of type String . We can set them using PnP PowerShell with the following lines of code.

The entire script can be found here.

We can simply compose the strings in the above format using an email address, run the above two lines and save the page. However, if the email address is invalid then we will face a problem by which an invalid value gets set as the header byline. Therefore, the script checks if the email address passed is valid by using Get-PnPUser and New-PnPUser functions.

Running the script sets the above two properties, saves the page and publishes it. By reloading the page we can see the user information in the page header byline.

Displaying user information

In the view mode, the page header byline gets the user information (like Name, Job Title) from the User Information List for user that is set. If the Job Title doesn’t appear then it might be because it is not yet updated in the User Information List. The information in the User Information List takes a few minutes to update/sync.

In the edit mode (or in view mode when _AuthorByline field is empty) the page header byline picks the user information based on the id set in Authors data of LayoutWebpartsContent .

• If the id in Authors is set to email address of the user then the user information is obtained using Microsoft Graph.
• If the id in Authors is set to LoginName of the user (i.e. of the format i:0#.f|membership|... then the user information is obtained using the SharePoint user profile service using REST API (SP.UserProfiles.PeopleManager/GetPropertiesFor).

Summary

To display a user’s information in header byline of a modern SharePoint page, we need to set _AuthorByline and LayoutWebpartsContent field of the page. We can do that using PnP PowerShell by setting the Authors and AuthorByline properties of the PageHeader property of a page.

Setup

Let’s assume the following setup (in the same tenant) for this post:

• Client runs on a timer (or it receives requests from end users).
• Client app runs code to get an access token and calls the server app for data (say Orders).
• The server app receives requests only from apps (not users) and expects certain claims to be present in the request.
• The server app is secured using an app registration.
• Based on the request received, the serve app does some computation and returns the data (Orders) to the client app.
• If applicable, the client app then returns that data to end users.

In this blog post we will be focusing on points 2, 3 and 4 above which are related to the way the client app sends requests to the server app. An HttpClient object will be used by the client app to call the server app. This HttpClient will have the access token in it’s request headers. In the sections below we will see a few ways of getting this access token.

Server app registration

An app registration is associated with the server function app. This app registration is server’s identity and is used to secure the server function app.

Application role

The server app registration is setup with an application role let’s say “Orders.Read” — which is a custom role. (This role is exposed as an application permission that can be added in other app registrations.)

To make sure that incoming requests have role assignments and only apps with “Orders.Read” permission can get the data from the server, the code in the server function app verifies that the incoming requests have “Orders.Read” role in the request. This is done by checking the “roles” claim of the incoming request.

req.HttpContext.ValidateAppRole(new string[] { “Orders.Read” });

Client function app

The client function app is a daemon app which uses it’s own identity (client app registration) to get data from the server function app. (The client function app can also be a non-daemon app but will still use it’s own identity (not users identity) to get data from server).

The client app registration will have “Orders.Read” application permission that will be approved by the admin. With this, the access token that gets generated in the client function app’s code will have “Orders.Read” role in the roles claim.

In the following sections we will see how to generate the access token in the client function app.

Code

All the code explained below can be found in this GitHub repository. Please note that the code is to show the concepts only and is not PROD ready.

Generating access token

Microsoft provide us with various authentication libraries which do all the hard work of computing the access token and checking it’s expiry. So, all we need to do is install one of those libraries in our project and use the methods that are provided by these libraries and get an access token. Let’s take a look at those libraries and the methods they provide:

1. ADAL (not recommended / deprecated)

Note: Using ADAL is deprecated hence not recommended. So use MSAL instead.

Using ADAL we create an AuthenticationContext object and get the access token using AcquireTokenAsync method of the authentication context object as shown in the image below and the code here.

2. MSAL.NET

In MSAL.NET, apps are represented either as public client or confidential client applications. In our case the client app registration will be represented as confidential client application. So, we create a variable of type IConfidentialClientApplication using the ConfidentialClientApplicationBuilder class provided by MSAL. We need to provide the client app registration’s ID, it’s secret (or certificate in case of PROD) and the tenant ID.

We then use the AcquireTokenForClient method with the scopes as “ServerAppRegId/.default” to get an access token. The access token will have the server app registration’s ID in the aud claim and will have the Orders.Read entry in the roles claim.

The code for the same can be seen in the image below and here.

Managed identities

Instead of using the client app registration to represent the client function app, we can create an identity in a different way for that function app by using managed identity. This will help us move away from maintaining client secret or certificate.

Managed identity for the client function app can be created by following the information in this Microsoft article.

The managed identity that is created will not have any permissions to talk to the server app. Hence we need to add “Orders.Read” application permission to the managed identity. We can do that either using Azure PowerShell or Microsoft 365 CLI. The Microsoft 365 command will be:

m365 aad approleassignment add — displayName “client-function-app” — resource “server-app-reg-name” — scope “Orders.Read”

Once the permission is assigned we can create a request to get an access token, to access the server app, using the managed identity of the client function app. Let’s see a couple of ways in which we can do that.

3. App Authentication client library for .NET

Note: For new applications Microsoft recommend using Azure.Identity instead of this library.

With this library we create an instance of AzureServiceTokenProvider with the connection string as RunAs=App. We then use the GetAccessTokenAsync method by passing in the server app registration’s ID to get an access token.

The access token will have the server app registration’s ID in the aud claim and will have the Orders.Read entry in the roles claim.

The code for the same can be seen in the image below and here.

4. Azure.Identity library

Microsoft have mentioned in this article that “Azure.Identity can be considered as the spiritual successor of the App Authentication client library for .NET”. Using Azure.Identity library we create an instance of ManagedIdentityCredential class. This will automatically use the credentials of the managed identity configured for the client function app. We then call the GetTokenAsync method with the scopes as “ServerAppRegId/.default” to get an access token. The access token will have the server app registration’s ID in the aud claim and will have the Orders.Read entry in the roles claim.

The code for the same can be seen in the image below and here.

Local development auth

During development if we want to test the above functionality (3 and 4) then, we have cannot use Managed Identity for authentication locally. Hence we have to use different methods of authentication.

More information on those methods can be found here and here.

Videos related to the same by Garry Trinder and Rahul Nath in their blog articles.

In the code that is shared along with this blog, we will be using the credentials of the client app registration for authentication during local development. This can be seen here and here. We make use of client app registration’s ID and secret to authenticate. This needs to be the case only in DEV tenant. In PROD there will be no need to have client app registration when using Managed Identity.

Further enhancements

The code in the server function app at the moment checks only if the token has the correct roles claim. The code can be enhanced further to perform more checks based on the security requirement. Those checks might be verifying if the aud claim in the request is the intended one or not etc.

Summary

We have seen 4 different ways of getting an access token for a daemon app (Client) to call an API (Server)using the different libraries provided by Microsoft. Thanks to Microsoft, all the hard work of computing the access token is done by the libraries. We have seen how easy it is to use the methods provided by those libraries.

If we are using an app registration to represent the client function app then we should use MSAL to get the access token and if we are using managed identity to represent the client function app then for the new development it is recommended to use Azure.Identity to get the access token.

In this 2 part series we will start by looking at:

1. What GitHub codespaces are and how to create them. After that we create a simple SPFx webpart in GitHub codespaces.
2. How to push the code of the SPFx webpart from GitHub codespaces to a repository in Azure DevOps.

Part 1 — GitHub Codespaces

What are GitHub codespaces?

GitHub codespaces are cloud hosted development environments that can be created very quickly so that we can start coding on a project right away. In terms of SPFx development we can think of GitHub codespaces as a preconfigured development environment (in the cloud) which has all the SPFx pre-requisites installed.

GitHub codespaces are currently in beta and access can be requested from here. During the beta stage each user can create a maximum of 2 codespaces.

Creating GitHub codespaces (need to request access first)

In order to create GitHub codespaces, we need a GitHub repository. Navigating to a repository and clicking on “Code” button and selecting “Open with codespaces” provides us an option to create a new codespace.

The new codespace (i.e. a development environment in cloud) that gets created will be based on Linux and will have version 12.x of node. More information on what is included in that codespace can be found here.

The newly created codespace will be automatically connected to the repository in GitHub. So if we add/remove files we can commit them back to the connected repository.

Accessing codespaces

We cannot RDP into this codespace, instead we connect to only the code we need in the codespace from VS code (either from the browser or from the editor on our machines). We need a VS code extension named “GitHub Codespaces” to access codespaces.

GitHub codespaces for SPFx

When a GitHub codespace is created, by default it will have Node version 12.x. For SPFx development we need Node version 10.x. Also the codespace will not have the other components like yeoman, the SPFx generator etc which are needed for SPFx development.

There are different ways of making the codespace have the setup required for SPFx development i.e. personalizing the codespace as per our requirement. We will be looking at the Docker approach.

When a new codespace is being created, it will look for something called as dotfiles (files and folders beginning with a dot). We can define the required SPFx configuration in these dotfiles. We can achieve this is by creating a folder named “.devcontainer” and adding 2 files in it named “Dockerfile” and “devcontainer.json”.

Note: The configuration specified in these files will be applied only to a new codespace at the time of creation. It will not apply to existing codespace. So if you have created a new codespace without these files then it would be good to delete it or run the pre-requisites manually.

Docker file

Please refer this article by Waldek Mastykarz to know about Docker and SPFx. Since a Docker file already exists for SPFx, we will be using that for our initial setup with a minor update.

devcontainer.json

This file contains information about the default settings of a codespace. One of the setting we need is what ports need to be forwarded from the codespace. So we will be defining those in this file. For SPFx we need ports 4321, 5432 and 35729 to be forwarded from the codespace.

.devcontainer folder

Lets either create a new repository with only file in it (README.md) or open an existing SPFx repository. Let’s add a folder named “.devcontainer” in the repository at the root level.

In this folder lets add the following 2 files:

1. Dockerfile (click to open content)
2. devcontainer.json (click to open content)

In the Dockerfile, we have specified the Node version as 10.22.0 and have also specified all the npm packages that need to be installed for SPFx development.

In the devcontainer.json we have specified that the Dockerfile needs to be used for creation of the codespace and we have specified the required ports that need to be forwarded.

Creating a codespace (need to request access first)

Now let’s create a codespace from this repository. For this all we have to do is click on “Code” button and select “Open with codespaces” and click “New codespace”.

This will start the process of creating the codespace which will involve looking at the “.devcontainer” folder for the configuration that we defined. We can see all the messages being logged related to installing the packages.

Once finished, we will see VS code opened in browser with the code in the repository. We can see the “.devcontainer” folder and other files present in the repository.

If we open the terminal (Ctrl + ‘) and type “node -v” we can see that the version is 10.22.0 as specified in the “Dockerfile”.

If we open the Remote explorer extension and have a look at the forwarded ports section, we can see the 3 ports forwarded that we defined in “devcontainer.json”.

SPFx development

We can continue the next steps in the browser, however I prefer doing it in the VS code editor. So let’s open VS code and install the “GitHub codespaces” extension if not installed. After signing into codespaces with our GitHub accounts we will be able to see the codespace that was created earlier.

Connect to the codespace by clicking on the connect button to load the code.

Now we are in the familiar territory. So let’s open the terminal in VS code and start developing SPFx solutions with our favourite command yo @microsoft/sharepoint .

Before testing the solution we need to make sure that the dev certificate is trusted. To do that, please follow this article by Paul Schaeflein.

node_modules

One nice thing to think/feel about is that there is no “node_modules” folder of this project on our machines now!

Azure DevOps

If we want to store the above code in Azure DevOps instead of GitHub then in the next we will look at how to push the code from GitHub codespaces to a repository in Azure DevOps.

The instructions mentioned here can be done for any code in GitHub codespaces. Also the instructions show one of the several ways of push the code to Azure DevOps. So let’s be sure that this is not the only way.

Repository in Azure DevOps

Let’s start by creating a new Git repository in Azure DevOps. There are many articles on the internet explaining how to do that.

Our intention is to make the GitHub codespace we created in part 1 to talk to the repository we created in Azure DevOps. There are several ways of doing this. We will go ahead with the SSH key approach which will be helpful in a way that there is no need to enter password for our git operations.

In newly created repository, click on “Clone” and then click on “SSH” and copy the URL representing the repository.

Setup in codespaces

Now in VS code let’s connect to the GitHub codespace that we created in part 1 and open the terminal. Now the code over here is already connected to a repository in GitHub. We need to remove that connection and establish a new connection to our repo in Azure DevOps.

So in the terminal enter the following command to remove the .git folder and hence the connection

rm -rf .git

After that initialise a repository with the following command

git init

Let’s use the SSH URL copied earlier to add a remote for our Azure DevOps repo

git remote add origin git@ssh.dev.azure.com:v3/ — project — / — repo —

As mentioned earlier, instead of using password authentication for git operations, let’s use SSH keys to authenticate. More information on this can be found here. To create SSH keys let’s run the following command:

ssh-keygen -t rsa

More parameters can be supplied by referring the guides here and here.

As part of running the command, let’s not provide any file name or passphrase. So simply keep pressing return until the command finishes execution. Once completed, we can see the path of the file where the public key is saved.

We need grab that public key and add it in Azure DevOps i.e. associate the key with our Azure DevOps account. To get the public key run the following command

code /home/spfx/.ssh/id_rsa.pub

or if you are using VS code insiders

code-insiders /home/spfx/.ssh/id_rsa.pub

Copy the key without any line breaks and navigate to Azure DevOps and click on “SSH public keys” as shown in the screenshot below

In the SSH keys window, click on “New key”, provide a relevant description and paste the copied key and save it.

Back in VS code test if this operation was successful by entering the following command

git fetch

If all is ok the next steps are to push the code to the repository. These are standard steps like we always do for other projects which include the standard `git commit` etc either via the terminal or via the source control extension.

Conclusion

After all the operations, our code will be in Azure DevOps.

When we connect to this GitHub codespace again, everything is setup and we can continue working on our SPFx solutions and keep committing the changes to the repo in Azure DevOps.

Once the project is complete, we can delete the GitHub codespace and move onto the next project by following instructions in Part 1 and this article.