API-APP server-to-server through Azure Active Directory

In the previous post you see how register your API app in the AAD and how register a client app to then access using RESTful AAD api. The work to do to access your API is not so much using any langue, btw is even more easy using .NET.

The POC

Creates a new Console project and then add Microsoft.IdentityModel.Clients.ActiveDirectory package.

Now add this class to your project

using Microsoft.IdentityModel.Clients.ActiveDirectory;
using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Threading;
using System.Threading.Tasks;

namespace ClientFor1MApi
{
  public class ActiveDirectoryAuthHandler : DelegatingHandler
  {
    private const int maxAuthRetry = 3;
    private readonly AuthenticationContext authContext;
    private readonly ClientCredential clientCredential;
    private readonly string appIdUri;

    public ActiveDirectoryAuthHandler(AuthenticationContext authContext
      , ClientCredential clientCredential
      , string appIdUri
      , HttpMessageHandler innerHandler) : base(innerHandler)
    {
      this.authContext = authContext ?? throw new ArgumentNullException(nameof(authContext));
      this.clientCredential = clientCredential ?? throw new ArgumentNullException(nameof(clientCredential));
      this.appIdUri = appIdUri ?? throw new ArgumentNullException(nameof(appIdUri));
    }

    public ActiveDirectoryAuthHandler(AuthenticationContext authContext
      , ClientCredential clientCredential
      , string appIdUri) : base(new HttpClientHandler())
    {
      this.authContext = authContext ?? throw new ArgumentNullException(nameof(authContext));
      this.clientCredential = clientCredential ?? throw new ArgumentNullException(nameof(clientCredential));
      this.appIdUri = appIdUri ?? throw new ArgumentNullException(nameof(appIdUri));
    }

    protected override async Task<HttpResponseMessage> SendAsync(HttpRequestMessage request, CancellationToken cancellationToken)
    {
      var authResult = await GetAuth();
      if (authResult != null)
      {
        request.Headers.Authorization = new AuthenticationHeaderValue(authResult.AccessTokenType, authResult.AccessToken);
      }
      return await base.SendAsync(request, cancellationToken);
    }

    private async Task<AuthenticationResult> GetAuth()
    {
      int retryCount = 0;
      bool mustRetry;

      do
      {
        mustRetry = false;
        try
        {
          // ADAL includes an in memory cache, so this call will only send a message to the server if the cached token is expired.
          return await authContext.AcquireTokenAsync(appIdUri, clientCredential);
        }
        catch (AdalException ex) when (ex.ErrorCode == "temporarily_unavailable")
        {
          mustRetry = true;
          retryCount++;
          await Task.Delay(3000);
        }
      } while ((mustRetry == true) && (retryCount < maxAuthRetry));

      return null;
    }
  }
}

We will use the implementation of HttpMessageHandler for the pipeline of the instance of HttpClient we will use to access to our API.
The HtppMessageHandler needs three parameters: AuthenticationContext, ClientCredential and appIDUri. To create each one we needs some information we have seen in the previous post and to be consistent I will reuse the same images.

The AuthenticationContext

To create an instance of the AuthenticationContext we need only the URL of the AAD where our API-app and our client are registered. It should look something like this:

The ClientCredential

To create an instance of ClientCredential we need the “Application ID” and the “Key” of our client registered un our AAD:
the Application ID is

the key is

The appIDUri

The App ID URI is the value we give to our API-app registered in our AAD

The usage of ActiveDirectoryAuthHandler

  public class Program
  {
    static void Main(string[] args)
    {
      var aadInstance = "https://login.microsoftonline.com/yourAaadDomain.onmicrosoft.com";
      var clientAppId = "1e852e38-2ef9-439b-b696-dccaa811562c";
      var clientAppKey = "vRSDlEOAFrYi59zoVQyuamJv0ZPRegZTd87ugngD8aU=";
      var apiAppIdUri = "https://The1MApi.azurewebsites.net";

      var httpClient = new HttpClient(new ActiveDirectoryAuthHandler(
        new AuthenticationContext(aadInstance)
        , new ClientCredential(clientAppId, clientAppKey)
        , apiAppIdUri
        ))
      {
        BaseAddress= new Uri("https://The1MApi.azurewebsites.net")
      };

      var _ = httpClient.PostAsync("api/values"
        , new FormUrlEncodedContent(new Dictionary<string, string> { { "value", "a new value from client" } })).Result;

      var response = httpClient.GetAsync("api/values").Result;

      Console.Write(response.Content.ReadAsStringAsync().Result);

      Console.ReadLine();
    }
  }

Just remember that the instance of the HttpClient should be a singleton with the same lifecycle of your application.

Web API access through Azure Active Directory

In the past year I realized that is not so clear that any request arrive to our Web app or API app was analyzed by a Gateway; after deliver an API the question was the same: “Nice! the API is the opened to the world, how we can protect the access to our API ?”

The picture

As you can see the gateway is already there; is you don’t activate the authentication it just send, to your app, all requests.

Start protecting your API with Azure Active Directory (AAD)

I’m assuming you having your 1M USD API already deployed in your Azure subscription and you can access to it. Now follow this steps.
1. Go to the Azure portal, select your WebApp and select the authentication option. You should see something like this:
 
2. Turn On the Authentication button

3. select the Azure Active Directory option to configure it.
NOTE: for this step you need “Global Admin” access to the AAD associated to the azure-subscription where your API was deployed. If you don’t have needed permissions don’t worry, somebody else can register the app for you and you can select it in the follow panel.

After select “Express”, what you need is just give a name, to recognize it in AAD, to your app.
4. back to the panel of step 2 you will see the AAD configured and you have to change the action to take when a request come to your app and then Save the configuration.

That’s all; without touch a single line of you API now, your API, is protected by AAD. If you try to access to your API you will see Azure asking you a login following the OAuth2 flow.

What happened in AAD

Because, sometimes, you don’t have permission to register an app in the AAD, is important to see what happened there and what is really important for us (poor tovarishch developers).
1. We having a new application registered

2. The “Express” process (point 3 of previous section) have configured some properties of our new App and you have to know it because someone are important to access to your API from another application and some others are important if you need to explain how register the app in the AAD.



In the “Properties” panel you have the name and home-page but from there you, as developer, have to know the “App ID URI”. For the “Reply URLs” you have to provide the URL of your API (not so much important for web-API). To allow users (developers) of your AAD to access to your API you must be sure on what is the configuration of “Required permissions”.

Allow access your Web-API from server-app (no web frontend)

With the previous steps we having a Web-app or an API-app where user have to login that can be enough for a web-app, or any web-enabled app, but a disaster if we need to consent access to a server unattended application. To consent access to a server application we need some others steps.
1. Add appRole to our API manifest

the result of our modification should look something like this:

The properties “description”, “displayName”, “id”, “value” are up to you (IIRC the id have to be a GUID).
2. Save the manifest
3. Back to our AAD register a trusted server application to consent access to you API


The name of the application is should be something that help you to recognize it and the “Sign-on URL” is whatever sound as a valid URL even if you know that the server app has no endpoints.






4. Back to the AAD you should see the new registered app and we can start configuring it

In this case there are two things really important.
5. Add a new Required Permission

take care to not trust what you see in the first list; you have to search your registered app and Select it (button at bottom).
6. Then add the real required permission

The permission we are adding here is the same we have added to the Manifest of our API app. Check it, Select it, and “Done” it.
7. If the permission was added successfully you should see something like this

8. The last step is set the key piece to access your API (aka client-secret, aka app-secret)

After select the expiry you have to save the configuration and REMEMBER to copy the key value or you will have to create a new one.

9. We need another piece to give to our API client: the Application ID.

The state

At this point we having:

1. Our API app registered and protected by AAD; if you want access to your API-app you have to login, with the credential registered in your AAD, following the OAuth2 flow.
2. A client-application, whos have access to out our API-app, with its Application-ID and its Application-Key (step 8)

Our “Client application” can access to our API-app using REST in two steps (if your client is implemented with .NET then wait a little bit for the next post).

Access your Web-API from server-app

To test our access grant from REST I will use POSTMAN

• the URL is the AAD Auth server to obtain a token for our API (the same used for lot of Microsoft’s services… scusate se é poco)
• the client_id header is the “Application ID” of the API client (step 9)
• the client_secret is the “key” of the API client (step 8)
• the resource is the “App ID URI”of our API-app (point 2 of “What happened in AAD”)

The content of the response is what our API-Client have to use to authenticate itself accessing to our API-app.

When we try to access our API-app we have to add the Authorization header with the previous obtained token_type and access_token. The client application can use the same access_token for the expiration time (3600 = 3600 seconds) and then it have to request a new access_token in the same way. Because the request of the access_token is time-expensive the client application should retain the obtained token for the time specified in expires_in property. The process to access our API-app is RESTful and so it can be implemented from lot of languages.