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.