in Office 365 API

Office 365 APIs: Getting Started with Building Web Applications

Office 365 API Development in Visual Studio

Office 365 API Tools for Visual Studio 2013 helps you to configure and integrate Office 365 APIs for your existing application and adds the required Office 365 API SDKs to your project.

However, Visual Studio 2013 does not include a default project template for Office 365 APIs to create new Visual Studio projects that provides you the required code to kick start your Office 365 development.

The code to authenticate your application will change depending on the type of the Visual Studio project, such as, an ASP.NET MVC Application or Windows Store or Windows Phone projects.

You can find code samples for almost every project type in Office Developer GitHub.

In this post, let us see how to quickly clone the ASP.NET MVC project template from GitHub to build a web application that consumes Office 365 APIs.

Below are the two ASP.NET MVC web application project templates available at Office Developer GitHub:

What You Need

To successfully build and execute this sample, you will need:

  1. Visual Studio 2013
    1. If you do not have Visual Studio 2013, you can download and install the free Visual Studio Community Edition
  2. Office Developer Tools for Visual Studio 2013
  3. Office 365 Developer Subscription

Choosing Between Building Single Tenant and Multi-tenant Web Applications

If the application you are building is deployed internally for your organization and allows only your organization users to sign in and use the application, then you should build a single tenant application.

If the application you are building is deployed internally for your organization but also allows external users, such as vendors to sign in and use the application, then you should build a multi-tenant application.

Clone GitHub Office 365 API Web Application in Visual Studio

Visual Studio 2013 supports connecting to Git servers. As the project templates are hosted in GitHub, Visual Studio 2013 makes it easier to clone projects from GitHub.

The steps below will describe how to clone Office 365 API web application project in Visual Studio from Office Developer GitHub.

1. Open Visual Studio 2013

2. Switch to Team Explorer

3. Team Explorer provides options to clone Git repositories

VS2013-Team-Explorer

4. Click Clone under Local Git Repositories, enter the clone URL for the web application project and click Clone

  • Clone URL for single tenant web application:
    • https://github.com/OfficeDev/O365-WebApp-SingleTenant.git
  • Clone URL for multi-tenant web application:
    • https://github.com/OfficeDev/O365-WebApp-MultiTenant.git

clone-git-repo

Visual Studio will clone the Git repo in your local development machine.

5. Once the project is cloned, double click on the repo

git-clone-complete

6. Double click the project solution which is available under Solutions

7. Visual Studio will open the cloned project

8. Switch to Solution Explorer and build your project

  • Visual Studio will download the NuGet packages and compile the project
  • Ignore any errors at this point (as we will fix in the steps below)

restore-nuget-packages

Integrate Your Application with Office 365 APIs

Office 365 applications use Azure Active Directory (Azure AD) to authenticate and authorize users and applications respectively. All users, application registrations, permissions are stored in Azure AD.

Using the Office 365 API Tool for Visual Studio you can configure your web application to consume Office 365 APIs.

  1. In the Solution Explorer window, right click your project -> Add -> Connected Service.
  2. A Services Manager dialog box will appear. Choose Office 365 -> Office 365 API and click Register your app.
  3. On the sign-in dialog box, enter the username and password for your Office 365 tenant.
  4. After you’re signed in, you will see a list of all the services.
  5. Initially, no permissions will be selected, as the app is not registered to consume any services yet.
  6. Select Users and Groups and then click Permissions
  7. In the Users and Groups Permissions dialog, select Enable sign-on and read users profiles’and click Apply
  8. Select Contacts and then click Permissions
  9. In the Contacts Permissions dialog, select Read users’ contacts and click Apply
  10. Click Ok

After clicking OK, Office 365 client libraries (in the form of NuGet packages) for connecting to Office 365 APIs will be added to your project.

In this process, Office 365 API tool registered an Azure AD Application in the Office 365 tenant that you signed in the wizard and added the Azure AD application details to web.config.

Azure Active Directory Authentication Library (ADAL) is used to authenticate your applications to Office 365 APIs. The web application project is already configured to use ADAL.

If you are building single tenant application:

There is one extra configuration required if you are building a single tenant application.

In your web.config, update the TenantId value to your Office 365 tenant Id where the application is deployed.

To get the tenant Id of your Office 365 tenant:

  • Log in to your Azure Portal and select your Office 365 domain directory.

NOTE: If you are unable to login to Azure Portal using your Office 365 credentials, You can also access your Office 365’s Azure Portal directly from your Office 365 Admin Center.

  • Now, in the browser URL, locate the GUID. This will be your Office 365 tenant Id.
  • Copy and paste it in the web.config where it says paste-your-tenant-guid-here :
    • <add key=ida:TenantId value=paste-your-tenant-guid-here />

Debug the Web Application

Hit F5 to debug your web application

NOTE: If this is a new development environment, Visual Studio may prompt to configure IIS SSL certificate. Click Yes (twice) to continue.

1. Visual Studio will launch the browser with the web application.

2. Click Sign in at the top right corner and sign in to your Office 365 tenant where you registered your web application.

3. If your application is a multi-tenant application, then you should see a consent screen:

NOTE: Since only your organization users are allowed to sign-in in a single tenant application, there is no need to consent.

Once successfully signed in, Azure AD will display the consent screen which shows the different permissions your web application is requesting.

web-application-consent

Click Accept to continue

5. Now you should see your email address displayed at the top, instead of sign in.

6. Click on My Contacts

7. My Contacts page will retrieve your Exchange contacts (if any) from your tenant

my-contacts

You now have a web application project that you can customize and integrate Office 365 APIs.

Quick Look at the Code

The authentication startup class, App_Start/Startup.Auth.cs in the project contains the startup logic for Azure AD authentication.

The sample uses a persistent ADAL token cache that uses a database for its token cache. You can see the token cache implementation in the following files:

Sign In and Sign Out Controls

The sign in and sign out controls are already added to the views. You can find them underViews\Shared folder. 1. _LoginPartial.cshtml is the partial view that renders the Sign In and Sign Out actions. 2. _LoginPartial.cshtml is then rendered in _Layout.cshtml 3. TheAccountController.cs has the required methods for sign in and sign out.

Requiring authentication to access controllers

Applying Authorize attribute to all controllers in your project will require the user to be authenticated before accessing these controllers. To allow the controller to be accessed anonymously, remove this attribute from the controller. If you want to set the permissions at a more granular level, apply the attribute to each method that requires authorization instead of applying it to the controller class.

Write Code to call Office 365 APIs

You can now write code to call an Office 365 API in your web application. You can apply the Autorize attribute to the desired controller or the method in which you wish to call Office 365 API.

ContactsController.cs describes how to interact with the Office 365 API discovery service, get the endpoint URI and resource Id for Outlook Services and then query users’ contacts.

Feel free to leave a comment below if you have any questions!

If you have a product/feature request, make sure you post your idea here!

Happy Coding!

Write a Comment

Comment

Time limit is exhausted. Please reload the CAPTCHA.

13 Comments

  1. Hi, thank you for share this code example.

    I tried it out and it worked perfectly in my local dev environment. Now I tried to publish the app to Azure Websites but I get a “bad request” error message when I try to login.

    I guess there is something I need to add to the web.config to get rid of the error. Maybe I need to add ida:RedirectUri as it’s written here: http://zimmergren.net/technical/getting-started-with-office-365-development-part-4-from-development-to-production-publish-your-app-to-windows-azure-web-sites. But how can I find out the GUID that I need?

    • Hi Mike,

      Yes, you need to update the Redirect URI to point to the published domain (eg., https://www.mywebsite.com). In your case it will be the Azure website domain.

      In the Office 365 API Tool, click on App Properties… and that should show you the Azure AD application name and the Redirect URI options.

      The latest tools do not have the Redirect URI in the web.config. However, if you are publishing a single-tenant app, make sure you update the tenant Id with the appropriate tenant if it is different from your developer tenant.

      If you are using the Azure AD Portal, in the Applications page, locate the Search icon and search for the application name that you see in the tool. That should take you to the application and you can add/manage Redirect URIs directly from the portal.

      Let me know if that works for you.

      • Thank you for your help. Unfortunately I didn’t work.

        When I try to sign in from my app the screen gets blank and the status bar says its waiting for my website.

        I am gonna try the multitenant example in a couple of days to see if that works for me.

        • In the bottom right corner of the page that shows the ‘bad request’ error, you’ll see the error details.
          I had this issue and realised that my browser was signed into my Microsoft account so the app was trying to use my @live.com credentials to authenticate. I signed out of this account and tried again – fixed!

  2. Hi,

    When i click sigin link, the authentication window should populate in a separate browser window , after entered the credentials it should be closed. How to to do this way ?? Please help.

  3. Hi,
    Im getting the folowing error when i used the valid username and password.
    [it is trial account]

    Error:
    ——-
    Sorry, but we’re having trouble signing you in
    Please try again in a few minutes. If this doesn’t work, you might want to contact your admin and report the following error: 50011.
    CorrelationId: 009ee5b6-e23d-4b86-92e0-ca613b7f267e

    Timestamp: 2015-04-01 13:00:49Z

    Please help what need to be done for this issue.

    Thanks in advance.

  4. Hi
    When I am clicking on My Contacts it’s showing an error:
    “The value cannot be null parameter name: clientsecret”
    can you tell me how to solve this..?