Calling Microsoft Graph from your Teams application – Part 1: Introduction

Microsoft Teams applications almost always need to call the Graph API, yet it’s not as easy as just calling a REST service. Most of the complexity has to do with getting an Azure AD access token, which is required on every Graph call to establish what, if anything, the caller is authorized to do.

Getting the access token requires an understanding of Teams, Azure AD, Graph, and sometimes other components like the SharePoint Framework or Bot Framework, yet each of these is documented separately and each one assumes the reader knows all the others. I literally get questions every day from frustrated developers trying to figure this out! (Yesterday I got 3!) In 2 1/2 years of Teams app development, this by far the most common source of difficulties.

I wrote these articles hoping they’ll assist developers in calling the Graph from Microsoft Teams. They’re also companions for my talk, “Calling Microsoft Graph from your Teams Application”, at the PnP Virtual Conference 2020.

  1. Introduction (this article)
  2. Deep dive concepts (optional)
  3. Calling Graph from a Teams tab
  4. Calling Graph from a Teams bot

This article will explain the basics. If all goes well, you can follow the step-by-step instructions in one of the sample apps and be done with it! Some day, the tooling may be improved to automate some of the steps.

Continue reading

Setting up SSL for tabs in the Teams Toolkit for Visual Studio Code

I’ve started using the new Microsoft Teams toolkit and overall I like it a lot! However there is a little challenge when creating tabs, and that’s due to the requirement to use SSL. The documentation is fine and explains how to trust your local project, but I found it a little painful since the certificates only last 1 month and there’s a different one for each project, so I need repeat the process frequently. Your teammates will need to do that as well.

Default certificate from localhost

Here is an alternative approach in which you create your own certificate authority and build certs from that so you can install just one root certificate across all your projects! Each teammate can have their own certs, so you can collaborate as much as you wish and nobody has to go installing certs.

NOTE: Did you know that the Teams Toolkit uses Create React App (CRA) for tabs? Create React App is a toolchain from Facebook (who created React in the first place) it’s very popular and well supported! If you need help, search on “Create React App” and you can find a plethora of helpful articles; this one helped me figure this out!

Step 1: Create and trust a certificate authority (CA)

This step only needs to be done once for as many projects as you wish. It assumes you already have Node.js installed, as required by the Teams Toolkit.

a. Create a safe/private folder somewhere and go there in your favorite command-line tool, and run these commands:

npm install -g mkcert
mkcert create-ca --organization "MyOrg" --validity 3650
mkcert create-cert --ca-key "ca.key" --ca-cert "ca.crt" --validity 3650

NOTE: 3650 is the number of days your certs will be valid; feel free to change it. You can use --help on mkcert to reveal other options, such as setting an organization name and location (the default org is “Test CA”) and customizing the domain names for your certificate (the default is “localhost,127.0.0.1”).

This will create a new Certificate Authority and a certificate that was issued from it. You should see 4 files:

FileDescription
ca.crtCertificate for your new CA
ca.keyPrivate key for your new CA
cert.crtCertificate for use in projects
cert.keyPrivate key for use in projects

b. Now you need to trust the certificate for your new CA; by doing that any cert you create will be trusted with no additional action on your part.

On Windows

  • Double click on the ca.crt file and click “Install Certificate”.
  • Choose Local Machine and click next.
  • Select “Place all certificates in the following store” and then click the “Browse” button. Choose “Trusted Root Certification Authorities” click “OK” to close the dialog box, and then click “Next”.
  • Restart all instances of your browser to force it to re-read its trusted roots. If in doubt, reboot your computer.

On Mac

  • Double click on the ca.crt file, which should be found under /Users/[your-name]/. It will launch Keychain Access app.
  • Enter your password or use Touch ID when prompted. 
  • The new certificate (in this case, “MyOrg”) should be added. Double-click it. 
  • In a new window, expand the Trust section of the certificate details. Select “Always Trust” for every option. 
  • Close the window. Enter your password or use Touch ID again if you are asked. Now the certificate is trusted. 
  • Restart all instances of your browser to force it to re-read its trusted roots. If in doubt, reboot your computer.

On Linux

There are more steps on Linux as most browsers don’t use the operating system’s certificate store, and a tool called certutil is needed to modify the browsers’ cert?.db files. This article explains how to install your new root certificate on Linux.

Step 2 – Add the certs to your project

This is what you need to do for each project.

a. Create a new folder in your project folder (the same level as the package.json file) called .cert. Copy the cert.crt and cert.key files into this folder.

b. Modify your .env file to tell the local web server to use your cert:

HTTPS=true
SSL_CRT_FILE=./.cert/cert.crt
SSL_KEY_FILE=./.cert/cert.key
BROWSER=none

c. Prevent saving the certs to your git repository by adding a line to the .gitignore file.

.cert

Working in a team

Each team member needs to do Step 1 on their computer just once. When a developer starts working on a project they can simply copy their .cert folder into their project and go to work.

Many thanks to my colleague Tomomi Imura for documenting the Mac instructions and providing screen shots.

Do you have ideas on how to do this better, especially in a project team? Please chime in using the comments; thanks!

Calling Microsoft Graph from your Teams application – Part 4: Bots

Microsoft Teams applications almost always need to call the Graph API, yet it’s not as easy as just calling a REST service. Most of the complexity has to do with getting an Azure AD access token, which is required on every Graph call to establish what, if anything, the caller is authorized to do.

Getting the access token requires an understanding of Teams, Azure AD, Graph, and sometimes other components like the SharePoint Framework or Bot Framework, yet each of these is documented separately and each one assumes the reader knows all the others. I literally get questions every day from frustrated developers trying to figure this out! (Yesterday I got 3!) In 2 1/2 years of Teams app development, this by far the most common source of difficulties.

I wrote these articles hoping they’ll assist developers in calling the Graph from Microsoft Teams. They’re also companions for my talk, “Calling Microsoft Graph from your Teams Application”, at the PnP Virtual Conference 2020.

  1. Introduction
  2. Deep dive concepts (optional)
  3. Calling Graph from a Teams tab
  4. Calling Graph from a Teams bot (this article)

This article will explain the options for building bots for Microsoft Teams which directly call the Microsoft Graph. Two options are considered, however it will be easier to decide because there’s really only one choice per scenario.

Continue reading

Calling Microsoft Graph from your Teams Application – Part 3: Tabs

Microsoft Teams applications almost always need to call the Graph API, yet it’s not as easy as just calling a REST service. Most of the complexity has to do with getting an Azure AD access token, which is required on every Graph call to establish what, if anything, the caller is authorized to do.

Getting the access token requires an understanding of Teams, Azure AD, Graph, and sometimes other components like the SharePoint Framework or Bot Framework, yet each of these is documented separately and each one assumes the reader knows all the others. I literally get questions every day from frustrated developers trying to figure this out! (Yesterday I got 3!) In 2 1/2 years of Teams app development, this by far the most common source of difficulties.

I wrote these articles hoping they’ll assist developers in calling the Graph from Microsoft Teams. They’re also companions for my talk, “Calling Microsoft Graph from your Teams Application”, at the PnP Virtual Conference 2020.

  1. Introduction
  2. Deep dive concepts (optional)
  3. Calling Graph from a Teams tab (this article)
  4. Calling Graph from a Teams bot

This article will explain the options for building tabs for Microsoft Teams which directly call the Microsoft Graph. The same methods apply to Task Modules (modal dialog boxes).

Continue reading

Calling Microsoft Graph from your Teams application – Part 2: Deep Dive

Microsoft Teams applications almost always need to call the Graph API, yet it’s not as easy as just calling a REST service. Most of the complexity has to do with getting an Azure AD access token, which is required on every Graph call to establish what, if anything, the caller is authorized to do.

Getting the access token requires an understanding of Teams, Azure AD, Graph, and sometimes other components like the SharePoint Framework or Bot Framework, yet each of these is documented separately and each one assumes the reader knows all the others. I literally get questions every day from frustrated developers trying to figure this out! (Yesterday I got 3!) In 2 1/2 years of Teams app development, this by far the most common source of difficulties.

I wrote these articles hoping they’ll assist developers in calling the Graph from Microsoft Teams. They’re also companions for my talk, “Calling Microsoft Graph from your Teams Application”, at the PnP Virtual Conference 2020.

  1. Introduction
  2. Deep dive concepts (optional – this article)
  3. Calling Graph from a Teams tab
  4. Calling Graph from a Teams bot

The first article is intended to explain the basics which anyone should understand before embarking on a Teams project that will call Microsoft Graph. This article is an optional deep dive that will go into more detail, either for the curious or to help in troubleshooting. The articles which follow target specific scenarios, such as calling the Graph from a tab or bot in Teams.

Continue reading

Starting a new role at Microsoft

I’m very excited to announce that today is my first day as a Cloud Developer Advocate at Microsoft, focused on Teams and Graph development! I wasn’t even looking, but a friend mentioned it and when I read the job description … well it was just too good of a fit.

Do you find yourself building Bots? Are you excited about integrating Microsoft Graph data into line of business applications? Are you extending Teams with your custom application? Are you spending time with SharePoint or Azure Active Directory? Find yourself excited about the latest Microsoft Graph schemas? … Use tools like curl and OAuth? Spend your free time pouring over the latest research on collaboration software?

Yes, yes, yes to all of the above! Me, pick me! And I’m thrilled that they did!

What is this new job?

The Cloud Advocates team is technically in the Azure organization, ultimately reporting to Scott Guthrie, which is prety exciting in itself. The goal (as well as I understand it on my very first day!) is to help developers succeed in the Microsoft cloud – all developers, from enterprises to partners to startups to students. Recently, the Cloud Advocates team expanded beyond Azure to also include Power Platform, and now Microsoft 365.

In this new role I expect to be:

  • Creating written content, videos, and samples that help people learn how to develop collaborative apps using Microsoft 365.
  • Speaking at conferences, meetups, coding boot camps, online forums, Twitter, Stack Overflow, Hacker News, and more.
  • Collecting and prioritizing product feedback and technical blockers with engineering.

So it’s not that different than what I was already doing, right? But on a larger scale. And some things I was doing on an extracurricular basis will become part of my day job, which is awesome.

I’m extremely thankful, especially in such challenging times, to have such a wonderful opportunity. Many thanks to all my colleagues in the One Commercial Partner Technical Team (OCPTT), and to all the awesome partners I’ve gotten to work with over the last 2 1/2 years. It’s been a lot of fun and I’ve learned so much from you all! I look forward to continuing to work with you as part of my new role.

And to all my friends in the wonderful SharePoint/M365 community – I hope to see more of you all than ever and work together on exciting new developer scenarios. The journey is only beginning!

Working from home with Microsoft Teams

While the world has been adapting to unprecedented changes due to the novel coronavirus pandemic, I’ve been counting my blessings. My family and I are all OK (so far at least!) and I have a job I love where I was already working from home. I was interviewed for the job using Skype for Business, and now my team works almost entirely using Microsoft Teams.

So at my manager’s suggestion, and in accordance with the internally published company policies on social media, my teammates and I decided to pitch in and share our favorite tips for working from home with Microsoft Teams. These are not official videos from Microsoft; they’re from some Microsoft employees acting as members of the community with a sincere desire to help out.

I made a playlist of our videos and am pleased to share it here. I’ll continue to add to this list over the coming weeks. All videos are short – 2-8 minutes – so if you’re busy but hungry for knowledge, you can just stop by for a snack-sized nugget and when you’ve had enough, put it aside and come back later.

Teams WFH Playlist

Continue reading

YouTube Grand Opening

I’m thrilled to announce that in addition to this blog, I’ve started creating short YouTube videos on Microsoft Teams, SharePoint, and Azure development. At first I was going to put everything on my own YouTube channel, but I’m thrilled that I was invited instead to post them on the Microsoft 365 Patterns and Practices channel. I consider it an honor, and it’s a great opportunity to reach nearly 16,000 SharePoint and M365 developers!

I’ll list my videos across all channels on the Videos page in this blog.

Here’s a video to get you started!

Continue reading

Building Microsoft Teams apps with SharePoint Pages – Part 2, Build your Own

This is Part 2 of a 2-part series which will show you how to make Teams applications using modern SharePoint pages. It’s not about the SharePoint Framework, which is a great option, but one that requires coding. This is the easy approach: if you can edit a SharePoint page, format a list, or make a Power App, you can make a Teams app.

Of course there are built-in tabs to allow adding a SharePoint page or PowerApp to Teams, but there are a number of advantages to building a proper Teams app:

  • You can distribute and manage it centrally in the Tenant App Catalog
  • Users can install it by name – no need to configure a website or Power Apps tab
  • You can use app policies to set permission and target the app to the users who need it, and optionally pin it to the Teams sidebar
  • You can be a hero for building a cool app (nobody has to know how easy it was!)

PART 1 – Introduces the Get Started app and explains Teams Tab principles

PART 2 (this article) – Shows how to use Teams App Studio and a new Tab Configuration web part to build your own static and configurable tabs

NOTE: This article has been updated to resolve issues where SharePoint pages were not displayed, especially in the desktop client. If you built apps using the original article, please update your solution using these instructions. Thanks!

App Studio

Github was a good way to share the Get Started app, so anyone can get a copy and adapt it to their needs. But if you’re starting a new app, especially a simple one based on SharePoint pages, you might like to skip the JSON and go to a tool called App Studio.

App studio is itself a Teams app (how meta!) – and it includes a great manifest editor. You can install apps right from App Studio for testing, and then export the app package for installing into the tenant App Catalog.

Here are the installation instructions.

Begin by selecting the Manifest Editor tab and create a new manifest. The editor will open, where you can enter the app details.

SPTabAppStudio001

Scroll through all the details and fill them in; details about each entry are in the manifest schema. Continue reading

Building Microsoft Teams apps with SharePoint Pages – Part 1, Get Started

This is Part 1 of a 2-part series which will show you how to make Teams applications using modern SharePoint pages. It’s not about the SharePoint Framework, which is a great option, but one that requires coding. This is the easy approach: if you can edit a SharePoint page, format a list, or make a Power App, you can make a Teams app.

Of course there are built-in tabs to allow adding a SharePoint page or PowerApp to Teams, but there are a number of advantages to building a proper Teams app:

  • You can distribute and manage it centrally in the Tenant App Catalog
  • Users can install it by name – no need to configure a website or Power Apps tab
  • You can use app policies to set permission and target the app to the users who need it, and optionally pin it to the Teams sidebar
  • You can be a hero for building a cool app (nobody has to know how easy it was!)

PART 1 (this article) – Introduces the Get Started app and explains Teams Tab principles

PART 2 – Shows how to use Teams App Studio and a new Tab Configuration web part to build your own static and configurable tabs

NOTE: This article has been updated to resolve issues where SharePoint pages were not displayed, especially in the desktop client. If you built apps using the original article, please update your solution using these instructions. Thanks!

Any SharePoint page can be a Teams Application

At events around the world lately, Karuana Gatimu has demonstrated a Get Started application that displays the Microsoft 365 Learning Pathways portal right in Microsoft Teams. Users who are new to M365 and need a little instruction can click on the app and gain access to a rich training portal.

LearningPathwaysInTeamsThe Learning Pathways training portal is right at the top of the Teams sidebar

Continue reading