Task 2 – Customizing the Developer Portal

Site Configuration

The Developer Portal is based on a fork of the Paperbits Web framework and is enriched with API Management-specific features. The fork resides at https://github.com/Azure/api-management-developer-portal.

It is possible to self-host and manage your own Developer Portal outside of an API Management instance. This is an advanced option, which allows you to edit the portal’s codebase and extend the provided core functionality. This is documented at https://github.com/Azure/api-management-developer-portal/wiki and https://docs.microsoft.com/en-us/azure/api-management/api-management-howto-developer-portal.

Before you make your portal available to visitors, you should personalize the automatically-generated content. Recommended changes include the layouts, styles, and the content of the home page. This is documented at https://docs.microsoft.com/en-us/azure/api-management/api-management-howto-developer-portal-customize.

A video on customization is available at https://www.youtube.com/watch?v=5mMtUSmfUlw.

Email Configuration

The templates for the email notifications are managed from the Azure Management Portal, directly on the blade’s resource menu.

Look at the available notifications and notifications templates which are customizable.

Task 3 – Product Management

A product contains one or more APIs as well as a usage quota and the terms of use. Once a product is published, developers can subscribe to the product and begin to use the product’s APIs.

Product definition

• In the Azure Portal, open the resource menu item Products.

  

• Let’s add a new product tier called Gold Tier.

  

  

• Next, we’ll change the access control by clicking on Gold Tier and selecting Access control in the left pane.

  

  Press Add group, check Developers and Guests, then press Select. The two added roles are shown now.

  

  Back in the private browsing session, browse to Products and observe the new Gold Tier.

  

• On the left menu, open the APIs blade. You will see all APIs, the possibility to add new ones, but also to customize existing ones.

  

Add API from Scratch

Instead of developing an API, for this lab you will use the existing Star Wars API:

1) Click on Add API.
2) Click on HTTP – Manually define an HTTP API.
3) Select the Full option in the Create an HTTP API dialog.
4) Enter Display name, Name, and Description.
5) Assign https://swapi.dev/api to the Web service URL.
6) Keep the URL scheme at HTTPS as we strive to enforce HTTPS only.
7) Set the API URL suffix to sw. This allows us to compartmentalize the APIM URLs for distinct APIs.
8) Assign Starter and Unlimited products.
9) Press Create.

While it is conventionally a good idea to version APIs from the onset, we are omitting this step here for brevity of the labs.

• Once created, inside the Star Wars API press + Add operation to declare two new operations:

  1) GetPeople

  • Display name: GetPeople
  • Name: getpeople
  • URL: GET /people/

  2) GetPeopleById

  • Display name: GetPeopleById
  • Name: getpeoplebyid
  • URL: GET /people/{id}/

  

Access Star Wars API from Developer Portal

• Switch now to the Developer Portal and sign in as a developer with a subscription.

• Select Explore APIs. You should see both Echo API and Star Wars.

  

• Click on Star Wars. Try the GetPeople operation. Observe a successful 200 response.

  

• Now try the GetPeopleById operation with id = 2

  

• Examine the successful 200 response with C-3PO’s details in the response body payload.

  

•  

Import API using OpenAPI

Instead of importing operations one-by-one, you can also import a full API. The OpenAPI specification (aka Swagger) is a definition format to describe RESTful APIs. The specification creates a RESTful interface for easily developing and consuming an API by effectively mapping all the resources and operations associated with it.

As a demo we will use an API that offers a simple calculator service : Calc API

1) On the left menu, open the APIs blade.
2) Under Create from definition select OpenAPI.
3) Select the Full option in the Create from OpenAPI specification dialog.
4) Enter http://calcapi.cloudapp.net/calcapi.json as the OpenAPI specification value. You should subsequently see Display name, Name, and Description populate.
> Note the intentional use of http instead of https as this backend does not presently support https.
5) While the backend service only runs on HTTP, we need to set URL scheme to Both to allow for APIM ingress to occur on HTTPS for callers such as the Developer Portal.
6) Set the API URL suffix to calc.
7) Assign Starter and Unlimited products.
8) Press Create.

• Once the API is created, it will show in the list of APIs along with all of its operations.

  

• Back in the Developer Portal, try out the Calculator API via the Add two integers GET method, then examine the response.

  Accepting the defaults of 49 and 51 suffices. There’s presently an issue where defaults are shown in a dropdown. If you wanted to change the values, add new a and b parameters and values, then remove the dropdown values.

We can inspect / edit the Open API definition by selecting the Edit icon from the Frontend block:

Troubleshooting

Unable to complete the request

This is likely a mixed-content CORS error in which you are attempting a call to an APIM endpoint that is only set up for HTTP. It fails as the Developer Portal runs on HTTPS. Please check the setup steps above for the URL scheme.

Task 3: Calling APIs

Calling API and testing Subscription Keys

Let’s add another API, the Color API.

• Create a new API with OpenAPI specification and import swagger from https://markcolorapi.azurewebsites.net/swagger/v1/swagger.json.

• Use the API URL suffix color.

  

  

• We can test the newly-added API from the Test tab. Note the successful 200 response.

  

• Products can be configured after the API is initially created as well. On the Settings tab, set Products to include Starter and Unlimited, then press Save.

  

• Switch to the Developer portal and look at the Color API.
• Try the ApiRandomColorGet operation.

• Notice the successful 200 response and the returned random color.

  

  

Rate limit

API Management uses rate limiting to protect APIs from being overwhelmed and helps prevent exposure to DDoS attacks. As APIM sits in between your API and their callers, it effectively governs access to your APIs.

We are going to use the Color website to demonstrate how rate limiting is applied. The website displays 500 lights. Each light will randomly make a call to the RandomColor API and then apply the returned color to the lights.

First, we need to enable CORS for the domain name of the frontend. To achieve this we have to do the following in APIM:

• On the sidemenu, click on APIs, then select the All APIs option.
• Inside the Inbound processing area you will see the cors policy, which we added in part 2 by pressing the Enable Cors button.

• Click on the pencil icon next to that policy to edit it.

  

• Here we will see this form where we can add the domain name of our frontend https://markcolorweb.azurewebsites.net or the * for all domains. Press Add allowed origin, enter the URL, then press Save.

  

• After enabling CORS in APIM lets go back to our frontend https://markcolorweb.azurewebsites.net and follow these steps:

• Click on the hamburger menu next to Colors in the top left corner.
• Click on Config.
• Replace the API URL according to this format: https://YOURAPIM.azure-api.net/color/api/randomcolor
• After setting the API URL correctly, press the hamburger menu again and go to Home.

• Press Start to see how the frontend is calling the api. You should see a 401 response, indicating an auth error. This happens as our API requires a subscription, but we have not yet entered a subscription key.

  

• The subscription keys can be fetched from the Developer Portal. Open the main Developer Portal page, then click on Profile in the top menu.
• Copy the following URL into Notepad, modify your APIM instance, then copy the URL, so that you have two of the same URLs. We will use them for the Starter and Unlimited pathways into APIM.
  
  • https://YOURAPIM.azure-api.net/color/api/RandomColor?key=

• Append the primary keys for both subscriptions – one key per URL – to get unique URLs for Starter and Unlimited.

  

• To see that Unlimited product has no rate limits:
  
  • Configure the Color website to use the Unlimited URL.
  • Select [Start].

  • Notice there is no rate limit – every light is randomly and continuously updated.

    

• To see that Starter product is limited to 5 calls per minute:
  
  • Configure the Color website to use the Starter URL.
  • Select [Start].

  • Notice that only 5 lights get colored.

    

• Try the same Starter URL directly in your web browser:
  

  • Notice the error status / message returned. For example: { "statusCode": 429, "message": "Rate limit is exceeded. Try again in 40 seconds." }

    

    
        <cors allow-credentials="true">
            
                https://apim-sk-12212021.developer.azure-api.net
                https://markcolorweb.azurewebsites.net
            
            <allowed-methods preflight-result-max-age="300">
                *
            
            
                

*

*

            
        
    
    
        <forward-request />
    
    <outbound />
    <on-error />

Task 3: Caching Policy

Caching

API Management can be configured for response caching which can significantly reduce API latency, bandwidth consumption, and web service load for data that does not change frequently.

Using the Azure Management portal, navigate to the Color API and set a set a caching policy for the ApiRandomColor GET:

• Press Add policy.

  

• Select Cache responses.

  

• Set a caching duration of 15 seconds.
  

  Simple caching configuration is not yet implemented in the Azure Management portal. We shall see later how it can be done using policy expressions.

  

• Configure the Color website from lab 3 to use the Unlimited subscription URL.
• Select Start.

• Notice that for each 15 second period the same color is set.

  

• Looking at the ApiRandomColor GET API policies in the Code View, you’ll see the caching policy defined:

  
      
          <base />
          <cache-lookup vary-by-developer="false" vary-by-developer-groups="false" downstream-caching-type="none" />
      
      
          <base />
      
      
          <base />
          <cache-store duration="15" />
      
      
          <base />
      
  
  

Task 4: Transformation Policy

Color API

Transformation – replace string

The find-and-replace policy finds a substring in a request or response and replaces it with a different string.

• Open the Color API, then open the ApiRandomColorGet operation.
• Enter the Policy code editor in the Outbound processing section.
• Place the cursor after the  element in the  section.

• Press Show snippets, then select the Find and replace string in body transformation policy.

  

• Fill in the from and to values accordingly:

  
      <base />
      <find-and-replace from="blue" to="yellow" />
      <cache-store duration="15" />
  
  

  

• Save the policy, then invoke the API using the Unlimited subscription key.

  

Star Wars API

Transformation – conditional

Policies can be applied very granularly. In this example, you are modifying the Star Wars API to return a limited set of information if the caller is using the Starter subscription. Other products, such as the Unlimited subscription, will receive the full response.

The context variable that is implicitly available in every policy expression provides access to the Response and Product below.

• Open the Star Wars API, then open the GetPeopleById operation.

• Similarly to the Color API, add the outbound policy to conditionally change the response body.
  Note that the inbound Accept-Encoding header is set to deflate to ensure that the response body is not encoded as that causes the JSON parsing to fail.

  
      
          <base />
          <set-header name="Accept-Encoding" exists-action="override">
              deflate
          
      
      
          <base />
      
      
          <base />
              
                  <when condition="@(context.Response.StatusCode == 200 && context.Product.Name.Equals("Starter"))">
                      @{
                              var response = context.Response.Body.As();
  
                              foreach (var key in new [] {"hair_color", "skin_color", "eye_color", "gender"}) {
                                  response.Property(key).Remove();
                              }
  
                              return response.ToString();
                          }
                      
                  
              
          
      
          <base />
      
  
  

• Test the API on the Test tab with id 1 and apply the appropriate Starter or Unlimited product scope. Examine the different responses.

• With Starter product scope:

  

• With Unlimited product scope. Notice the four properties in red that are not included in the Starter scope response.

  

Calculator API

Transformation – XML to JSON

A frequent requirement is to transform content, especially to maintain compatibility with legacy APIs. For this lab we are going back to the Calculator API that returned an XML response.

• Add an outbound policy to the Add two integers operation on the Calculator API to transform the response body to JSON.

  
      <base />
      <xml-to-json kind="direct" apply="always" consider-accept-header="false" />
  
  

• Test the API and examine the response. Note that it’s now JSON.

  

Delete response headers

A frequent requirement is to remove headers, especially ones that return security-related or superfluous information.

• Add an outbound policy to the same Calculator API operation to remove specific response headers.

  
      <base />
      <xml-to-json kind="direct" apply="always" consider-accept-header="false" />
      <set-header name="x-aspnet-version" exists-action="delete" />
      <set-header name="x-powered-by" exists-action="delete" />
  
  

• Invoke the API and examine the response, which now no longer contains the two headers. See above screenshot for how it looked prior.

  

Amend what’s passed to the backend

Query string parameters and headers can be easily modified prior to sending the request on to the backend.

• Back in the same Calculator API operation, add inbound policies to modify the query string and headers.

  
      <base />
      <set-query-parameter name="x-product-name" exists-action="override">
          @(context.Product.Name)
      
      <set-header name="x-request-context-data" exists-action="override">
          @(context.Deployment.Region)
      
  
  

• Test the call by using either the Starter or Unlimited product, then inspect the result on the Trace tab.

  

  

Task 5: Named Values 

Calculator API

Named Values collection

Named Values (aka Properties) are a collection of key/value pairs that are global to the service instance. These properties can be used to manage string constants across all API configurations and policies. Values can be expressions, secrets (encrypted by APIM), or Key Vault, which links to a corresponding secret in Azure Key Vault.

• Open the Named values blade in the resource menu and press + Add.
• Create the new property:
  • Name: TimeNow
  • Display name: TimeNow
  • Type: Plain

  • Value: @(DateTime.Now.ToString())

    

• Back in the APIs blade, open the Add two integers operation in the Calculator API.
• Amend the set-header policy by clicking on the pencil icon.
• Create a new header by pressing + Add header:
  • Name: x-request-received-time
  • Value: {{TimeNow}}
  • Action: override

• The corresponding XML in the Code editor view should look like this:

  
      <base />
      <set-query-parameter name="x-product-name" exists-action="override">
          @(context.Product.Name)
      
      <set-header name="x-request-context-data" exists-action="override">
          @(context.Deployment.Region)
      
      <set-header name="x-request-received-time" exists-action="override">
          {{TimeNow}}
      
  
  

• Test the operation by selecting the Starter or Unlimited product scope.

• Examine the backend trace to find the added header with the evaluated named value:

  {
    "name": "x-request-received-time",
    "value": "12/30/2021 6:10:47 PM"
  }

Task 1: Versios

Task 2: Revision

Revisions

Add a new revision

• Select the Star Wars API v2.
• Select the Revisions tab.

• Add a new revision with description Adding a caching policy.

   

  The new revision is online but not yet current. The previous revision continues to remain the active default. Having added the new revision has not resulted in change for your consumers.

  

Add caching

• Select the GetPeople operation.
  

  Revision 2 automatically became the active revision you are now making changes in. You can also switch between revisions, but be aware that changes to the Current revisions are live immediately.

  

• Add a 10-second caching policy for the GET operation.

  

Test the new revision

• From the Azure portal, test the GetPeople operation.
  

  Note the revision number at the top of the page as well as in the request URL.
  The request URL should look similar to: https://.azure-api.net/sw/v2;rev=2/people/.

  

• Test the API twice. The test trace should then show that the cache-lookup occurred.

  

Make current revision

• Select the Revisions tab.

• Make rev2 the current revision.

  

• Choose to post to the public change log for the API and provide a meaningful update.

  

• The new revision is now the current one. Note that the URL reflects the URL the consumer calls. The old revision is still online and can be accessed with the rev qualifier.

  Unlike versioning, revisioning requires no URL updates for the API consumer.

  

Task 1: Basic Monitoring with Azure Monitor

Task 2: Application Insights 

How to integrate Azure API Management with Azure Application Insights

Azure API Management allows for easy integration with Azure Application Insights – an extensible service for web developers building and managing apps on multiple platforms. This guide walks through every step of such an integration and describes strategies for reducing performance impact on your API Management instance.

Create an Azure Application Insights instance

Before you can use Azure Application Insights, you first need to create an instance of the service.

1. Open the Azure portal and navigate to Application Insights.

   

2. Click + Create, then fill in the form. You may need to create a new Log Analytics Workspace if you don’t already have one.

   

3. Click Review + Create, followed by Create.

Create a connection between Azure Application Insights and Azure API Management service instance

1. Navigate to your APIM instance in the Azure portal.
2. Select Application Insights from the menu on the left.

3. Click + Add.

   

4. Select the previously created Application Insights instance and provide a short description.
5. Click Create.

6. You have just created an Azure Application Insights logger with an instrumentation key. It should now appear in the list.

   

   Behind the scenes, a Logger entity is created in your API Management instance, containing the Instrumentation Key of the Application Insights instance.

Enable Application Insights logging for your API

1. Select APIs from the menu on the left.
2. Click on the Color API.
3. Go to the Settings tab from the top bar.
4. Scroll down to the Diagnostics Logs section.
5. On the Application Insights tab check the Enable box.
6. In the Destination dropdown select the logger you just added in the Application Insights blade.
7. Set sampling to 100 to capture all events.

8. Check the Always log errors checkbox.

   

9. Click Save.

   Overriding the default value 0 in the Number of payload bytes to log field may significantly decrease the performance of your APIs.

   Behind the scenes, a Diagnostic entity named ‘applicationinsights’ is created at the API level.

What data is added to Azure Application Insights

Azure Application Insights receives:

• Request telemetry item for every incoming request (frontend request, frontend response),
• Dependency telemetry item for every request forwarded to a backend service (backend request, backend response),
• Exception telemetry item, for every failed request.

A failed request is a request which:

• failed because of a closed client connection, or
• triggered an on-error section of the API policies, or
• has a response HTTP status code matching 4xx or 5xx.

Generating Test Requests

Any request you make to the Color API in APIM will be subject to being received by Application Insights (recall the 100% sampling). To generate a large amount of requests quickly, you can invoke the API via the Color website. As we are presently caching the output for 15 seconds, you may get a lot of requests with the same color. Please feel free to disable the output caching in the Color API if you would like to see more variety.

Viewing Azure Application Insights Data

• Go back to the Application Insights blade and click on the Application Insights instance.
• In the Application Insights instance, you should be able to see logs and metrics after a few seconds.

• Open the Transaction search to see details on a transactional level:

  

Performance implications and log sampling

Logging all events may have serious performance implications, depending on incoming requests rate, payload size, etc.

Based on internal load tests, enabling this feature caused a 40%-50% reduction in throughput when request rate exceeded 1,000 requests per second. Azure Application Insights is designed to use statistical analysis for assessing application performances. It is not intended to be an audit system and is not suited for logging each individual request for high-volume APIs.

You can manipulate the number of requests being logged by adjusting the Sampling setting (see the steps above). 100% means all requests are logged, while 0% reflects no logging at all. Sampling helps to reduce the volume of telemetry, effectively preventing from significant performance degradation, while still carrying the benefits of logging. Sampling is an effective tool in diagnosing often general operational issues. For example, sampling can identify connectivity or integration issues as these would often occur in high quantity, not singular instances. A sampling rate of 50% is as effective in diagnosing such issues as 100% is.

Skipping logging of headers and body of requests and responses will also have positive impact on alleviating performance issues.

Task 3: Logging with Event Hub

Event Hub Overview

Azure Event Hubs is a fully managed, real-time data ingestion service. Millions of events per second can be aggregated to build dynamic data pipelines.

We can use Event Hubs with API Management to obtain analytics of our API usage.

Create an Event Hubs namespace

An Event Hubs namespace provides a unique scoping container in which you create one or more event hubs. To create a namespace in your resource group using the Azure portal, follow these steps:

1. In the Azure portal select Create a resource at the top left of the screen.

2. Search for Event Hubs, then click on the resource.
   If you cannot find it there, please try the same Event Hubs term in the top search bar.

   

3. Press Create to create the namespace, then enter the following:
   1. Select the Resource Group you created in previous labs.
   2. Enter a unique Namespace name.
   3. Select the Location you used in previous labs.
   4. Choose Basic for the Pricing Tier. To learn about differences between tiers, see Quotas and limits, Event Hubs Premium, and Event Hubs Dedicated articles.
   5. Leave the Throughput Units setting as it is. To learn more about throughput units or processing units: Event Hubs scalability.

   6. Select Review + Create at the bottom of the page, followed by Create.

      

   7. Press Go to resource.

      

   8. Confirm that you see the Event Hubs Namespace page similar to the following example:

      

Create an Event Hub

To create an event hub within the namespace, follow these steps:

1. From the Event Hubs blade select + Event Hub>

   

2. Type a name for your event hub, then select Create.

   The partition count setting allows you to parallelize consumption across many consumers. For more information, see Partitions.

   The message retention setting specifies how long the Event Hubs service keeps data. For more information, see Event retention.

   

3. After the event hub is created, you see it in the list of event hubs.

   

Create Access to the Event Hub

1. Click on the newly-created event hub.
2. Open the Shared access policies blade.

3. Click on + Add.

   

4. On the right side of your screen create a ´sendpolicy´ with just ´Send´ permissions

   

5. Click on the new policy created and copy the Connection string-primary key to a notepad. Also copy the Event Hub namespace. You will use both values in the next section.

   

Create an API Management logger

Now that you have an Event Hub, the next step is to configure a Logger in your API Management service, so that it can log events to the Event Hub.

API Management loggers are configured using the API Management REST API. For this example we are going to use the “REST API Try it” Functionality to create the logger:

1. Open the following link REST API Try It

   

2. Press Sign in and use your Azure credentials that you have been using with this workshop, if prompted.
3. Fill in the following Parameters:
   1. loggerId: eventhublogger
   2. resourceGroupName: your resource group
   3. serviceName: your Azure APIM instance

   4. subscriptionId: your Azure subscription

      

4. Replace the request Body with the following json. Make sure you replace the parameters appropriately:

    {
        "properties": {
            "loggerType": "azureEventHub",
            "description": "adding a new logger",
            "credentials": {
                "name": "",
                "connectionString": ""
            }
        }
    }
   

5. Your request parameters might then look similar to this:

   Note my deviation by intential masking my SharedAccessKey. Please do not alter your key.

    {
        "properties": {
            "loggerType": "azureEventHub",
            "description": "adding a new logger",
            "credentials": {
                "name": "eh-sjk-01062022/myeventhub",
                "connectionString": "Endpoint=sb://eh-sjk-01062022.servicebus.windows.net/;SharedAccessKeyName=sendpolicy;SharedAccessKey=********;EntityPath=myeventhub"
            }
        }
    }
   

6. Press Run.

7. You should get a 201 response, confirming that the resource has been created.

   

Configure log-to-eventhub policies

Once your logger is configured in API Management, you can configure your log-to-eventhub policy to log the desired events. The log-to-eventhub policy can be used in either the inbound policy section or the outbound policy section.

1. Browse to your APIM instance.
2. Select the APIs blade.
3. Select the API to which you want to add the policy.
   In this example, we’re adding a policy to the Echo API.
4. Select All operations.
5. On the top of the screen, select the Design tab.
6. In the Inbound or Outbound processing window, enter the Code editor.
7. Enter a new line after the  tag in the inbound or outbound policy section.
8. Select Show snippets.

9. In the window on the right, select Advanced policies > Log to EventHub. This inserts the log-to-eventhub policy statement template.

   

10. Replace the policy with this snippet:

     <log-to-eventhub logger-id="">
         @{
             return new JObject(
                 new JProperty("EventTime", DateTime.UtcNow.ToString()),
                 new JProperty("ServiceName", context.Deployment.ServiceName),
                 new JProperty("RequestId", context.RequestId),
                 new JProperty("RequestIp", context.Request.IpAddress),
                 new JProperty("OperationName", context.Operation.Name)
             ).ToString();
         }
     
    

11. Replace  with the value you used for {loggerId} in the request URL to create the logger in the previous step (e.g. eventhublogger).

    You can use any expression that returns a string as the value for the log-to-eventhub element. In this example, a string in JSON format containing the date and time, service name, request ID, request IP address, and operation name is logged.

    

12. Click Save to save the updated policy configuration. As soon as it is saved the policy is active and events are logged to the designated Event Hub.

Verify Events are logged in Event Hub

1. Issue a handful of test Echo API calls from within APIM (e.g. Get Retrieve Resource operation).

2. In the Azure portal open the Event Hub you created earlier. You should see recent events. If not, give it a minute, then refresh.

   

What to do with the data that is now in Event Hub is beyond the scope of this lab as this lab primarily focused on APIM to Event Hub integration.

Task 1: JSON Web Token Validation

Task 2: Oauth2 

2.1: Azure APIM and Oauth2

Based on the Microsoft Tech Community blog post by Sherry Sahni.

The API Management is a proxy to the backend APIs, it’s a good practice to implement security mechanism to provide an extra layer of security to avoid unauthorized access to APIs.

In this Diagram we can see the OAUTH flow with API Management in which:

• The Developer Portal requests a token from Azure AD using app registration client id and client secret.
• In the second step, the user is challenged to prove their identity by supplying User Credentials.
• After successful validation, Azure AD issues the access/refresh token.
• User makes an API call with the authorization header and the token gets validated by using validate-jwt policy in APIM by Azure AD.
• Based on the validation result, the user will receive the response in the developer portal.

Different grant types:

High-level steps required to configure OAUTH

To configure Oauth2 with APIM the following needs to be created:

• Register an application (backend-app) in Azure AD to represent the protected API resource.​
• Register another application (client-app) in Azure AD which represent a client that wants to access the protected API resource.​
• In Azure AD, grant permissions to client(client-app) to access the protected resource (backend-app).​
• Configure the Developer Console to call the API using OAuth 2.0 user authorization.​
• Add the validate-jwt policy to validate the OAuth token for every incoming request.​​

2.2: AAD Create a new tenant

1. Sign in to your organization’s Azure portal.

2. From the Azure portal menu, select Create a resource.

   

3. Select Identity, and then select Azure Active Directory.

   The Create directory page appears.

   

4. On the Create directory page, enter the following information:

   • Type Contoso into the Organization name box.

   • Type Contoso into the Initial domain name box.

   • Leave the United States option in the Country or region box.

5. Select Create.

Your new tenant is created with the domain labapimtenant.onmicrosoft.com.

2.3: Authorization Code

In Authorization code grant type, User is challenged to prove their identity providing user credentials. Upon successful authorization, the token end point is used to obtain an access token. The obtained token is sent to the resource server and gets validated before sending the secured data to the client application.

Register an application (backend-app) in Azure AD to represent the Basic Calculator API​

To protect an API with Azure AD, first register an application in Azure AD that represents the API. The following steps use the Azure portal to register the application.

First we need to access our the AAD tenant we created in the excercise before, be sure you are in the right tenant. Then select App registrations under Azure Portal to register an application:

• Select New registration.

• In the Name section, enter a meaningful application name that will be displayed to users of the app. For example oauth-backend-app
• In the Supported account types section, select an option that suits your scenario.
• Leave the Redirect URI section empty.
• Select Register to create the application.

• On the app Overview page, find the Application (client) ID value and record it for later.

• Select Expose an API and set the Application ID URI with the default value. Record this value for later.
• Select the Add a scope button to display the Add a scope page. Then create a new scope that’s supported by the API (for example, Calculator.Read).
• Select the Add scope button to create the scope. Repeat this step to add all scopes supported by your API.
• When the scopes are created, make a note of them for use in a subsequent step.

Register another application (client-app) in Azure AD to represent the Developer Portal( client application)​

Every client application that calls the API needs to be registered as an application in Azure AD. In this example, the client application is the Developer Console in the API Management developer portal. In this case we will register another application in Azure AD to represent the Developer Console:

• Select New registration.

• In the Name section, enter a meaningful application name that will be displayed to users of the app. For example oauth-client-app
• In the Supported account types section, select an option that suits your scenario.
• Leave the Redirect URI section empty.
• Select Register to create the application.

• On the app Overview page, find the Application (client) ID value and record it for later.
• Create a client secret for this application to use in a subsequent step.
  • From the left menu options for your client app, select Certificates & secrets, and select New client secret.
  • Under Add a client secret, provide a Description. Choose when the key should expire and select Add. When the secret is created, note the key value for use in a subsequent step.

Grant permissions for client-app to call backend-app

• Now we have to open our client app and choose the option API permissions
• In here we need to click on Add a permission
• Then choose My APIs
• Select the record for backend-app-oauth

• Then select the Delegated Permissions option
• Then mark the Calculator.Read checkbox
• Then click the Add Permissions button

• Finally click the Grant admin consent for ...

Enable OAuth 2.0 in the Developer Console for Authorization Code Grant type

At this point, we have created the applications in Azure AD, and granted proper permissions to allow the client-app to call the backend-app.

In this demo, the Developer Console is the client-app and has a walk through on how to enable OAuth 2.0 user authorization in the Developer Console. Steps mentioned below:

• In Azure portal, browse to your API Management instance and Select OAuth 2.0 > Add.
• Provide a Display name and Description.
• For the Client registration page URL, enter a placeholder value, such as http://localhost.
• For Authorization grant types, select Authorization code.

Specify the Authorization endpoint URL and Token endpoint URL. These values can be retrieved from the Endpoints page in your Azure AD tenant. Browse to the client App registrations page again and select Endpoints.

ENDPOINTS VERSIONS

We recommend using v2 endpoints. When using v2 endpoints, use the scope you created for the backend-app in the Default scope field. Also, make sure to set the value for the accessTokenAcceptedVersion property to 2 in your application manifest in Azure AD Client APP and Backend app.

• Next, specify the client credentials. These are the credentials for the client-app.
• For Client ID, use the Application ID of the client-app.

• For Client secret, use the key you created for the client-app earlier.
• Immediately following the client secret is the redirect_urls

• Go back to your client-app registration in Azure Active Directory under Authentication.
• Paste the redirect_url under Redirect URI, and check the issuer tokens then click on Configure button to save.

Now that you have configured an OAuth 2.0 authorization server, the Developer Console can obtain access tokens from Azure AD.

The next step is to enable OAuth 2.0 user authorization for your API. This enables the Developer Console to know that it needs to obtain an access token on behalf of the user, before making calls to your API.

• Go to APIs menu under the APIM
• Select the Basic Calculator API and Go to Settings.
• Under Security, choose OAuth 2.0, select the OAuth 2.0 server you configured earlier and select save.

• Publish the developer portal again to refresh this changes

CALLING THE API FROM THE DEVELOPER PORTAL

Now that the OAuth 2.0 user authorization is enabled on your API, the Developer Console will obtain an access token on behalf of the user, before calling the API.

• Copy the developer portal url from the overview blade of apim

• Browse to any operation under the Basic Calculator API in the developer portal and select Try it. This brings you to the Developer Console.
• Note a new item in the Authorization section, corresponding to the authorization server you just added.

• Select Authorization code from the authorization drop-down list, and you are prompted to sign in to the Azure AD tenant. If you are already signed in with the account, you might not be prompted.

• After successful sign-in, an Authorization header is added to the request, with an access token from Azure AD. The following is a sample token (Base64 encoded):

Select Send to call the API successfully with 200 ok response.

Validate-jwt policy to pre-authorize requests with AD token:

At this point we can call the APIs with the obtained bearer token. However, what if someone calls your API without a token or with an invalid token? For example, try to call the API without the Authorization header, the call will still go through. This is because the API Management does not validate the access token, It simply passes the Authorization header to the back-end API.

To pre-Authorize requests, we can use validate-jwt Policy by validating the access tokens of each incoming request. If a request does not have a valid token, API Management blocks it.

We will now configure the Validate JWT policy to pre-authorize requests in API Management, by validating the access tokens of each incoming request. If a request does not have a valid token, API Management blocks it.

• Browses to the APIs from the left menu of APIM
• Click on Basic Calculator Api and open the inbound policy to add the validate-jwt policy(It checks the audience claim in an access token and returns an error message if the token is not valid.) and save it.

• You will need to get the id of your scope, you set from you backend-app registration. Normally this comes in the form api://d183fdbe-fc28-4ef7-9ca1-e7b4a4cd1ff8/Calculator.read , we need to use the id d183fdbe-fc28-4ef7-9ca1-e7b4a4cd1ff8 as audience

<validate-jwt header-name="Authorization" failed-validation-httpcode="401" failed-validation-error-message="Unauthorized. Access token is missing or invalid.">
    <openid-config url="https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration" />
    
        YOUR-BACKENDAPP-SCOPE-ID
    

• Go back to the developer portal and send the api with invalid token.
• You would observe the 401 unauthorized.

• Modify the token from authorization header to the valid token and send the api again to observe the 200-ok response.

UNDERSTANDING VALIDATE-JWT POLICY

In this section, we will be focusing on understanding how validate-jwt policy works (the image in the right side is the decoded JWT Token)

• The validate-jwt policy supports the validation of JWT tokens from the security viewpoint, It validates a JWT (JSON Web Token) passed via the HTTP Authorization header
• If the validation fails, a 401 code is returned. The policy requires an openid-config endpoint to be specified via an openid-config element. API Management expects to browse this endpoint when evaluating the policy as it has information which is used internally to validate the token. Please Note : OpenID config URL differs for the v1 and v2 endpoints.
• The required-claims section contains a list of claims expected to be present on the token for it to be considered valid. The specified claim value in the policy must be present in the token for validation to succeed.

The claim value should be the Application ID of the Registered Azure AD Backend-APP.

Task 3: Managed Identities

Security

Managed Service Identity

In Azure, an Active Directory identity can be assigned to a managed resource such as an Azure Function, App Service or even an API Management instance. Once an identity is assigned, it has many capabilities to work with other resources that leverage Azure AD for authentication, much like a service principal.

REGISTER API MANAGEMENT WITH ACTIVE DIRECTORY

KEY VAULT – CREATE KEY VAULT AND ADD A SECRET

• Create a Key Vault instance
• Add a secret to the Key Vault instance
  • Name:favoritePerson
  • Value: 3

KEY VAULT – ACCESS POLICY AND PRINCIPAL ASSIGNMENT

Create an access policy

Select the Get operation from the list of Secret permissions

Select the principal and search for the name of your API Management instance

Remember to click Save

API MANAGEMENT, KEY VAULT AND MANAGED SERVICE IDENTITY

• Add a new operation to the Star Wars API
• Update the policies for the new operation

<base />
<send-request mode="new" response-variable-name="secretResponse" timeout="20" ignore-error="false">
    https://{your-keyvault-base-uri}.azure.net/secrets/favoritePerson/?api-version=7.0
    GET
    <authentication-managed-identity resource="https://vault.azure.net" />

<set-variable name="favoritePersonRequest" value="@{
    var secret = ((IResponse)context.Variables["secretResponse"]).Body.As<JObject>();
    return "/people/" + secret["value"].ToString() + "/";
}" />
<rewrite-uri template="@((string)context.Variables["favoritePersonRequest"])" />

TEST THE OPERATION

• Test the operation (use the developer portal, Azure portal or tools like Postman and curl)
• Notice the request URL will be similar to: https://{your-apim-instance}.azure-api.net/sw/favorite

Task 1: Azure DevOps + Apim Devops Kit

Please see aka.ms/apimdevops for more guidance and tools around automating deployment across multiple API Management environments.

Continuos Integration and Continuos Deployment using Azure DevOps

The following instructions demonstrate how to deploy the contents of this example repository using Azure DevOps Repos and Azure DevOps Pipelines.

Pre-reqs

There are two options to execute te apim devops kit, locally with .net and azure cli or using the azure cloude shell. Please select your prefered option:

Local

• Dotnet core 3.1 Installed in your local machine
• Azure CLI installed on your local machine

Azure Cloud Shell

• How to enable Cloudeshell

Optional(if you want to deploy with a build pipeline):

• Azure DevOps Account
• An Azure DevOps Repo configured (how to configure an Azure DevOps Repo)

Architecture

This is one example of how to use Azure DevOps Repo and Azure DevOps Pipelines to enable a Continuous Integration and Continuous Deployment (CI/CD) for API's on an Azure API Management Service. There’re other ways to do this, but this is a “Keep it Simple” to help you start. (Planning to have another version using Github and Github Actions soon).

This is our Development API management. In general, developers will create their API's in one instance of APIM to test it.

Create your API’s on API Management Development environment. (How to create API’s on API Management)

APIM DevOps Toolkit

Running the Extractor

After a developer creates and tests APIs in API management, it is time to extract those APIs using this DevOps Resource Kit.

Below are the steps to run the extractor from source code:

• Clone this repository and navigate to {path_to_folder}/src/APIM_ARMTemplate/apimtemplate
  

    git clone https://github.com/Azure/azure-api-management-devops-resource-kit.git
    cd src/APIM_ARMTemplate/apimtemplate
  

• Restore its packages using

    dotnet restore 
  

• Make sure you have signed in using Azure CLI and have switched to the subscription containing the API Management instance from which the configurations will be extracted. Ensure you are using the correct Azure subscription:

   # View subscriptions
   az account list
  

   # Verify selected subscription
   az account show
  

   # Set correct subscription (if needed)
   az account set --subscription 
  
   # Verify correct subscription is now set
   az account show
  

Extractor Arguments

You have two choices when specifying your settings:

• By using a JSON file with key-values where the keys matches the table below. Use the extractorConfig argument:

  extract --extractorConfig c:/temp/extractSettings.json

• Or you can also pass the arguments on the command line. For instance extract --sourceApimName my-feature-apim --destinationApimName company-stable-apim --resourceGroup my-feature-rg --fileFolder c:\\temp\\apim-extract --apiName MyFeatureV1Api

  Where:

  sourceApimName: API Management where you created your API

  destinationApimName: It's just a convention to set the DESTINATION-API-NAME in front of the generated files.

  resourceGroup: Resource group where the DEV-APIM-NAME is hosted.

  fileFolder: (NOTE: git clone and create the local repos before executing the dotnet run extract)

  For more information on how to run the application and parameters, go to this page.

• For this example, we will pass the arguments on the command line. So, run the application with:

    dotnet run extract --sourceApimName  --resourceGroup  --destinationApimName   --fileFolder apim-extract
  

  i.e.

    dotnet run extract --sourceApimName famc-apimlab2 --resourceGroup famc-apimlab2 --destinationApimName famc-apimlab2-prod  --fileFolder apim-extract 
  

After executing the command above, you will see something similar to this:

Then you see the JSON files extracted:

Now, push them to your Azure DevOps Repo

git add *
git commit -a -m "add extracted *.json files to devops repository
git push

Build Pipeline

We will use a Build Pipeline to pull the extracted files from a repo and put it on Azure DevOps Artefacts Folder.

1 – Add these tasks to your build:

• Get Sources
• Copy Publish Artifacts

2 – Configure the fields as show bellow:

Release Pipeline

You can use this document as a reference on how to create a release pipeline.

1 – Add an Azure Deployment tasks for each file generated by the extractor, following the order:

- Products.template.json
- Tags.template.json
- namedValues.template.json
- apis.template.json
- globalServicePolice.template.json

2 – Set “Override template parameters” field with “-ApimServiceName “

3 – Set set Deployment mode to Incremental

When you finish the steps above, you will see something like this:

Clone your QA environment and update the Resource Group and ApimServiceName value on “Override template parameters” field to reflect your “production” APIM.

Now you will see your Release Pipeline like this:

By using a combination of manual deployment approvals, gates, and manual intervention within a release pipeline in Azure Pipelines, you can quickly and easily configure a release pipeline with all the control and auditing capabilities you require for your DevOps CI/CD processes. You will find more information on this link.

Task 1: Powerapp + Azure Apim API

The premier Star Wars Fan club is growing and the club officers would like to upgrade from their existing member tracking worksheet to a mobile application that would be available to their members all over the world. The members would also like to see information about their favorite Star Wars movies and characters in the application that would update as new shows and movies are released.

In this exercise, you will be using Star Wars API with Azure API Management instance that you created in part three of this lab. The Excel worksheet of member profiles will serve as the primary backing data source and will be used to generate a base application. You will export the Star Wars API from API Management as a Power Platform Custom Connector so that the Canvas App can access real-time Star Wars character information. For each of the Fan Club members, you can then search the Star Wars API character data and show information about their favorite character in the Canvas App.

Note: This exercise requires access to Power Apps Premium connectors. Sign up for a free Developer Plan.

Create a custom connector

From the existing Star Wars API Api in Azure API Management, click the ellipsis … and select the Create Power Connector option to generate a custom connector in your Power Platform environment.

If you are unable to create a Power Connector from Azure API Management, you can also export an OpenAPI v2 (JSON) file that can be imported as a Custom Connector within Power Platform. You can find a sample here.

View your custom connector in Power Platform

1. Go to https://make.powerapps.com and sign in with your organizational account.
2. Select Data from the left pane, and then select Custom Connectors to see your generated custom connector to your API Management API.

1. From here, select the pencil icon to edit the custom connector.
2. On the Definition screen, we need to define a search query string for people so that the Power App can search for character records by name. Select the GetPeople action, and in the Request section, select + Import from sample. Enter a sample request URL with the search query string:

https://apim-star-wars-xxxx.azure-api.net/sw/people?search=Luke

1. In the Response section of the getpeople action, select the 200 response and then select + Import from sample. Copy and paste a sample JSON response into the Body section of the response. Close the import panel and select Update connector.

Repeat this import for the getpeoplebyid action.

1. On the Test screen, create a new connection instance in the Connections section. You will then be redirected to the Connections area in Power Platform where your connection was created. Navigate back to the Custom Connectors page and edit the Star Wars API again. Return to the Test page and test each of the API actions.

Generate the Star Wars Fan Club Application

Connect to the backing data source

1. Download the FanClubMembers.xlsx workbook and save it to your OneDrive for Business account.
2. Back in the Power Apps Editor, in the left pane, select Home.
3. Under Start from data , select Other data sources and then select New from the left pane.
4. Select OneDrive for Business data source, and then Phone layout.
5. Under OneDrive for Business , select Create.
6. Under Connections , select OneDrive for Business and browse to the file location. You might need to select New Connection to see the OneDrive for Business connection.
7. Under Choose an Excel file , select the FanClubMembers.xlsx file.
8. Under Choose a table , select the Members table.
9. Select Connect on the bottom right.
10. Power Apps will generate the app by inspecting your data and matching it with Power Apps screens.

Add Favorite Character information

Your generated app will now be in edit mode in the Power Apps Studio.

Add the Star Wars API Data Source

1. Select Data from the left pane and then select + Add data from the drop-down menu.
2. Search for Star Wars in the search field and choose the connection to the Star Wars API.

Customize the generated app

Your generated app will now be in edit mode in the Power Apps Studio.

You can customize your app theme using the Theme drop-down menu and selecting an option. You can change or format the fields that are shown in the Gallery by selecting Tree view in the left pane, clicking on the BrowseGallery1, and making edits in the right formatting pane.

Add controls to the View Detail screen

1. In the Tree view, select DetailScreen1.
2. Select the + icon on the left side of the screen to bring up the Insert panel.
3. Select Text Label and add labels for the Favorite Character section header and for each one of the character description fields.
4. For each label control, change the Text property in the right-side Properties panel to describe each field.
5. Drag the controls on the screen so they are below the header and are aligned with the center of the screen.

Connect the Detail Screen to the Star Wars API

1. In the left pane, select the Tree view and then the BrowseGallery1 on Browsescreen1.
2. Using the drop-down menu, select the OnSelect action that will be executed when a user selects a Fan Club member from the gallery.
3. In the OnSelect function, we will navigate to DetailScreen1 and call the Star Wars API to get the character details for the member's favorite character.

Navigate(DetailScreen1, ScreenTransition.None);

ClearCollect(characterCollection, StarWarsAPI.getpeople({search: ThisItem.MemberFavoriteCharacter}).results);

Show the Star Wars character information on the Detail Screen

1. For each of the description labels on DetailScreen1 , change the Text property in the right-side Properties panel to include the data from the API. For example, for the Name: label:

"Name:" & " " & First(characterCollection).name

1. Select Play in the upper-right corner to practice using the app.

Task 1: Architecture Desing Session

Task 2: Provision your own instance of ColoursWeb/ColoursAPI

Some of the demos use the ColourWeb web application and the ColourAPI API application. In this lab we will show you how to deploy your own instances of the Colours Web and Colours API. Note – ColoursWeb / ColoursAPI is new version of ColorsWeb/ColorsAPI … do not mix the web client and API versions.

The code for the ColourWeb / ColourAPI applications is available here:

• ColourWeb
• ColourApi

Docker Containers exist for these applications and so provides an easy deployment option ( IMPORTANT : due to the new pull restrictions on Docker Hub images, in this lab we will be using the GitHub registry):

• Github (Colours)
  • docker pull ghcr.io/markharrison/coloursapi:latest
  • docker pull ghcr.io/markharrison/coloursweb:latest
• DockerHub (Colors)
  • docker pull markharrison/colorweb:latest
  • docker pull markharrison/colorapi:latest

With the container we can deploy to multiple hosting options : VM’s, App Services, ACI and also AKS. In this lab we are going to show you how to do it with Azure Container Instances.

Deploying Web and API containers with Azure Container Instances

1. Login to Azure Portal at http://portal.azure.com.

2. Open the Azure Cloud Shell and choose Bash Shell (do not choose Powershell)

   

3. The first time Cloud Shell is started will require you to create a storage account.

4. We proceed to create a unique identifier suffix for resources created in this Lab:

    APIMLAB_UNIQUE_SUFFIX=$USER$RANDOM
    # Remove Underscores and Dashes
    APIMLAB_UNIQUE_SUFFIX="${APIMLAB_UNIQUE_SUFFIX//_}"
    APIMLAB_UNIQUE_SUFFIX="${APIMLAB_UNIQUE_SUFFIX//-}"
    # Check Unique Suffix Value (Should be No Underscores or Dashes)
    echo $APIMLAB_UNIQUE_SUFFIX
    # Persist for Later Sessions in Case of Timeout
    echo export APIMLAB_UNIQUE_SUFFIX=$APIMLAB_UNIQUE_SUFFIX >> ~/.bashrc
   

5. Now we proceed to create a resource group for our ACI objects:

    #we define some variables first
    APIMLAB_RGNAME=myColorsAppRg-$APIMLAB_UNIQUE_SUFFIX
    APIMLAB_LOCATION=eastus
    # Persist for Later Sessions in Case of Timeout
    echo export APIMLAB_RGNAME=$APIMLAB_RGNAME >> ~/.bashrc
    echo export APIMLAB_LOCATION=$APIMLAB_LOCATION >> ~/.bashrc
   
    #we create the resource group
    az group create --name $APIMLAB_RGNAME --location $APIMLAB_LOCATION
   

6. Now we create our ACI and specify our colors-web github container

   #we define some variables first
   APIMLAB_COLORS_WEB=mycolorsweb-$APIMLAB_UNIQUE_SUFFIX
   APIMLAB_IMAGE_WEB=ghcr.io/markharrison/coloursweb:latest
   APIMLAB_DNSLABEL_WEB=acicolorweb$APIMLAB_UNIQUE_SUFFIX
   # Persist for Later Sessions in Case of Timeout
   echo export APIMLAB_COLORS_WEB=$APIMLAB_COLORS_WEB >> ~/.bashrc
   echo export APIMLAB_IMAGE_WEB=$APIMLAB_IMAGE_WEB >> ~/.bashrc
   echo export APIMLAB_DNSLABEL_WEB=$APIMLAB_DNSLABEL_WEB >> ~/.bashrc
   
   
   #we create the container instance for the colors web
   az container create --resource-group $APIMLAB_RGNAME --name $APIMLAB_COLORS_WEB --image $APIMLAB_IMAGE_WEB --dns-name-label $APIMLAB_DNSLABEL_WEB --ports 80 --restart-policy OnFailure --no-wait
   

7. Now we run the following command to check the status of the deployment and get the FQDN to access the app:

    #we check the status
    az container show --resource-group $APIMLAB_RGNAME --name $APIMLAB_COLORS_WEB --query "{FQDN:ipAddress.fqdn,ProvisioningState:provisioningState}" --out table
   

   The output should something like this:

    FQDN                                                  ProvisioningState
    ----------------------------------------------------  -------------------
    aci-color-web-fernando22287.eastus.azurecontainer.io  Succeeded
   

   Once we have a “Succeeded” message we proceed to navigate to the FQDN. And we should see our home page for our Colours Web:

   

8. Now we proceed to create the ACI for the colors-api github container:

   #we define some variables first
   APIMLAB_COLORS_API=mycolorsapi-$APIMLAB_UNIQUE_SUFFIX
   APIMLAB_IMAGE_API=ghcr.io/markharrison/coloursapi:latest
   APIMLAB_DNSLABEL_API=aci-color-api-$APIMLAB_UNIQUE_SUFFIX
   # Persist for Later Sessions in Case of Timeout
   echo export APIMLAB_COLORS_WEB=$APIMLAB_COLORS_WEB >> ~/.bashrc
   echo export APIMLAB_IMAGE_WEB=$APIMLAB_IMAGE_WEB >> ~/.bashrc
   echo export APIMLAB_DNSLABEL_WEB=$APIMLAB_DNSLABEL_WEB >> ~/.bashrc
   
   
   #we create the container instance for the colors api
   az container create --resource-group $APIMLAB_RGNAME --name $APIMLAB_COLORS_API --image $APIMLAB_IMAGE_API --dns-name-label $APIMLAB_DNSLABEL_API --ports 80 --restart-policy OnFailure --no-wait
   

9. Now we run the following command to check the status of the deployment and get the FQDN to access the app:

   #we check the status
   az container show --resource-group $APIMLAB_RGNAME --name $APIMLAB_COLORS_API --query "{FQDN:ipAddress.fqdn,ProvisioningState:provisioningState}" --out table
   

   The output should something like this:

   FQDN                                                  ProvisioningState
   ----------------------------------------------------  -------------------
   aci-color-api-fernando22287.eastus.azurecontainer.io  Succeeded
   

   Once we have a “Succeeded” message we proceed to navigate to the FQDN. And we should see our home page (Swagger UI) for our Colours API:

   

Task 3: API Proxy to Serverless

Azure Serverless (Functions and Logic Apps) can be configured to benefit from the advantages of API Management.

Azure Functions

• Create a simple function that is Triggered by an HTTP Request

Example:

    //string[] strColors = { "blue", "lightblue", "darkblue" };
    string[] strColors = { "green", "lightgreen", "darkgreen" };

    Random r = new Random();
    int rInt = r.Next(strColors.Length);

    return  (ActionResult)new OkObjectResult(strColors[rInt]);

Lets add the function to API Management. In the API blade select [+Add API] and the [Function App] tile

• Select the [Browse] button to get a list of Functions in the subscription

• Select the Function App and then the Function

• Amend the Names / Descriptions, URL suffix and select the Products

• As previously add CORS policy

• Validate the function works – either from the Azure management portal or the developer portal

Azure Logic Apps

• Create a simple logic app that is Triggered by an HTTP Request

Example:

Use the following sample message to generate the schema of the Request body payload. By specifying the schema, the individual fields (in this case msg) can be extracted and referred to in the subsequent logic

{
  "msg": "text"
}

Lets add the function to API Managament. In the API blade select [+Add API] and the [Logic App] tile

• Select the [Browse] button to get a list of Logic Apps in the subscription

• Select the Logic App

• Amend the Names / Descriptions, URL suffix and select the Products

As previously add CORS policy

• Validate the Logic App works – either from the Azure management portal or the developer poral

• Check the Logic App audit

• Check the email was sent

Task 4: Self-hosted Gateway

With the API Management self-hosted gateway, organisations have the ability to deploy an instance of the APIM gateway component to the environments where they host their applications and/or APIs – for example, in an on-premise data center.

The self-hosted gateways are hosted in a Docker or Kuberenetes environment, and are managed from the API Management service they are connected to.

This part of the lab assumes that the user has Docker Desktop installed. Installation instructions are here

There are two terms to become familiar with:

• Gateway Deployment … this is a set of APIM configuration details that will be used by the Gateway Node(s)
• Gateway Node … this is a running instance of a APIM gateway proxy i.e. a containerised instance of the gateway

There can be multiple Gateway Deployments and multiple Gateway Nodes. The Gateway Deployments are chargeable – the Gateway Nodes are free i.e. an organization pays for the management control plane, but the compute is free (you are running on the organizations own hardware)

Deploy the Self-hosted Gateway

To deploy a self-hosted gateway:

• Select the Gateways option from the menu
• Select + Add

• Enter a Name and Location for the Gateway
• Select the required APIs from those that are configured in the APIM instance
  • Our lab will use the Color API – this was configured in an earlier module
• Select the Add button

The added gateway will appear in the list … this is the Gateway Deployment.

• Click on the gateway in the list – a blade appears allowing further configuration

• Select the Deployment option from the menu
  • There are scripts for deploying on Docker and Kuberenetes … for this lab, we will be using the Docker option
• Save the env.conf file to your desktop
• Copy the Docker run command but remove the -d parameter … this is so the logs are displayed to the terminal

docker run -p 80:8080 -p 443:8081 --name OnPremiseGateway --env-file env.conf mcr.microsoft.com/azure-api-management/gateway:latest

From a command line – elevated to Administrator (needed for Docker commands)

• Navigate to the location where the env.conf is located
• Run the Docker run command

The first time this is executed, it will need to pull down the Docker image – and so there will be a small delay. Subsequently – if restarted – it will just use the downloaded image.

Once downloaded, the log output from the container will display a Sputnik logo (this was an internal code name) and some diagnostic logs.

Note that in the Gateway blade we can see the status – it will show there is one healthy Gateway Node connected to the Deployment. The Gateway Node will keep in sync, and be automatically updated should any of the Gateway Deployment config changes.

Testing the API

Our Gateway Node is now deployed – and we can test that it works.

• Open Developer portal, go in the Profile page and get API key for Unlimited products
• Open Notepad – make note of URLs including the key. For our lab test, the machine name is just localhost
  • https://localhost/color/api/RandomColor?key=Unlimited-Key

• Use a tool like Postman to test the API … should see the random color appear in the response and this confirms everything is working properly
• If tested with a browser, then a warning needs to accepted to proceed – this is because trusted TLS certificates have not been set up

Diagnostics for the API call will be logged by the container.