In this blog I will show you how to add authorisation to a MCV Controller, setup Azure AD as an OAuth 2.0 JWT (Json Web Token) provider and use an Azure AD endpoint to obtain the access token. I will be using Client Credentials grant flow to access a protected Web API resource.
Client Credential flow uses a Client Id and a Client Secret values. These are sent to an OAuth token provider to retrieve an access token first. This is ideal for a client application calling a web service resource without a user supplying their login credentials. The following sequence diagram shows how a website would call a web service.
Registering the Web API Service
Lets first start by provisioning an Azure Active Directory using the classic portal as we will require the generated Audience and Tenant values for our MVC Web API latter.
Next add a name for your Directory and a unique Domain Name to use. For this example I called it “connectedcircuits”
Once the Domain has been configured it will be shown in your active directory listings.
Next we will add an Application to this domain for the Web API we are developing. Now click on Applications. It will have a default application already registered for Office 365 Management APIs.
Scroll down to the bottom of the page and click the Add button. It will then show the following dialogue box. Select “Add an application my organisation is developing”
Give it a suitable name and select “Web Application and/or Web API”
In the next screen you can set the Sign-on URL to “http://localhost” as we won’t be using this URL for Client Credential flow.
Now add an App ID URI for the API we will be developing. It must be unique within your organisation’s directory. In our scenario I have chosen “https://connectedcircuits.onmicrosoft.com/DemoProtectedAPI” which represents the domain and the name of the Web API we will be building.
We can now start on building the MVC Web API. Create a new ASP.NET Web Application project in Visual Studio.
Select the Web API template, set the Authentication to “No Authentication” and uncheck “Host in the cloud”. We will setup the authentication manually and host this locally in IIS Express for now.
Once the template solution is created install the following Nuget packages to the project.
- Install-Package Microsoft.Owin
- Install-Package Microsoft.Owin.Security.ActiveDirectory
- Install-Package Microsoft.Owin.Host.SystemWeb – this package is required when hosting your API in IIS express.
- Install-Package Microsoft.AspNet.WebApi.Owin.
- Install-Package System.IdentityModel.Tokens.Jwt -Version 4.0.2.206221351
After the packages have been installed, add a new partial class called Startup.cs to the App_Start folder.
Add the following code into this class. This class reads the configuration settings in the web.config file and initialises the Owin authentication.
1: using Microsoft.Owin;
2: using Owin;
3: using System.Web.Http;
4: using Microsoft.Owin.Security.ActiveDirectory;
5: using System.Configuration;
6: using System.IdentityModel.Tokens;
7:
8: [assembly: OwinStartup(typeof(DemoProtectedAPI.App_Start.Startup))]
9:
10: namespace DemoProtectedAPI.App_Start
11: {
12: public partial class Startup
13: {
14: public void Configuration(IAppBuilder app)
15: {
16: HttpConfiguration config = new HttpConfiguration();
17: ConfigureAuth(app);
18: WebApiConfig.Register(config);
19:
20: app.UseWebApi(config);
21: }
22:
23: private void ConfigureAuth(IAppBuilder app)
24: {
25: var tokenValidationParameter = new TokenValidationParameters();
26: tokenValidationParameter.ValidAudience = ConfigurationManager.AppSettings["Azure.AD.Audience"];
27: app.UseWindowsAzureActiveDirectoryBearerAuthentication(
28: new WindowsAzureActiveDirectoryBearerAuthenticationOptions
29: {
30:
31: Tenant = ConfigurationManager.AppSettings["Azure.AD.Tenant"],
32: TokenValidationParameters = tokenValidationParameter
33:
34: });
35:
36: }
37: }
38: }
In the web.config add the two keys to the <appSettings> section shown in the code below. The Tenant value is the domain name that was specified when creating the directory and the Audience value is the App ID URL that was given when adding an application to the directory.
1: <appSettings>
2:
3: <add key="Azure.AD.Tenant"
4: value="connectedcircuits.onmicrosoft.com" />
5: <add key="Azure.AD.Audience"
6: value="https://connectedcircuits.onmicrosoft.com/DemoProtectedAPI" />
7:
8: </appSettings>
Now to protect the methods in a a Controller, add the [Authorize] attribute to the class as shown below.
One final step is to turn on the SSL requirement for this project as oAuth2 relies on using a secure channel. Click on the project to display the Properties page and set the SSL Enabled to True. Take note of the URL and port number.
Now if you try and navigate to the GET Values method you should get an authorization error as shown below:
Registering the client app
To be able to get access to the methods exposed in the MVC Controller, you will need to send a bearer token in the Authorization HTTP Header. To get the token we will need to setup another application for the client in the same domain as the Web API Service.
From the Azure Classic Portal, go to the Active Directory resources and select the name of the active directory that was created at the beginning of this blog. Click on Applications and then click on the Add button at the bottom of the page.
Again select “Add an application my organization is developing”. In the dialogue box give it a suitable name and set the type to Web Application and/or Web API as shown below.
In the next screen, you can set the sign-on URL to http://localhost as it is not used for this type of authentication flow. The APP ID URI should be set to a unique value, its used as a unique logical identifier for your app.
Once it has been created, click “Configure” and scroll to the bottom of the page and click the button “Add application”. This is how we associate the web service you created earlier with your application.
Set the “Show” dropdown control to “All Apps” and click the Tick icon. This should display all the apps listed in your domain. Highlight your web service and click on the plus icon.
After clicking the plus icon, the app will be shown in the Selected column. Then click the “Tick” icon at the bottom of the page to return back the Configure page.
Back on the Configure page, set the delegated permissions on the App you just added from the previous web page as shown below and click save.
Now we need to obtain the client key to be used for obtaining the JWT. Scroll up to the keys section and generate a new key. Note the key won’t be shown until you press the save button at the bottom of the page and you will need to take a copy of this key.
Next we will need top take a copy of the client Id which is also on the Configure page.
The last piece we need is the endpoint of the OAuth token. This is found by scrolling to the bottom of the page and pressing the View Endpoints button.
Now take a copy of the OAuth token endpoint.
We now have the 4 pieces of information required to request the JWT.
- Web API endpoint – the specified App ID URI when registering the Web API service.
- Client Id – created when registering the client app.
- 7f1fd29a-d20f-4158-8f47-eff1ea87dc38
- Client Key – generated when registering the client app.
- OPAfMI4IixoYnGAPiCpLvAvYecH92TXcC1/8wH31HD0=
- OAuth 2.0 token endpoint – App endpoints from either the Web API or Client App.https://login.microsoftonline.com/f3301fa6-4178-44a9-b5a9-e945e69e4638/oauth2/token
Using the above information we make a POST to the OAuth token endpoint using the following raw body form content to get a bear token. resource=<web_api_endpoint>&grant_type=client_credentials&client_id=<client_id>&client_secret=<client_key>
Using a tool like PostMan, POST the following request. Note the generated Client Key needs to be URL encoded and set the header Content-Type: application/x-www-form-urlencoded.
Actual Token request message shown below.
POST /f3301fa6-4178-44a9-b5a9-e945e69e4638/oauth2/token HTTP/1.1
Host: login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded
Cache-Control: no-cache
resource=https://connectedcircuits.onmicrosoft.com/DemoProtectedAPI&grant_type=client_credentials&client_id=7f1fd29a-d20f-4158-8f47-eff1ea87dc38&client_secret=OPAfMI4IixoYnGAPiCpLvAvYecH92TXcC1%2F8wH31HD0%3D
If all went well you should get the following response as a JSON Web Token (JWT).{ “token_type”: “Bearer”,
“expires_in”: “3600”,
“ext_expires_in”: “0”,
“expires_on”: “1480196246”,
“not_before”: “1480192346”,
“resource”: “https://connectedcircuits.onmicrosoft.com/DemoPortectedAPI“,
“access_token”: “<token string>” }
Now to access the Web API service, we need to pass the access_token value in the request Authorisation header as a bearer token. Take note the value of the Authorization header key requires the oAuth token to be prefixed with “Bearer” and a blank space.
The raw request is shown below and the bearer token has been truncated for clarity.
GET /api/Values HTTP/1.1
Host: localhost:44312
Authorization: Bearer GET /api/Values HTTP/1.1
Host: localhost:44312
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiI…
Cache-Control: no-cache
Postman-Token: 1eb00cbd-6eb9-c7b0-182d-a55fcd4f044a
Enjoy.