Contents tagged with npm

  • Using Device Codes to authenticate Bots with Azure AD

    Tags: Bot Framework, Microsoft Teams, npm, Microsoft Azure, Microsoft Graph, Azure AD

    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.

    Setting the platform for the App

    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

    Testing the bot with the Bot Framework emulator

    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.

    Consenting the device code bot

    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:

    The device code bot in 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.

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

    Tags: Microsoft Teams, Yeoman, Npm, Git

    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

    Tags: SharePoint Framework, npm, SharePoint

    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

    externals in config.json

    write-manifest.json

    cdn base path in 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.

About Wictor...

Wictor Wilén is the Nordic Digital Workplace Lead working at Avanade. Wictor has achieved the Microsoft Certified Architect (MCA) - SharePoint 2010, Microsoft Certified Solutions Master (MCSM) - SharePoint  and Microsoft Certified Master (MCM) - SharePoint 2010 certifications. He has also been awarded Microsoft Most Valuable Professional (MVP) for seven consecutive years.

And a word from our sponsors...