Create a custom connector for a web API

This tutorial shows you how to start building an ASP.NET Web API, host it on Azure Web Apps, enable Azure Active Directory authentication, and then register the ASP.NET Web API in Microsoft Flow. After the API is registered, you can connect to it and call it from your flow. You could also register and call the API from PowerApps or Azure Logic Apps.

Prerequisites

Create and deploy an ASP.NET web app to Azure

For this tutorial, create a Visual C# ASP.NET web application.

  1. Open Visual Studio, then choose File > New Project.

    1. Expand Installed, go to Templates > Visual C# > Web, and select ASP.NET Web Application.

    2. Provide a project name, location, and solution name for your app, then choose OK.

    For example:

    Create a Visual C# ASP.NET web application

  2. In the New ASP.NET Web Application box, select the Web API template. If not already selected, select Host in the cloud. Choose Change Authentication.

    Select "Web API" template, "Host in the cloud", "Change Authentication"

  3. Select No Authentication, and choose OK. You can set up authentication later.

    Select "No Authentication"

  4. When the New ASP.NET Web Application box reappears, choose OK.

  5. In the Create App Service box, review the hosting settings described in the table, make the changes you want, and choose Create.

    An App Service plan represents a collection of physical resources used for hosting apps in your Azure subscription. Learn about App Service.

    Create App Service

    Setting Suggested value Description
    Your Azure work or school account, or your personal Microsoft account your-user-account Select your user account.
    Web App Name custom-web-api-app-name or the default name Enter the name for your Web API app, which is used in your app's URL, for example: http://web-api-app-name.
    Subscription Azure-subscription-name Select the Azure subscription that you want to use.
    Resource Group Azure-resource-group-name Select an existing Azure resource group, or if you haven't already, create a resource group.

    Note: An Azure resource group organizes Azure resources in your Azure subscription.

    App Service Plan App-Service-plan-name Select an existing App Service plan, or if you haven't already, create a plan.

    If you create an App Service Plan, specify these settings:

    Setting Suggested value Description
    Location deployment-region Select the region for deploying your app.
    Size App-Service-plan-size Select your plan size, which determines the cost and computing resource capacity for your service plan.

    To set up any other resources required by your app, choose Explore additional Azure services.

    Setting Suggested value Description
    Resource Type Azure-resource-type Select and set up any additional resources required by your app.
  6. After Visual Studio deploys your project, build the code for your app.

Create an OpenAPI (Swagger) file that describes your Web API

To connect your Web API app to Microsoft Flow, PowerApps, or Logic Apps, you need an OpenAPI (formerly Swagger) file that describes your API's operations. You can write your own OpenAPI definition for your API with the Swagger online editor, but this tutorial uses an open source tool named Swashbuckle.

  1. If you haven't already, install the Swashbuckle Nuget package in your Visual Studio project.

    1. In Visual Studio, choose Tools > NuGet Package Manager > Package Manager Console.

    2. In the Package Manager Console, go to your app's project directory if you're not there already (run Set-Location "project-path"), and run this PowerShell cmdlet:

      Install-Package Swashbuckle

      For example:

      Package Manager Console, install Swashbuckle

    Tip

    If you run your app after installing Swashbuckle, Swashbuckle generates an OpenAPI file at this URL:

    http://{your-web-api-app-root-URL}/swagger/docs/v1

    Swashbuckle also generates a user interface at this URL:

    http://{your-web-api-app-root-URL}/swagger

  2. When you're ready, publish your Web API app to Azure. To publish from Visual Studio, right-click your web project in Solution Explorer, choose Publish..., and follow the prompts.

    Important

    Duplicate operation IDs make an OpenAPI document invalid. If you used the sample C# template, the template repeats this operation ID twice: Values_Get

    To fix this problem, change one instance to Value_Get and republish.

  3. Get the OpenAPI document by browsing to this location:

    http://{your-web-api-app-root-URL}/swagger/docs/v1

    You can also download a sample OpenAPI document from this tutorial. Make sure that you remove the comments, which start with "//", before you use the document.

  4. Save the content as a JSON file. Based on your browser, you might have to copy and paste the text into an empty text file.

Set up Azure Active Directory authentication

You will now create two Azure Active Directory (AAD) applications in Azure. For more information on how to do this, see Integrating applications with Azure Active Directory.

Important

Both apps must be in the same directory.

First AAD application: Securing the Web API

The first AAD application is used to secure the Web API. Name it webAPI. You can enable AAD authentication on your webAPI by following these steps with the following values:

  • Sign-on URL: https://login.windows.net
  • Reply URL: https://<your-root-url>/.auth/login/aad/callback
  • There is no need for a client key.
  • There is no need to delegate any permissions.
  • Copy the application ID, because you need it later.

Second AAD application: Securing the custom connector and delegated access

The second AAD application is used to secure the custom connector registration and acquire delegated access to the Web API protected by the first application. Name this one webAPI-customAPI .

  • Sign-on URL: https://login.windows.net
  • Reply URL: https://msmanaged-na.consent.azure-apim.net/redirect
  • Add permissions to have delegated access to Web API.
  • Copy the application ID, because you need it later.
  • Generate a client key and copy it, because you need it later.

Add authentication to your Azure Web App

  1. Sign in to the Azure portal and then find the Web App that you deployed in the first section.
  2. Select Settings, and then select Authentication / Authorization.
  3. Turn on App Service Authentication and then select Azure Active Directory. On the next blade, select Express.
  4. Select Select Existing AD App, and select the webAPI AAD application you created earlier.

You should now be able to use AAD to authenticate your web application.

Add the custom connector to Microsoft Flow

  1. Modify your OpenAPI to add the securityDefintions object and AAD authentication used for the Web App. The section of your OpenAPI with the host property should look like this:
// File header should be above here...

"host": "<your-root-url>",
"schemes": [
    "https"		 //Make sure this is https!
],
"securityDefinitions": {
    "AAD": {
        "type": "oauth2",
        "flow": "accessCode",
        "authorizationUrl": "https://login.windows.net/common/oauth2/authorize",
        "tokenUrl" : "https://login.windows.net/common/oauth2/token",
        "scopes": {}
    }
},

// The rest of the OpenAPI follows...
  1. Browse to Microsoft Flow, and add a custom connector as described in Use custom connectors in Microsoft Flow.

  2. Once you have uploaded your OpenAPI, the wizard auto-detects that you are using AAD authentication for your Web API.

  3. Configure the AAD authentication for the custom connector.

  • Client ID: Client ID of webAPI-CustomAPI
  • Secret: Client key of webAPI-CustomAPI
  • Login URL: https://login.windows.net
  • ResourceUri: Client ID of webAPI
  1. Select Create and creating a connection to the custom connector.

Next steps