The blog of Wictor Wilén

Microsoft Teams Tabs SSO and Microsoft Graph - the "on-behalf-of" blog post

Tue, 21 Apr 2020 12:54:08 GMT

Hey, I'm back. Long time since I did some writing on this blog. But I needed to get this one out. As you all know I'm a huge fan of the Microsoft Teams extensibility model and now with the SSO support for Tabs, it's even easier to create integrated experiences for your end users where they can consume data and information from the Microsoft Graph or LOB systems.

I recently did a small appearance at the Microsoft 365 PnP webcast showcasing how to configure and scaffold a Microsoft Teams project that uses this new SSO Tab feature. You can watch the recording here:

I've also documented the whole process at the Microsoft Teams Yeoman generator wiki.

One thing I did not show in that video or in the tutorial is how to access other services. The Tab SSO feature (microsoftTeams.authentication.getAuthToken) in Microsoft Teams gives you a token, but this is just an identity token that cannot be used as an access token to call into the Microsoft Graph - despite we grant permissions on the Tab app in the tutorial.

If we inspect the token we get from Microsoft Teams, using https://jwt.ms, we see the following:

Let's focus on the highlights. aud is the intended audience of the token and in this case it's the Application ID URI of my Tab, as defined in the tutorial. appid is the application id of issuing application - in this case the Microsoft Teams web application. You also see the name of the user to whom the token was issues - and that's what we use when typing out our text in the Tab, and finally we do have the scp/scope we created.

As I said, we cannot use this token to talk to Microsoft Graph or any other services. But how do we do that?

Exchanging the token using an on-behalf-of flow

In order to be able to call into Microsoft Graph we need to use the token we have, that ensures our identity and use some server side code to do an OAuth 2.0 on-behalf-of flow. This means that we take the token we received from Microsoft Teams and send to a service, that accepts the aud claim and then uses this token to exchange that for another token for a set of specified scopes using a client secret. We can then use this newly generated token to call into the services, allowed by the app registration and scopes.

To show you how this is done, I'll use the exact same demo as shown in the linked tutorial from the Yo Teams wiki. Note that this demo is in node.js, using npm packages - but the process is the same for all platforms.

Preparing the Azure AD Application

Before we start writing any code let's go to our Azure AD application and do two things;

First we need to create a client secret which will be used during the on-behalf-of flow (Certificates & Secrets > New Client secret). Store the newly created secret in a secure location
Secondly we will do an admin consent of the permissions grants ( API Permissions > Grant admin consent for <tenant>). In a production scenario you might want to manage this in your application/tab instead and redirect the users/admins to a consent page.

Since we're only going to read the user photo from the user in this demo, there's no need to add additional scopes as we already have added User.Read.

Building a custom web service for the on-behalf-of-flow

In my application I will use the passport and passport-azure-ad modules to secure my endpoints and we need to install those modules. We also need the axios and querystring modules for our demo.

npm install passport passport-azure-ad --save
npm install @types/passport @types/passport-azure-ad --save-dev
npm install axios querystring --save

Once we have this we can define a new Express router that will expose a web api that will accept the identity token, use the token and convert it to an access token that can be used by Microsoft Graph and then finally call into the Graph and return the results.

You will find all the code in this repo and I'll only repeat some of the code in this post: https://github.com/wictorwilen/teams-sso-tab-demo

The web API

Under the ./src/app folder I create a new folder called api in which I create a new file called graphRouter.ts. This file exposes one single api (GET /photo). The router itself is also added to server.ts so it is properly loaded by Express.

 router.get(
  "/photo",
  pass.authenticate("oauth-bearer", { session: false }),
  async (req: express.Request, res: express.Response, next: express.NextFunction) => {
    ...
});

As you can see this request is passed through a passport Express handler. This handler is configured further up in the file. A BearerStrategy is configured to only accept incoming authorization tokens that has the correct client id and audience (the client id and application id URI for my Tab) - any other tokens will be denied. The handler will also decode the token and add the tenant id, user name and upn to the request object for our convenience.

In order to exchange this identity token for an access token that gives us access to the Microsoft Graph we use a helper method in the router method.

const accessToken = await exchangeForToken(user.tid,
  req.header("Authorization")!.replace("Bearer ", "") as string,
  "https://graph.microsoft.com/user.read"]);

The helper method uses the tenant id, the incoming token as well as an array of scopes to exchange that for a new access token. The helper method itself uses this information together with the client id and the client secret we created to request a new token. You can see the full method on Github. Essentially it uses this together with a specific grant_type and request_token_use=on_behalf_of parameters to request the token from a Microsoft Azure AD OAuth v2 endpoint.

The token we receive back should look like below, where you can see that the aud now indicates Microsoft Graph and that we do have the required scopes to read the user photo.

Now all that is left is to fire away the query to the correct Microsoft Graph endpoint and use the access token we received from the helper method.

The Tab should now be able to use this client side and retrieve the photo of the user from Microsoft Graph, without the need of signing in on all platforms (desktop, mobile and web).

You can see the the API call here and the React implementation here.

Good luck have fun!

Version 2.7.0 of the Microsoft Teams Apps generator is now available

Wed, 17 Apr 2019 22:07:14 GMT

Happy Easter everyone, I have fantastic news. After seven preview versions (and even a skipped version - 2.6) the Microsoft Teams Apps Yeoman generator 2.7.0 is now available for you to use! Just like tons of others do; there's been over 6.000 downloads of the generator, it's generating a handful of new Teams projects every day and it's done from all parts of the world! Join the movement!

As usual it is just a simple npm command to install:

npm install generator-teams --global

What's new?

Version 2.7.0 contains quite a few updates, changes, additions and fixes. For all the details please study the CHANGELOG. But here is a summary of the more important updates.

Support for Microsoft Bot Framework 4 - this is one of the more substantial changes. The default scaffolded bot looks very different, using the new Bot Framework 4 and the sample bot created contains some examples for you to build on. Note that the middleware for Microsoft Teams is still in beta.
Message Extensions middleware - as the time of publishing this there's no support in the Microsoft Teams Bot middleware for message extensions and to make the code easier to read and extend a dedicated middleware is used to manage message extensions. This middleware is available as a standalone npm package. The automatic configuring of the Message Extensions are handled by the express-msteams-host package, and see it's documentation for all the details.
Microsoft Teams schema 1.3 - the default schema is now 1.3, but also the devPreview schema is supported for validation.
Restructuring of artefacts - from this version and forward each artefact will be scaffolded into its own folder in order to make them easier to manage and find in a larger Microsoft Teams Apps project.
Dynamic generation of the manifest - the manifest file created by the generator will now have placeholders for things such as the host name, bot id's and connector id's and more. The value of these placeholders are either defined in the .env file or in the application settings and will be replaced when building; gulp build, gulp serve or in the case of the manifest gulp manifest.
Improved generated code - all code is now properly linted and linting support is also added to the generated project. This also resulted in that the default casing of files and class names has changed to support the linting.
Test support - when scaffolding a project you now have the option of specifying to include test framework and sample tests (for now only Tabs) using Jest and Enzyme. Huge thanks to Çağdaş Davulcu for helping out with this task.
Bug fixes - yes, we found a few bugs and squashed them!

What about updating?

Since this is a generator, it generates the skeleton code for your Teams Apps, there's no way to upgrade an already scaffolded project using the generator. If you want the latest and greatest, you should create a new project. Then migrate over your existing customizations. Remember to copy over the application id from your old manifest to the new one.

What's next?

All very nice updates and new features! And now we're looking forward and are already planning the next version! What do you want to see?

We've updated the Github repo with a set of Issue templates to support feature suggestions as well as a project board where we start to manage the features.

Also, if you want to be part of the communication, planning and writing some awesome software - join us on Gitter.

#yoteams

Returning to Vegas for SharePoint Conference 2019

Thu, 13 Dec 2018 10:23:00 GMT

I’m excited to be returning to Las Vegas in May of 2019 to speak at the SharePoint Conference 2019 in May 21st to 21rd, at the MGM Grand.

This event is one of the two major events, second one being Microsoft Ignite, that the SharePoint, OneDrive and Yammer product groups are announcing their greatest and latest features and also where you will meet some of the finest speakers and community members of our great SharePoint family.

There will be over 200 session giving you all things you need to adopt, build and manage SharePoint Online and if that is not enough there’s even three days of Workshops, more than 20 of them, with even more deep dives into SharePoint, PowerBI, PowerApps, OneDrive – delivered by amazing speakers.

Full Page Apps in SharPoint Online

The session I will be presenting is about how to Build Full Page Experiences in SharePoint Online. We have for a long time build complete and full applications in SharePoint; sometimes as huge Web Parts, sometimes as sweet JavaScript injections and back in the days we could create application pages to create solutions that was a full page experience. In SharePoint Online this functionality has been quite limited, even though i blogged years ago on how to do this using a Sandbox solution (still an article that drives traffic!) . This kind of experience often goes under the name of a SPA (Single-Page-Application).

This session will cover all the different options we have of creating these full page experiences in SharePoint Online, using SharePoint Framework Web Parts, zones and page designs. We will of course, if you know me, spend most of the time looking at the code, but also discuss different strategies on when to use which method. And last but not least, given the announcements on how SharePoint Framework and Microsoft Teams can be used together, this will be a topic that we’ll cover.

It’s been a few years since I presented at the SharePoint conferenes, and it’s always been a blas, remembering one session where we spent an additional 90 minutes of QnA. Bring all of your questions you have on this topic (and of course anything else you think I or other speakers can help with) and get your answers – there’s no better way for you to get value from this conference than getting answers to your questions.

There is still a few more months to go until May and I’m looking forward to be able to modify the session to incorparate all the latest and greatest features in this area. We’re living in an Evergreen world so this session will be as fresh as possible when delivered – so you have to be there! For the latest updates on the sessions content you can always go to the session page at the SPC19 site: https://sharepointna.com/#!/session/Build%20Full%20Page%20Experiences%20in%20SharePoint%20Online

(I know it is currently tagged as an IT-Pro, we’ll fix that, so we can make fun of the IT-pros for realz during the session)

Register and save $50

Talking of being there, if you have yet not signed up for the conference, you should do it right now. And I can save you $50, that you can spend on gifts to your family for the holidays seasons coming up. Go to https://askwictor.com/SPC19 to register with my discount code WILEN (my awesome last name in all caps – and extra bonus for a correct pronounciation) and you will get a $50 discount. And even better, if you do it before the 15th of January you will get an XBox, a Surface Go or other cool stuff depending on your selected package.

I hope to see you there, in my session! Happy holidays from Sweden, where the snow now has started to fall!

Creating a Bot for Microsoft Teams using Microsoft Flow

Fri, 02 Nov 2018 17:34:44 GMT

Imagine you want to create a chat bot for Microsoft Teams in order to automate tasks, enhance the discussion or just feeling lonely and want someone to talk to. There’s many ways of doing this; you can start from scratch building a bot, using the Microsoft Bot framework and/or using the Microsoft Teams Yeoman generator, you can use the Azure Bot Service, you can use the FAQ bots to essentially create a no code solution.

But, what if you need some logic to happen with your bot, what if you’re not that adverse in coding or have all the skills to build something using Microsoft Cognitive Services, such as language understanding and what not. What if you could use Microsoft Flow to automate tasks, initiated from a conversation in Microsoft Teams?

Then this is your lucky day, you can do this almost without any code (more on why a little bit later) and be up and running within minutes – and also without involvement of any admins that needs to approve of your solution!

The Flow!

First of all we need a Microsoft Flow to do the stuff we want to do. In this sample I’ll create a bot that I can use in a Teams discussion to create a task in my Microsoft To-Do task lists. The Flow is very simple and consists of one HTTP trigger (When a HTTP Request is recieved) and then a task that add a task to To-Do.

You should copy and store the URL, generated in the HTTP trigger upon save, as we will need that for our bot in just a minute.

For now the Subject is static, but for the Body Content I use the text property of the incoming JSON – that will be sent from the Microsoft Teams client. I use the Dynamic Expression to get text from the Teams message:

triggerBody()['text']

NOTE: If you want more help with what properties you can use, such as creating a link to the original message, you can use the HTTP trigger and import a sample paylod found in the Microsoft Teams documentation. However currently that page is not up to date with the latest schema, so the best way is to make sure this sample works, and then just take a look at the Flow history and copy-paste the JSON from a successful run.

Creating the Microsoft Teams bot

To create the bot in Microsoft Teams we take advantage of the feature called Outgoing webhook. This is a somple way that allows you to send an outgoing message when at-mentioning the bot in a Microsoft Teams team (there’s no personal equivalent at the moment). You can add a new outgoing webhook by going in to the Team settings and then click on the Apps tab. In the lower right corner you will find the link called “Create an outgoing webhook”. Click on that one to create it.

In the dialog that appears you need to fill in the name and description of your outgoing webhook (bot) and optionally upload an icon. What you also need to do is to add the Callback URL. Let’s add our URL generated for the MIcrosoft Flow and give it a shot.

When you click on create, you will get another popup with some vital information. It contains a security token, used for validating the message. This is the only time you will see it and if you forget it you have to create a new outgoing webhook. So copy-paste this into a notebook or remember it, you will need it shortly.

Let’s try this

So, now we should be able to chat to our outgoing webhook/bot by at-mentioning it in a channel in the Team where we added it.

Hmm, that was not what we expected, and this is where a lot of people have stopped trying this approach. It’s not that unexepcted though. Remember I just said the outgoing webhook has a security token, that we should validate, and also the Microsoft Flow does not send any message (JSON) back.

Azure Functions to the rescue

In order to get this to work, we need to smack some code up in sort of a proxy, that will sit between the outgoing webhook and the Microsoft Flow. The easiest and probably cheapest way is to use Azure Functions. So let’s do that.

Let’s create a new Azure Function, using the JavaScript runtime stack (if you prefer .net, it’s not my problem and you have to spend the time on your own writing the code). When creating the Azure function I choose to use HTTP Trigger (just as we did for the Microsoft Flow).

In this Azure Function we can now write some code that

Accepts the webhook coming from Microsoft Teams
Validates the Security Token (HMAC)
Invokes the Microsoft Flow
Sends a response back to the user

All the code you need can be found in this Gist: https://gist.github.com/wictorwilen/8ac6f9c167d70e4774e20f3c39a47a55. You need to do two modifications.

On line 4 you need to add your Security/HMAC token generated when you created the outgoing webhook
On line 5 you need to add the webhook URL for your Microsoft Flow

Since this example uses the request npm module, which is not by default installed in an Azure Function you need to go in to the Console located at the bottom of the Azure Function code editor and run

npm install request --save

Note: for production and real scenarios you might not want to build your Azure function directly in the Web UI and you should have a package.json file so any npm modules are properly restored.

Then, just save the Azure function and go back to Microsoft Teams and the same location where you created your outgoing webhook. Click on the outgoing webhook you created to edit it and then change the URL to the Azure Function URL (found next to the Save and Run buttons in the Azure Function code editor - Get function URL).

Let’s try it again

Head on back over to Microsoft Teams and into a channel, now try to at-mention the bot again!

Look at that! It’s working. I can even go over to To-Do and see that I have a new task!

Next steps…

This was the basics on how to get things working. You can of course make the bot far more advanced by injecting more logic to the Microsoft Flow (obviously) but also into the Azure Function. For instance you might want to invoke different flows, depending on the message. You have full access to the JSON in the Azure Function to do this.

One caveat is that right now you only have access to the message where the bot was at-mentioned. Hopefully Microsoft Flow gets some more Microsoft Teams features so we can extract the full conversation. Meanwhile you can always use the Microsoft Graph, but that involves a few extra steps for app permissions etc.

Summary

This approach has already today saved me and my team from having to manually do some steps in our daily routing, by simply at-mentioning a bot in our conversation. What cool stuff are you building with this?

Announcing Microsoft Teams Apps Yeoman generator 2.5.0

Fri, 17 Aug 2018 12:40:52 GMT

A long overdue update of the Microsoft Teams Apps Yeoman generator – we’re now up to version 2.5.0! It’s a fairly substantial update both in the generator and in the generated code – this update will make future updates a lot smoother and will allow for enabling more features going forward. Thanks to all who provided feedback and input and has tested the generator over the last few months.

You can get the latest generator by running

npm install generator-teams@latest –global

Generator updates

The actual Yeoman generator has been refactored and changed so that it used TypeScript AST (abstract syntax tree) to dynamically generate some of the TypeScript files. This will open up for adding new artifacts to existing projects without having to do weird string and text file parsing. We’ve also refactored some generated files out to separate npm packages, so that those files and controls can be updated without you having to manually update files or generate new solutions – more about this below.

Solution updates

In order to improve the generated app we have moved some of the generated files, controls and base classes into separate npm packages. This allows you to get the latest and greatest in these packages with just a simple npm command – and not having to manually copy and paste.

The generated solution is hosted in a node.js Express server and the new generated solutions will dynamically discover what components and extensions you have in your solution and automatically register the different routes. All this is done by using TypeScript decorators and Express routes that are defined in the express-msteams-host npm package. Previous versions of the generator had a quite complex server implementation and since it was scaffolded by the generator it was close to impossible to update with new features or fixes. Now all you have to do is decorate your bots, connectors and outgoing webhooks with these decorators and their routes will automatically be picked up and registered. For more information, see the documentation.

A similar approach has been taken to the clients side of the generated solution. A few releases ago the UX was moved to leverage the Microsoft Teams React controls, and with this version we’ve moved the base page class (previously generated by the generator) into a separate npm package called msteams-react-base-component. Similar story here, this will make it way easier for everyone to consume updates to this component without running the generator again.

Of course there are plenty of more stuff that has been fixed or refactored such as; the build pipeline that has been upgraded to Gulp 4 and Webpack 4 and improved logging in the generated solution using the debug module – and you can read about the other changes in the change log.

What next?

It’s exciting times in Microsoft Teams Apps land! We now have a corporate store for Teams Apps, we’ve seen that the SharePoint and Microsoft Teams product groups are having secret meetings to improve the integration between (my favorite) two services. I’m of course looking into this and will share some exciting updates when we close in on more public reveals of features – Microsoft Ignite mayhaps. Oh, if you’re at Microsoft Ignite, try to find me somewhere in a Theater session or lurking in the SharePoint and Microsoft Teams booths if you want to discuss the generator.

#yoteams

SharePoint Framework and Microsoft Graph access – convenient but be VERY careful

Tue, 03 Apr 2018 11:18:59 GMT

SharePoint Framework (SPFx) is a fantastic development model on top of (modern) SharePoint, for user interface extensibility, and it have evolved tremendously over the last year since it became general available. The framework is based on JavaScript extensibility in a controlled manner, compared to the older JavaScript injection mechanisms we used to extend (classic) SharePoint, that comes with a lot of power.

Using SharePoint Framework our JavaScript has access to the whole DOM in the browser, meaning that we can do essentially what we want with the user interface – however, of course, we shouldn’t, only certain parts of the DOM are allowed/supported for modification. These areas are the custom client-side Web Parts we build (that squared box) or specific place holders (currently only two of them; top and bottom). For me that’s fine (although there’s a need for some more placeholders), but if you want to destroy the UX it is all up to you.

In our client-side solutions we can call out to web services and fetch data and present to the user and even allow the end-user to manipulate this data. For a while now we’ve had limited access to Microsoft Graph, where Microsoft has done the auth plumbing for us, and now in the latest version (1.4.1) a whole new set of API’s to both call Microsoft Graph, with our own specified permission scopes, and even custom web services protected by Azure AD. Very convenient and you can build some fantastic (demo) solutions with this to show the power of UX extensibility in SharePoint Online.

However – there are some serious security disadvantages that you probably don’t think or even care of if you’re a small business, a happy hacker or just want to build stuff. For me – designing and building solutions for larger enterprises this scares me and my clients…a lot!

Some perspective

Let’s take a step back and think about JavaScript injections (essentially SPFx is JavaScript injections – just with a fancier name and in a somewhat controlled way). It’s all very basic things, but from recent “social conversations” it seems like “people” forget.

JavaScript running on a web page, has all the power that an end-user has, one could say even more power, since it can do stuff the user doesn’t see or is aware of. I already mentioned that JavaScript can modify the DOM – like hiding, adding or moving elements around. But it can also execute code, that is not necessarily visible. A good example is for instance to use Microsoft Application Insights to log the behavior of the user or the application – seems like a good thing in most cases (although I don’t think that many users of AppInsights understand how GDPR affects this – but that’s another discussion). We could also use JavaScript to call web services, using the information we have on the page to manipulate the state of the page, and also send data from our page to another page. All without the user noticing it. For good or for bad…let’s come back to the latter in a minute or so.

No Script sites and the NoScript flag

Before SharePoint Framework Microsoft introduced “No Script” sites to mitigate the issue with arbitrary JavaScript running in sites and pages. All modern Team sites, based on Office 365 Groups, and OneDrive sites are No Script sites. You can as an admin control the behavior of newly created SharePoint Sites using the settings in the SharePoint admin center (under settings):

Depending on when your tenant was created (before or after the addition of this setting) your default settings may be different. My recommendation is, of course, to Prevent users from running custom scripts, to ensure that you don’t get some rogue scripts in there (see below).

This setting can also be set on individual sites using the following SharePoint Online PowerShell command:

Set-SPOsite https://contoso.sharepoint.com/sites/site 
-DenyAddAndCustomizePages 0

More information here: “Allow or prevent custom script”

This setting on a site not only affects JavaScript injections it also prohibits the use of Sandbox solutions and the use of SharePoint Designer – all good things!

Script Editor Web Part – the wolf in sheep clothes

“Our favorite” SharePoint extensibility mechanism, specifically for the citizen developers (or whatever you prefer calling them), has been the Script Editor Web Part (SEWP). As an editor of a site in SharePoint we can just drag the SEWP onto a page and add arbitrary scripts to get our job done and we’re done.

The aforementioned No Script setting will make the Script Editor Web Part unavailable on these sites.

The Script Editor Web Part does not exist in modern SharePoint. The whole idea with modern SharePoint and SPFx is that we (admins/editors) should have a controlled and managed way to add customizations to a site – and of course SEWP is on a collision course with that. Having that option would violate the whole idea.

You can read much more about this in the SharePoint Patterns and Practices article called “Migrate existing Script Editor Web Part customizations to the SharePoint Framework”.

But, there is now a “modern” version of the Script Editor Web Part available as a part of the SharePoint Patterns and Practices samples repository (which is a bit of a shocker to me). This solution is bypassing the whole idea of SharePoint Framework – controlled and governed JavaScript in SharePoint Online. And of course this is being used by a lot of users/tenants – since it’s simple and it works. If you do use this solution you really should continue reading this…

SharePoint Framework and Microsoft Graph = power?

How does this relate to SharePoint Framework then? As I said, with SharePoint Framework we now have a very easy way to access the Microsoft Graph (and other Azure AD secured end-points) with pre-consented permission scopes. As a developer when you build a SharePoint Framework solution you can ask to be granted permissions to the Microsoft Graph and other resources. The admin grants these permissions in the new SharePoint Online admin center under API management.

For instance you want to build a Web Part that shows the e-mail or calendar on your portal page, you might want to have access to read and write information to tasks. The possibilities are endless and that is great, or is it?

I think this is a huge area of concern. Imagine these user stories:

“As a user I would like to see my calendar events on my Intranet” – pretty common request I would say. This requires the SPFx Web Part developer to ask for permissions to read the users calendar.

“As a user I would like to see and be able to update my Planner tasks” – another very common request. This requires the SPFx Web Part developer to ask for Read and Write access to all Groups (that’s just how it is…).

Both these scenarios opens up your SharePoint Online solution for malicious attacks in a very severe way. Of course the actual permission has to be approved by an admin – but how many admins do really understand what’s happening when the business cries “we need this feature”.

Note: this is not just a SharePoint Framework issue, but SPFx makes it so easy that you probably don’t see the forest for the trees. And this is also true for many of these “Intranet-in-a-box” vendors that has made their similar service to access mail/calendars etc from the Graph. It’s still JavaScript and if you allow a single user to add a script it can be misused.

Rogue scripts

Once you have granted permissions to the Microsoft Graph, by a single request from that fancy calendar Web Part, all other scripts in the whole tenant has those permissions. So your seemingly harmless Web Part has suddenly exposed your calendar for reading to any other Web Part. Assume that now the admin installs a weather Web Part (downloaded or acquired from a third party). This weather Web Part is now also allowed to read the users e-mail, even though it did not request it. And if that vendor goes rogue or already is, he or she can without the users knowing send all the calendar or e-mail details away to a remote server, while just displaying the weather. This requires some social engineering of course to make the admin install this Web Part. But what about allowing the modern Script Editor Web Part! And you piss an employee off…with just some simple JavaScript knowledge this user can then create a sweet looking cat-of-the-day web part or even a hidden one with the Modern Script Editor Web Part. Then send the boss to that page, and read all the bosses calendar events or e-mails, sending them to some random location somewhere…

You still think this is a good idea?

And what about the second user story; where we need full read and write to all the groups, just to be able to manipulate tasks in Planner. It’s not much you can do, if you’re building this web part – you are opening up for so many more possibilities for “working with” groups and its associated features. This is not a SharePoint Framework thing, but a drawback in how Microsoft Graph works with permissions and the lack of contextual or fine-grained scopes in Azure AD. Same goes for reading/writing data from SharePoint sites – Azure AD/Microsoft Graph cannot restrict you to a single site or list – you have access to all of them.

Remember how SharePoint Add-ins have Site Collection or list scoped permissions. I guess you all remember how we complained back then as well. That was some sweet days and we really want those features back. Well, we still have them – SharePoint add-ins are probably the best way to protect the users and your IP still…

As I stated above, of course all SPFx solutions has to be added to the tenant app catalog – but, we also have the option of a site collection scoped catalog. So that’s another vector for insertion of seemingly nice solutions that can take advantage of the permissions you granted on a tenant level.

The grey area between modern and classic sites

Currently most SharePoint Online tenants is in a transition period between classic and modern sites. That is, they have built their SharePoint Online environment based on the “classic way” of building stuff, most often requiring script enabled sites. And now they want to transition to modern sites, without these scripting capabilities. Should they just add the new modern Script Editor Web Part or should they turn of scripting for all sites?

If you turn this off I can almost guarantee that a lot of your sites will be useless. And in many cases your whole Intranet – specifically this happens with many of the “Intranet-in-a-box” vendor solutions. So be careful.

So, what should I do?

If you still think it is very valuable to build solutions with SPFx and Microsoft Graph the first thing you MUST do is to ensure that there is not a single site in your tenant with scripting enabled. You can do a quick check for this with this sample PowerShell command:

 get-sposite | 
  ?{$_.DenyAddAndCustomizePages -eq 'Disabled'}

This will list all the site collections which still allow JavaScript execution using the Script Editor Web Part for instance. If there’s a single site in here, stop what you’re doing and don’t even consider granting SPFx any permissions.

I wish we had this kind of notification and warning in the permission grant page in the new SharePoint Admin center. To make it very obvious for admins.

Secondly, be very thoughtful on what solutions you are installing in your app catalog. Do you know the vendor, do you know their code, is their code hosted in a vendor CDN (warning signs – since they can update this without you knowing) etc? Do you have multiple vendors? Who have access to do this?

So, you really need to do a proper due diligence of the code you let into your SharePoint Online tenant.

A note on the CDN issue; when you add a SPFx solution to the app catalog all “registered” external script locations are listed. But this is not a guarantee. It’s only those that are registered in the manifest. As a developer you can request other resources dynamically without having them show up on this screen.

Summary

I hope that this gave you the chills, and that you start reflecting on these seemingly harmless weather web parts that you install. You as an admin, developer or purchaser of SharePoint Online customizations MUST think this over.

Do we have a plan to move from script enabled sites to ALL sites with no custom scripts enabled
Do we have the knowledge and skill to understand what our developers and vendors are adding to our SharePoint Online tenant
Do we understand the specific permission requirements needed

I also hope (and know) that the SharePoint Framework product team listens, this is an area which needs to be addressed. We want to build these nicely integrated solutions, but we cannot do it on behalf of security concerns. And it’s NOT about security in SharePoint or SharePoint Framework it is about how web browsers work. What we need is:

Visibility – make it visible to the admins what is really happening in their tenant; script enabled sites, SEWP instances etc.
Isolation – we need to be able to isolate our web parts, so that they and their permissions scopes cannot be intercepted or misused. In the web world I guess that Iframes is the only solution
Granularity - Azure AD permission granularity – it’s not sustainable to give your applications these broad permissions (Group Write All). I want to give my app access to write in one Planner plan only and not in all groups.

Thanks for reaching the end! I oversimplified some parts, but if you have any concerns, questions or issues with my thinking – don’t hesitate to debate, confront, question or agree with this post.

Finally! Proper custom themes in SharePoint Online!

Mon, 02 Oct 2017 13:32:00 GMT

Microsoft Ignite is just around the corner and the sheer number of new announcements for SharePoint and SharePoint Online has been almost overwhelming. The team is making such a tremendous job right now!

One of my favorite features, that I have requested both privately and openly with Microsoft, is the ability to have custom themes for SharePoint. Yes, we had the old “look and feel” thing, custom CSS thing, Office 365 suite bar branding, but there has never been a good way of using this in Modern sites or even the possibility to turn of the default themes. And now, last week, Microsoft announced a new set of features that can do all of this for us – create custom themes, a nice theme designer and the ability to hide the default themes.

Let’s go through how this works (note that the feature is not currently available in all tenants)…

How to add your own themes

By default in Modern sites (Teams, Communications and Hub sites) in SharePoint Online you are given a set of default themes (Blue, Orange, Red, Purple, Green and Gray), which can be changed through the cog wheel settings menu in the suite bar and then choose Change the look.

In order to create your own Theme, you go to the theme builder at aka.ms/spthemebuilder. Using this tool you can create a theme visually and then get a set of snippets to be used in PowerShell to add the theme to your tenant.

Once you have created your theme, all you need to do is to fire up your SharePoint Online PowerShell window and start writing some PowerShell. Make sure that you have the latest version of the SharePoint Online Management Shell.

First of all you need to connect to your SPO tenant:

Connect-SPOService -Url https://contoso-admin.sharepoint.com

While the theme builder has a great feature that allows you to export the PowerShell settings required to create your theme, it does not really work (at least not in the builder and the shell versions that exists at the time of writing this blog post). The theme builder PowerShell generates a Hashtable but the PowerShell command requires a Dictionary object, so here's a quick way to do that conversion (until they fix the builder and/or the cmdlet).

$builder = [past the PowerShell code from the builder here]
$theme = New-Object "System.Collections.Generic.Dictionary``2[System.String,System.String]"
$builder.Keys | %{$theme.Add($_, $builder[$_])}

Now, that we have a PowerShell variable with our Theme we can use the Add-SPOTheme cmdlet to add our theme, like this:

Add-SPOTheme -Name "Contoso Purple" -Palette $theme -IsInverted:$false

And voilá! We have a new custom theme available:

We can in the same way add more themes, and when we don’t want them anymore we can use the Remove-SPOTheme cmdlet. There’s also a Get-SPOTheme cmdlet that allows you to get a theme by name, unfortunately it is not possible to use that cmdlet without any parameters and list all available ones (feedback SP Team, feedback).

The IsInverted flag is used for dark theme (true) and light theme (false9, so SharePoint knows when to render light text on top of dark and vice versa.

Hide the default ones

An almost as cool feature is that you can actually hide the default themes. Using the Set-HideDefaultThemes cmdlet you can turn the default themes on or off (oh, and I don’t know why this cmdlet is not prefixed with SPO!?)

Set-HideDefaultThemes -HideDefaultThemes:$true

And now you should only see your themes:

If you want the default ones back you just fire off this:

Set-HideDefaultThemes -HideDefaultThemes:$false

More options

[Added] Vesa Juvonen pointed out so correctly that you can do this programmatically as well. You can check the full documentation of this feature here with REST and CSOM options for ya devs.

Summary

The new themes features in SharePoint Online will make it easier to have a consistent look and feel in all your Modern SharePoint sites, and will be a feature that your communications and marketing departments will love.

Using Device Codes to authenticate Bots with Azure AD

Sun, 03 Sep 2017 13:05:24 GMT

I’ve been building chat-bots for a while now and I’m seeing more and more requests of building these bots for enterprises. For bots targeted at the enterprise, perhaps being hosted in Microsoft Teams, one of the first requirements is that they should get data from their internal systems and most specifically from Office 365, through the Microsoft Graph. The problem here is that we need to authenticate and authorize the user, through Microsoft Azure AD, to be able to access these resources. A Microsoft Bot Framework bot, does not inherit the credentials or security tickets from the application the bot is being invoked from, so we need handle this ourselves. For instance, even though you have logged in to Microsoft Teams, or Skype for Business or your Intranet – your security token cannot (and should not) be passed to the Bot.

This is not mission impossible, and there are multiple ways of implementing this. For instance if you’re building Bot Framework bots using .NET you can use the AuthBot and with node.js there’s the botauth module. There’s also other (a bit weird and specialized) ways of doing this by using the backchannel.

All of these are custom implementations with either sending an already existing access token to the bot or using home brewed magic number generators. But, there’s a much simpler way of doing this – using the native and built-in features of the Azure Active Directory Authentication Library (ADAL), specifically using the OAuth 2.0 Device Flow.

In this post I will demonstrate how to create a bot from scratch and use the device flow to sign in and get data from Microsoft Graph. It will all be built using node.js and TypeScript – but the procedure is the same for any kind of environment.

Creating the bot

First of all we need to create a bot using the Bot Framework portal. Give the bot a name, handle, description and specify the messaging endpoint. You can use localhost for testing but in the end you should have a publically available URL to be able to use it in the different Bot channels. In this sample we need to make sure that the messaging endpoint ends with /api/messages. Then you need to create a Microsoft App ID and a password – just follow the wizard and copy and take a note of the ID and specifically the password – you will only see it once. Once you’re done, save your bot.

Configuring the App platform for the bot

The bot created in the Bot Framework portal, is essentially an Application in the Microsoft Application Registration Portal. In order to use this Application ID with Azure AD and Microsoft Graph, we need to log in to that portal and find our newly registered bot and then add a platform for it. In this case let’s add a Native Application. You don’t have to configure it or anything, it just needs to have a platform.

In this portal you can also add the delegated permissions for your bot, under Microsoft Graph Permissions. For the purpose of this demo we only need the User.Read permissions.

Let’s write some code

Next step is to actually start writing some code. This will be done in node.js, using TypeScript and a set of node modules. The most important node modules used in this demo are:

webpack – bundles our TypeScript files
ts-loader – webpack plugin that transpiles TypeScript to JavaScript
express – node.js webserver for hosting our Bot end-point
adal-node – ADAL node.js implementation
@microsoft/microsoft-graph-client – a Microsoft Graph client
botbuilder – Bot Framework bot implementation

All code in this sample are found in this Github repo: https://github.com/wictorwilen/device-code-bot. To use it, just clone the repo, run npm install. Then to be able to run it locally or debug it you can add a file called .env and in that file add your Application ID and password as follows:

MICROSOFT_APP_ID=fa781336-3114-4aa2-932e-44fec5922cbd
MICROSOFT_APP_PASSWORD=SDA6asds7aasdSDd7

The hosting of the bot, using express, is defined in the /src/server.ts file. For this demo this file contains nothing specific, part from starting the implementation of the bot – which is defined in /src/devicecodebot.ts.

In the bot implementation you will find a constructor for the bot that creates two dialogs; the default dialog and a dialog for sign-ins. It will also initialize the ADAL cache.

constructor(connector: builder.ChatConnector) {
    this.Connector = connector;
    this.cache = new adal.MemoryCache()

    this.universalBot = new builder.UniversalBot(this.Connector);
    this.universalBot.dialog('/', this.defaultDialog);
    this.universalBot.dialog('/signin', this.signInDialog)
}

The implementation of the default dialog is very simple. It will just check if we have already logged in, but in this demo we will not set that value, so a login flow will always be started by starting the sign-in dialog.

The sign-in dialog will create a new ADAL AuthenticationContext and then use that context to acquire a user code.

var context = new AuthenticationContext('https://login.microsoftonline.com/common', 
  null, this.cache);
    context.acquireUserCode('https://graph.microsoft.com', 
      process.env.MICROSOFT_APP_ID, '', 
      (err: any, response: adal.IUserCodeResponse) => {
        ...
});

The result from this operation (IUserCodeResponse) is an object with a set of values, where we in this case should pay attention to:

userCode – the code to be used by the user for authentication
message – a friendly message containing the verification url and the user code
verificationUrl – the url where the end user should use the user code (always aka.ms/devicelogin)

We use this information to construct a Bot Builder Sign-In Card. And send it back to the user:

var dialog = new builder.SigninCard(session);
dialog.text(response.message);
dialog.button('Click here', response.verificationUrl);
var msg = new builder.Message();
msg.addAttachment(dialog);
session.send(msg);

This allows us to from Bot Framework channel invoke the authorization flow for the bot. The end-user should click on the button, which opens a web browser (to aka.ms/devicelogin) and that page will ask for the user code. After the user entered the user code, the user will be asked to authenticate and if it is the first time also consent to the permissions asked for by the bot.

In our code we then need to wait for this authorization, authentication and consent to happen. That is done as follows:

context.acquireTokenWithDeviceCode('https://graph.microsoft.com',
   
process.env.MICROSOFT_APP_ID, response, 
  (err: any, tokenResponse: adal.IDeviceCodeTokenResponse) => {
    if (err) {
      session.send(DeviceCodeBot.createErrorMessage(err));
      session.beginDialog('/signin')
    } else {
        session.userData.accessToken = tokenResponse.accessToken;
        session.send(`Hello ${tokenResponse.givenName} ${tokenResponse.familyName}`);
        ...
    }
});

The result from this operation can of course fail and we need to handle that, in this case just sending the error as a message and restart the sign-in flow. If successful we will get all the data we need to continue (IDeviceCodeTokenResponse) such as access-token, refresh-token, user-id, etc. In a real world scenario you should of course store the refresh token, in case the access token times out. And it is also here that we potentially tells our bot that the user is signed in redirects subsequent dialogs to what we want to do.

Now we can use this access token to grab some stuff from the Microsoft Graph. The following code, with a very simplistic approach, where wo do not handle timed out access tokens, we just grab the title of the user and sends it back to the user.

const graphClient = MicrosoftGraph.Client.init({
    authProvider: (done: any) => {
        done(null, session.userData.accessToken);
    }
});
graphClient.
    api('/me/jobTitle').
    version('beta').
    get((err: any, res: any) => {
        if (err) {
            session.send(DeviceCodeBot.createErrorMessage(err));
        } else {
            session.endDialog(`Oh, so you're a ${res.value}`);
        }
    });
    }
});

Run the application

To run the application first we need to transpile and bundle it using webpack like this:

npm run-script build

The we start the express server like this:

npm run-script run

To test it locally we need to use the Bot Framework emulator. Download it, run it and configure it to run at http://localhost:3007/api/messages. Type anything in the emulator to start the sign-in experience

As soon as you’ve written something the Sign-In card will be displayed. When you click on the button a browser window will open and you will be asked to type the code. When you’ve done that you will be asked to sign-in and consent. And shortly after that the bot will come alive again and type the users name and if all works well, also the job title of the user.

If you decide to publish your bot (for instance to Azure, all the necessary files are in the Github repo to Git publish it to Azure) you can also use the bot in other channels, for instance Skype:

Summary

As you’ve now seen. It is very easy to create a simple and elegant sign-in flow for your bots, without sacrificing any security, and all using standard features of ADAL and OAuth. This will nicely work with any Azure AD accounts, with MFA or not.

Re-awarded as Microsoft MVP for the 8th year

Sat, 01 Jul 2017 15:48:20 GMT

Today is the day where the Microsoft community officially award the community with the Microsoft MVP award. We will all receive some new friends and old friends and also we loose some dear friends (that we of course hope to see back into the program again). I’ve been fortunate to be re-awarded with the Office Servers and Services Microsoft MVP award, for the 8th consecutive year. Thank you Microsoft!

As usual, being an MVP is not something you can take for granted and you have to work hard to stay in the program. But all you can do is have fun and share your joy with the rest of the Microsoft community. I really would like to thank my peer MVPs, the community and the Microsoft product teams – specifically the SharePoint and Teams teams. I’ve had tons of fun this year and I’m looking forward to an exciting new year ahead.

yo teams have a new home, and officially backed by Microsoft

Sat, 01 Jul 2017 09:26:00 GMT

A couple of months back I started creating a Yeoman generator to make it easier for me to scaffold, build and deploy the Microsoft Teams extensions (now apps). I’ve received very good feedback on it and had some very nice contributions to the project, which was hosted on my public Github account.

To really make this available for everyone to use I’ve been discussing this project with the Microsoft Teams team about having it “officially backed” by the real team and nut just me as an individual. After some interesting discussions the Microsoft Teams generator now have a new home.

The Microsoft Teams Yeoman generator are now transferred to the OfficeDev organization on Github and lives in this repository: https://github.com/OfficeDev/generator-teams

I think this is great and it will allow more organizations to actually use the generator. We’ve switched to MIT licensing and we added some contribution guidelines to be able to do this move. The rest is intact. All the old links to the repo will now redirect to the new one and you still use npm to install it in the same way.

We have some nice updates coming shortly to it, of which some you can see in the preview branch, that uses all the latest and greatest features of Microsoft Teams Apps.

A big thank you to Bill Bliss who set things in motion and did all the heavy lifting, and of course to all the contributors to the generator and to the great Microsoft Teams team!

#yoteams

How to generate SharePoint Framework bundles for multiple tenants

Tue, 18 Apr 2017 16:00:49 GMT

If you are an ISV or SI with multiple clients and are interested in building SharePoint Framework (SPFx) solutions that you would like to re-use you will face a huge issue when it comes to reference SharePoint JavaScript files and reference your SharePoint Framework bundles. All these URL's are hardcoded into your solution configuration files and requires you to update these files and rebuild for each and every client environment. And not only that even in your own development team this will cause issues if you don't have a shared development environment.

This causes a lot of issues and headaches. Each and every developer needs to update the configuration files in the SharePoint Framework - meaning that they will check-out the files and then eventually check them back in with their specific tenant information, which will break the solution for another developer. Same goes if you want to deploy a solution to another client; you check the files out update with the new client information and the more clients you have the worse it gets.

The SharePoint Framework is essentially built so that you should NOT reference any SharePoint JavaScript files (think CSOM/JSOM) and always host your bundled SPFx files in a public CDN. In practice this doesn't work. There are tons of features in JSOM that you would like to use, such as managed metadata. Also very few clients really want their JavaScripts to be hosted in a location they don't own or have control of.

So, SharePoint Framework as of now is very limited and it is a mess for you as a developer, SI or ISV. I know, that's exactly where I've been, until now!

Introducing the spfx-build-url-rewrite node package

To sort this issue out I've built a node.js package called spfx-build-url-rewrite that helps you re-write those URLs at build time. All it requires is that you in your config files use a specific URL that the package knows about (currently it's contoso.sharepoint.com - I know, I'll make it configurable/better later) and when building you specify the URL you want to replace it with, and voila - you can now automate builds for any number of clients/environments.

How it works

First of all you need to install the node module into your SPFx solution using npm:

npm install spfx-build-url-rewrite --save

Then you need to modify the gulpfile.js to use this module. Just before the initialize method you need to add two lines so it looks like this:

const rewrite = require('spfx-build-url-rewrite');
rewrite.config(build);

build.initialize(gulp);

Whenever you want to reference a script inside SharePoint, such as the JSOM files or you want the SPFx CDN to be in SharePoint you modify the config.json or write-manifest.json files to use https://contoso.sharepoint.com instead of your tenant URL.

config.json

write-manifest.json

Now when you build the solution you append the argument --target-cdn <url> to replace the URLs in your solution, as follows:

gulp build --target-cdn https://fabrikam.sharepoint.com
gulp bundle --target-cdn https://fabrikam.sharepoint.com
gulp package-solution

If you don't want to specify this for each and every command you can create an empty file called .env and specify the substitution URL in it like this:

TargetCdn=https://fabrikam.sharepoint.com

Summary

I hope this small node package makes your life easier, it sure makes mine! If you have any feedback please use the Github repository.

And as a final note, even though it is supported to extend the build pipeline of SPFx this is possibly in the grey zone - but it works…on my machine.

yo teams: a full Microsoft Teams extensibility Yeoman generator

Mon, 27 Mar 2017 22:53:33 GMT

A couple of weeks back I published a Yeoman generator to build Tabs for Microsoft Teams. Since then I've continued to add stuff to it as the Teams team has continued to add features to their extensibility story. So, this generator is not only for creating Tabs, but now also for adding Bots and Custom Bots to Microsoft Teams. With that I decided to rename the generator to yo teams (generator name is generator-teams).

I'm very thankful to the over 600 downloads within less of a month, and all the positive feedback, the issues and PR created. Keep it coming.

What's new?

The two big new features of the generator is the ability to add either a reference to an existing bot that you want to use (your own, or any bot in the Bot Framework directory) or to create a bot from scratch, using the Bot Framework. You can also add a custom bot, which is a Microsoft Teams specific webhook that acts like a bot, which can be used by specific Teams only and you don't have to add it to the Bot Framework - perfect for those internal smart bots you want to build.

The source code has also gone through some heavy refactoring with sub-generators and all. There's more to come…

Both the Bot and Custom bot uses the JavaScript/TypeScript implementations of the Bot Framework and you have some boilerplate code to get started, including readme files of the essentials.

If you have any issues, or feedback, or problem or just feeling chatty, then use the Issues list on Github.

What do I need to do?

If you already used the old generator, uninstall it with npm uninstall generator-teams-tab --global and then install the new generator with npm install generator-teams --global. All your current solutions will work, but I recommend you to, if you feel like it, to "move" all your code over to a newly created project.

The old npm package is deprecated and you will get a warning if you try to install it.

The Github repository has been renamed, but the old one will still redirect you to the correct location. You can find it here: https://github.com/wictorwilen/generator-teams

Congratulations to the Microsoft Teams team on an excellent delivery

Tue, 14 Mar 2017 15:32:17 GMT

A big round of applause for Microsoft and the team behind Microsoft Teams for now being general available (GA) worldwide. Today, they lit up the Teams icon in the Office 365 waffle for all tenants (unless your admins are being boring and has turned it off).

It's been awesome to be a part of this preview journey, which started last summer. Avanade was selected as one of the TAP members, in a preview program shrouded in a secrecy I've not seen at Microsoft before. Our IT department slowly trickled it out, so that we had a chance of learning how Microsoft Teams could fit into our organization and our way of working. A big thanks to David who have mastered the preview program internally.

When Microsoft Teams was unveiled to the public, back in November, we did our first point-of-view based on our experience so far. Since then I would say that the way we work has changed dramatically. Many of our teams and interest groups has quickly adopted this new chat-based workspace - not just for chatting but as the preferred channel for communication and collaboration. It fits our style of work perfectly, given how spread out our teams are and the different time zones we're working in.

Personally I've been way more effective in my work since we started to adopt Microsoft Teams. The number of unnecessary e-mails has gone done dramatically, my inbox is not flooded with simple questions, or links, or things that can more easily be expressed through a chat. One thing that has surprised me is how much more we use the ad-hoc chats compared to what I've expected, we don't all have to be online at the same time - you can easily go back and see what's been discussed while you were away or in a meeting. Sharing of files and notes is so much easier now and it allows us to have an ongoing discussion about them.

It's been a blast discussing Microsoft Teams with my clients. And I'm thrilled that some of them now are leading with "Teams first" - that is you create a Team, not a SharePoint team site, not an Office 365 Group. You get them for free with Teams anyways. This will change the way collaboration is done for enterprises going forward, without doing trade offs for compliance, governance and security.

This is the first release of many to come. And they number of features that has popped up over the last few months are incredible. And I'm sure we will see some more productivity enhancers going forward.

Once again, thank you to the team behind Microsoft Teams.

yo teams-tab: A Microsoft Teams Tabs Yeoman generator

Sat, 04 Mar 2017 13:45:25 GMT

I'm happy to announce that today at SharePoint Saturday Munich I presented a new Yeoman generator for building Microsoft Teams Tabs projects. Tabs in Microsoft Teams is a great way to extend the user interface and to do integrations to other systems and provide visualizations. Tabs are based on a JavaScript framework, a set of web pages and a manifest describing the Tab. It requires a set of manual steps to both build out the pages, configuring CSS, hooking up the JavaScripts, deploying it all to a web site hosted in the cloud, writing the manifest, packaging the manifest into a zip file and more.

With the Teams Tab generator you can in an easy manner scaffold out the project and get a build and deployment pipeline, and be up and running in a few minutes.

The project that will be created is a TypeScript based project with a set of Gulp tasks to build the project and package the manifest, and optionally a built-in Express server to host the web sites and configuration so that you can with a simple command deploy your project to an Azure Web App.

How to get it

The generator is published as an npm package and you use npm to install it. The following command will install it as a global package for you to scaffold your Teams tabs.

npm install generator-teams-tab --global

How to use it

To create a new Teams Tab all you need to do is open up a command prompt and use Yeoman to create the project. The generator will ask you a set of questions and your project will configured based on those.

yo teams-tab

How to use the project

The project contains all source code you need to build and deploy tabs. Use Visual Studio Code or whatever text editor you prefer. The source code is divided into two areas. The first one being the actual tabs (pages and scripts), located in ./src/app You will find one folder called web which contains the web pages required for a tab; such as the actual tab page, the configure page and remove page. In the scripts folder you will have the TypeScripts file in which you build the logic for your tabs. For instance the actual main tab page, tab.html, has a corresponding tab.ts TypeScript file. You'll get it…

In the ./src/app folder there is also a TypeScript file called server.ts. Note, this file only exists if you answers yes to the question on using Express to host the Tab. This file is the server side node.js web server. If you need to modify the paths or want it to do fancier stuff than just client-side scripting this is where you start hacking.

There's also a folder calle ./src/manifest which contains the Tab manifest. A json file you might want to configure. And that folder also contains the two images you need to have for a Tab.

How to build it

You build the tab by using a simple Gulp task that will transpile and bundle your TypeScript into JavaScript and sets up the web server. Just use the following command to build it

gulp build

Once you've built it you can follow the instructions in the README.md file to deploy it to an Azure Web App.

The manifest for the tab is created by using another Gulp task:

gulp manifest

This task will create a zip file that you use to upload to your Teams team and it references the specified web site hosting the tabs. The file being created is located at ./package/tab.zip

This is great, but I want to…

I know, you want to have more stuff in the generator. It's all available on Github for you to grab and hopefully come back with suggestions. Go git it here: https://github.com/wictorwilen/generator-teams-tab

I'm looking forward to feedback and I'll keep updating the generator in line with what the Teams team are doing with their JavaScript framework, which is currently at 0.4.

glhf

SharePoint Framework has now reached General Availability - such a great journey

Fri, 24 Feb 2017 15:24:00 GMT

Let me start with congratulating the SharePoint Framework team on an amazing job and an amazing journey reaching this GA milestone.

A Big Thanks from the team here in Redmond to everyone who helped us to get to GA! #SPFx #SharePoint #SharePointFramework pic.twitter.com/czo2Duon7z
— Chakkaradeep (@chakkaradeep) February 24, 2017

The SharePoint Framework plays a significant part of the SharePoint future, yes - this is only the first version with a lot of new features on the way, and it is a part of the new SharePoint wave. I've haven't seen this interest in SharePoint for many years and I'm glad I'm still in this business. Delivering top notch collaboration solutions for our clients at Avanade. The SharePoint Framework will make it easier for us to customize SharePoint and it will also bring a lot more value for our clients in the end allowing them to stay evergreen and not being tied into "workarounds" and pesky SharePoint Designer hacks or arbitrary JavaScript snippets.

I'm extremely glad that I've been a part of this journey, seeing the team making the awesome stuff they've done. For me it started back in the fall of 2015 when we we're shown some very early ideas on where to go next and also some whiteboard sessions where we had an open and frank discussion about what the requirements were from the field. This openness is something that I think has made the difference this time and made the SharePoint Framework into what it is. All discussions was kept very secret and I'll tell you it was hard not to cry out to everyone how excited I was on the progress.

Early 2016 I was part of the first DevKitchen, where we had the opportunity to use SharePoint Framework for the first time. The team had only in a couple of months created something that actually worked! It was very satisfying to build that first web part (I do think that I was the first outside of Microsoft that actually built a client-side Web Part!). The framework had its quirks and issues back then, but they kept the speed up and delivered. A few more DevKitchens were hosted and finally in May they revealed the SharePoint Framework to the public.

Just after the summer everyone could get their hands on the first public release of the SharePoint Framework and the SPFx Team opened the floodgates of feedback through their Github repository. It has been fantastic to see all the support, wishes, bugfixes, samples and documentation that the public (and specifically Waldek) has produced to support the SharePoint Framework. And how fast and agile the team has responded to all the requests and issues. This is how Microsoft should build more stuff!

I've tried to do my best giving feedback as a consultant, developer and things my clients need. I'm particular proud of the enterprise guidance documentation that I've helped with. I absolutely love being part of this community.

Now, we're here, within a few weeks all tenants in Office 365 should be able to use the SharePoint Framework to build great stuff and awesome client-side Web Parts. We're already in the midst of porting our solutions to take advantage of the SharePoint Framework and getting it in the hands of our clients.

Thank you to the SharePoint Framework Team - I'm so looking forward to what's happening next. See you in a few weeks in Redmond ;-).

Let's make SharePoint great again!

Configuring Office 365 Groups creation the right way

Wed, 25 Jan 2017 15:08:00 GMT

Over the last few days the issue on how to prevent users to create Office 365 Groups has popped up in all sorts of conversations. This blog post will show you how to do it in the correct way, and serve as a future reference. I'm not the only one who have blogged about this, it's in many places including official documentation. But in many places both scripts and some caveats are either wrong or outdated. One post covers this topic really well, and in a good and correct way and it's this post by John P. White - Disable Office 365 Groups, part 2. Read it! This post however will show you how to do it in a more direct way, using PowerShell.

Background

We used to prevent end-users from creating Office 365 Groups (from now on referred to as only Groups) using an OWA Mailbox policy. Even I have a blog post on that topic. But this way to do it is outdated. That mailbox policy only applies to Groups being created from OWA (Outlook Web Access, Outlook on the web…whatever) and Outlook. It did not prevent people from creating Groups using Microsoft Teams, Planner, StaffHub, PowerBI, Dynamics 365 and what not.

How to do it properly

Instead of continuing to building the settings on the Mailbox policy setting, this setting has now moved to Azure AD. You can even see it in the "new" Azure Portal, although it doesn't really reflect the real settings and not all settings.

The way to do it is to use PowerShell and essentially follow the official documentation. The problem with that article however is that it contains a few errors, is not updated, has some weird scripts and is just to darn long to read through. So, here's a my PowerShell for this. You can find the complete script in this Gist.

Prerequisites

To be able to run the PowerShell you need to install some stuff

The Microsoft Online Services Sign-in assistant
The Windows Azure Active Directory Module for PowerShell - and here's a big thing. You MUST (at the time of writing) only use the preview version, with version number 1.1.130.0-preview found here. Do not try to download the higher version with version number 1.1.166.0 - it will not work.

Now, we got that out of the way, let's get to the fun stuff.

Scripting FTW

First we need to log in to our tenant using an admin account. I prefer to use a the Get-Credential method over the dialog option, makes everything more smoother.

# Store the credentials in a variable
$creds = Get-Credential

# Connect to the Microsoft Online services
Connect-MsolService -Credential $creds

The next thing is to make sure that users are allowed to create Groups, we'll limit it later. Make sure you use the script below and not the one in the official article as they have spelling errors on the variable.

# Get tenant setting (misspelled in official docs)
Get-MsolCompanyInformation | Format-List UsersPermissionToCreateGroupsEnabled

# If false, then use the following
Set-MsolCompanySettings -UsersPermissionToCreateGroupsEnabled $true

To limit the users allowed to create Groups we need to have a security group with members in Azure AD. And we need the Id of that group, so we'll grab it with some PowerShell:

# Retrieve ID of Group that should have the option to create groups
$group = Get-MsolGroup -SearchString "Group creators"

The settings we need to set are contained in an Azure AD object, created from a template. We retrieve that template using the following command and create our settings object like this:

# Retrieve the Group.Unified settings template (assuming you have not done this before)
$template = Get-MsolAllSettingTemplate | Where-Object {$_.DisplayName -eq "Group.Unified"}

# Create the settings object from the template
$settings = $template.CreateSettingsObject()

Once we have the settings object, we can start setting properties.

EnableGroupCreation - should be set to false. We negate the tenant setting here, and we'll override it soon again for the specific security group
GroupCreationAllowedGroupId - this is the Id of the security group that are allowed to create Groups
UsageGuidelinesUrl - a URL pointing to your usage guidelines. Optional, but recommended
GuestUsageGuidelinesUrl - a URL pointing to usage guidelines for external users. This link will be shown in the external sharing e-mails and should of course be on a public available location. Optional, but recommended
ClassificationList - a comma separated list with your classification labels. Optional. Currently the first one in the list will be the default one. (does not work in all tenants at the time of writing)

There's some more properties that you can take a look at, and over the last few weeks even some more popped up (without any documentation).

# Use this settings object to prevent others than specified group to create Groups
$settings["EnableGroupCreation"] = $false
$settings["GroupCreationAllowedGroupId"] = $group.ObjectId

# (optional) Add a link to the Group usage guidelines
$settings["UsageGuidelinesUrl"] = 
  "https://contoso.sharepoint.com/Pages/GroupUsageGuidelines.aspx"

# (optional) Add a link to Guest usage guidelines
$settings["GuestUsageGuidelinesUrl"] = 
  "http://contoso.com/usageguidelines"

# (optional) Add classifications to be used for Groups
$settings["ClassificationList"] = "Public,Internal,Top Secret"

# Verify
$settings.Values

Now we have the settings and all we need to do is to add them to Azure AD:

# Add the settings to Azure AD
New-MsolSettings -SettingsObject $settings

And from now on, only members of the security group can create Office 365 Groups using all endpoints such as Planner, Teams, PowerBI, Microsoft Graph REST etc. BUT StaffHub still ignores this setting!!!!! Aaargh!

Need to update the settings?

If you need to update the settings, or there are new properties that you want to configure, then use the PowerShell below. The one(s) in the official documentation is really weird written…

# Retrieve settings
$settings = Get-MsolAllSettings | Where-Object {$_.DisplayName -eq "Group.Unified"}

# Check the values
$settings.Values

# Update a property
$settings["GuestUsageGuidelinesUrl"] = "http://www.wictorwilen.se"

# Save the updates
Set-MsolSettings -SettingId $settings.ObjectId -SettingsValue $settings.GetSettingsValue()

Summary

That's it. It's not rocket science. Looking forward to further settings and also a proper UI in the Azure portal for the lazy people.

The PowerShell is a bit weird though, should have had a review by the PowerShell team before going into the production in my opinion.

SharePoint Framework: how to properly dynamically populate dropdown property pane fields

Thu, 06 Oct 2016 20:37:00 GMT

One of the key parts of SharePoint Web Parts is the ability to have them configurable using the Web Part properties. This story is still true with client-side Web Parts in the new SharePoint Framework. In this post I will show you one of the more common scenarios; how to populate drop downs (and other fields) in the property pane dynamically. But also show you how what's wrong with the current implementation.

Client-side Web Part Property Pane basics

The Property Pane in client-side Web Parts are defined by the propertyPaneSettings method. It's a method that returns an IPropertyPaneSettings object representing the pages, groups and fields. This method is invoked whenever you click to edit the Web Part. The method is "synchronous" meaning that you should return a static set of pages, groups and fields - there's no option to wait for it to load (SPFx issue #127).

Defining the Dropdown

For a Dropdown we use the PropertyPaneDropdown field and specify for instance it like this, in the propertyPaneSettings method.

PropertyPaneDropdown('listName', {
  label: strings.DescriptionFieldLabel,
  options: this._options
})

In this case the options property references a local variable defined as below:

private _options: IPropertyPaneDropdownOption[];

Loading the data…

But when do we load this data into the local variable. We do have a couple of options to do this, but there really is only one viable option at the moment and that is to use the onInit<T>() method. This method always runs when the Web Part is loaded or is added to a page, and it only runs once and it is the only option we have if we want to load something using a promise and make sure to have it loaded before we have the chance of rendering the property pane. The onInit method returns a Promise and that allows us to actually block the loading of the Web Part until we have the data.

To load data, mock or live, I've created a simple list data provider, that you can find in the following Gist. Pay attention to the fact that I have set a delay on the mock loading to 5 seconds, this is to simulate a slow request and show you how bad this current implementation actually is. https://gist.github.com/wictorwilen/0bf866ee4fda2f9611f43ee17b9127d5

Then I implement the onInit method as follows:

public onInit<T>(): Promise<T> {
  let dataService = (this.context.environment.type === EnvironmentType.Test || this.context.environment.type === EnvironmentType.Local) ?
    new MockListsService() :
    new ListsService(this.context);

  this._options = [];

  return new Promise<T>((resolve: (args: T) => void, reject: (error: Error) => void) => {
    dataService.getListNames().then(lists => lists.forEach(list => {
      this._options.push(<IPropertyPaneDropdownOption>{
        text: list,
        key: list
      });
      resolve(undefined);
    }))
  });

First of all I create my data service object (mock or real one). Then I create a new Promise that uses my list service and once the list data is read it populates the local variable holding the data for our dropdown and finally I resolve the promise.

There are some articles and Github repos that uses another approach, they just return a resolved promise and let the call to the external data service run in the background. If that background request takes to long time (the simulated 5 seconds for instance) or fails then the user might have time to open the property pane and see an empty dropdown.

Now when the web part is added to a page or a page a loaded with that web part the onInit method will "block" the web part from rendering until it has the data for the property pane. Well, that's not good, but that's how it is at the moment. There is however a possibility that we might be able to use displayMode property of the web part and only do this when we are in edit mode. I have not been able to verify this as the workbench always are in edit mode and none of my tenants actually loads the client side web parts in the modern pages - I'll get back on this.

Another annoying thing is that since this is blocking the rendering, not even showing a spinning wheel or something, the user experience is quite bad if you have long running calls since nothing is shown (SPFx issue #228).

Summary

I've now shown you how to pre-load data for your property pane fields, yes same approach works for other field types than dropdowns as well. But is this the proper way then? Nope, it isn't but I have great hopes that this will be fixed in a better manner (see linked issues). If not we still have the option of creating completely custom property pane fields that allows us to do basically whatever we want.

SharePoint Online CDN features announced in preview

Thu, 22 Sep 2016 20:36:00 GMT

Today, Mr Vesa, announced the availability of the (long awaited) CDN features for SharePoint Online. The SharePoint Online CDN features allows you to turn one or more libraries in your SharePoint tenant into a repository for assets that you want to store in a CDN for performance reasons and geo-distribution reasons.

How to set things up

I'm not going to rehash everything that is outlined in the announcement post, but rather highlight a few important things.

To get started and turn one of your libraries into a CDN enabled library you need to install the latest SharePoint Online PowerShell cmdlets to get access to some new and updated PowerShell cmdlets. Once you have that all you need to do is first enable it on your tenant and then add libraries for cdnization:

$creds = Get-Credential
Connect-SPOService -Url https://contoso-admin.sharepoint.com -Credential $creds
Set-SPOTenant -PublicCdnEnabled $true

Once this is done then you choose what libraries to use as the source for your CDN. You can point directly to a library or a subfolder in a library.

New-SPOPublicCdnOrigin -Url https://contoso.sharepoint.com/SiteAssets/

When you do this you get a big and yellow warning stating that everything you add in this folder from now on will be pushed to the CDN, and that CDN is publicly available and not governed by all the nice policies we have in Office 365. So, don't put your annual report drafts in there!

Note, it might take a few minutes until it is all ready for usage after adding or changing the origins. 15-20 minutes is not uncommon.

You can always retrieve all your CDN origins by using the following command:

Get-SPOPublicCdnOrigins

This command will list the ID of each CDN origin as well as the origin. The ID is very important, because you need that when you construct the URL to the CDN. It's probably one or more Guids in that ID…

How to access the files in the CDN

To get access to the files in the CDN you need to construct a path using the ID for the CDN origin like this:

https://publiccdn.sharepointonline.com/tenant.sharepoint.com/ID

For instance

https://publiccdn.sharepointonline.com/contoso.sharepoint.com/1544004027c884490c55638fcb53de1f5d4897c5ea7513c1c0849dd7d8f4314cbda99429

Yes, it's a bit long but that's how it is.

If you now try to access an image or script in this CDN by just typing the URL in the browser, you will get an error stating "Invalid referer". This is by design and you need to add a HTTP Header to see the image/script, the Referer header with the value of the URL of your tenant (see announcement blog). In cases where you embed the image in a page or load the script from a page, this is done automatically for you by the browser. An even easier way is to just create a page and insert a Picture from Address, and paste your CDN Url.

Caveats

There's a couple of caveats to the CDN as of now. ~~One thing I had hoped was that you could use image renditions in combination with this, which would have been AWESOME. Nope, you can't. Vesa, can you add that to the todo list?~~

[Update 2016-09-29] The image renditions are partly supported, you can now use width, height and cropMode (fit for instance) as query string parameters for the image. But not RenditionId - once that can be done this feature is rock solid!

[Update 2016-09-29] CORS support has been enabled! Thanks you to the product group for fast and quick turnaround for these kind of features!

Another quite important thing is that the CDN isn't CORS enabled. They do a check for the referer, see above, so that the request are coming from the correct tenant. But if you try to use jQuery or some other mechanism to load scripts or assets from the CDN location you get

No 'Access-Control-Allow-Origin' header is present on the 
requested resource. Origin 'https://tenant.sharepoint.com' is 
therefore not allowed access. 
The response had HTTP status code 406.

~~I wish they added the possibility to allow CORS requests from the tenant, just as they only allow request refering from the tenant~~.

Summary

I think this feature is awesome and I have already upgraded a few tenants and customers to use this new feature for some embedded resources. Oh, did I say this is free of charge and a part of your Office 365 subscription. Free beer is good beer, despite in preview!

SharePoint Framework Nuggets: working with GUIDs

Mon, 19 Sep 2016 17:50:00 GMT

SharePoint developers - we do like GUIDs, don't we. We all read RFC4122 both once and twice. And now with SharePoint Framework and the goal to embrace all them Macintosh and open source people - they gotta have their fair share of GUIDs.

And to aid with that the SharePoint Framework got some really nice GUID features, although a bit unpolished as you might notice - but this is all preview bits at the time of writing.

The Guid class

First of all we must have the option to create GUIDs. There might be a situation that you need to store something really, really unique - to help with the we do have the Guid class in the @microsoft/client-sp-base module. This class both allows you to create new Guids, parse Guids and validate Guids.

This is how you import the Guid class:

import { Guid } from '@microsoft/sp-client-base';

Then to create a Guid, you use the code below. The newGuid method can take an optional parameter if you need to create a custom random generator. By default it generates a version 4 UUID, also known as a pseudo random UUID, which can be generated in a browser. I suggest you skip passing in custom random generators.

var guid: Guid = Guid.newGuid();

What if someone gives a "GUID" to you, can you trust it is a proper Guid, no you can't you need to validate it. That can be done using the isValid method, which takes a string as in input.

if( Guid.isValid(' f0a1f189-dae4-49f5-8846-3a17429fd52') ) { alert('Valid') };

Then we finally also have a method to parse a string potentially containing a Guid, tryParse. The method will either return a Guid object or undefined.

var guid: Guid = Guid.tryParse('f0a1f189-dae4-49f5-8846-3a17429fd52');

The GuidHelpers class (@internal)

[Update 2016-09-20] - The GuidHelpers class is marked internal and will be removed in future builds of the SharePoint Framework.

There's also another class in SharePoint Framework for Guids, the GuidHelpers class. This class lives in the @microsoft/sp-client-preview module. It has a set of similar function to generate and validate Guids, but it does not work with Guid objects, it uses strings instead. For instance the GuidHelpers.generateGuid() returns a string. Another issue is that the GuidHelpers.isValid() does not validate Guids the same way as the Guid.isValid does (issue #201 in the SPFx Repo).

At the moment (drop 3 of SPFx) I would stay away from the GuidHelpers class.

As usual there's some code samples of this to be found in this Github repo: https://github.com/wictorwilen/spfx-nuggets

Happy GUIDing!

SharePoint Framework Nuggets: logging like a pro

Mon, 19 Sep 2016 12:19:51 GMT

I guess that almost every application or solution you ever built has contained some portions of a logging mechanism. And how many of you have written your own - yup, all of you! But what about the SharePoint Framework - yes, it has built-in logging!

How to log in the SharePoint Framework

Logging is a very convenient and easy way to keep track of events happening, instead of having breakpoints, or in JavaScript even worse - alerts. The SharePoint Framework (SPFx) has as all decent frameworks a built-in logging mechanism, albeit very simple, but still yet valuable. It's contained in the @microsoft/sp-client-base module and the class is called Log. To use it in your SharePoint Framework solutions you need to import it as follows:

import {
  Log
} from '@microsoft/sp-client-base';

The Log class contains four static methods for logging:

info
warn
error
verbose

The names are exactly what you expect, the info is used for information, warn for warnings, error for errors and verbose for when you just have to much on your mind and want to spit it out.

In the SharePoint Framework implementation all logging is done to the JavaScript console and you can see the logging using the developer tools of your favorite browser. It can take some searching to find them as SPFx spits out quite a lot of logging by itself.

All static methods have the same signature, except the error method - they take three arguments:

source: the source of the logging information (max 20 characters), such as method or class name
message: the actual message to log (max 100 characters)
scope: an optional service scope (more on this one later)

The error method takes an Error object instead of the message string, otherwise they are the same.

This is how it could be used in client side web part:

public render(): void {
  this.context.statusRenderer.clearError(this.domElement);
  this.context.statusRenderer.displayLoadingIndicator(this.domElement, strings.Loading);
  Log.verbose('SpFxNuggets', 'Invoking render');

  this._webInfoProvider.getWebInfo().then((webInfo: IWebInfo) => {
    if (this.properties.fail) {
      throw new Error('Mayday');
    }
    Log.info('SpFxNuggets', 'Service OK', this.context.serviceScope);
    this.context.statusRenderer.clearLoadingIndicator(this.domElement);
    this.context.domElement.innerHTML = `<h1>${webInfo.title}</h1>`;

  }).catch((err) => {
    Log.error('SpFxNuggets', err);
    this.context.statusRenderer.clearLoadingIndicator(this.domElement);
    this.context.statusRenderer.renderError(this.domElement, err);
  });
}

In the example above I use the verbose method to log that we're in the render method. Just verbose information. I also added logging to when the service returns (the promise is fulfilled) to log information that it has returned. In that info method I use the service scope of the web part, and when using the service scope, it replaces my source with the real name (JavaScript name) of the web part. Finally I log the error in the catch method. The image below shows the console output.

As usual you can find all the source code in this repository: https://github.com/wictorwilen/spfx-nuggets

Happy logging!