services: active-directory platforms: dotnet author: kalyankrishna1 level: 300 client: .NET Desktop App (WPF) service: ASP.NET Web API endpoint: AAD v2.0

How to manually validate a JWT access token using Microsoft identity platform (formerly Azure Active Directory for developers)

About this sample

A Web API that accepts bearer token as a proof of authentication is secured by validating the token they receive from the callers. When a developer generates a skeleton Web API code using Visual Studio, token validation libraries and code to carry out basic token validation is automatically generated for the project. An example of the generated code using the asp.net security middleware and Microsoft Identity Model Extension for .NET to validate tokens is provided below.

public void ConfigureAuth(IAppBuilder app)
{
    app.UseWindowsAzureActiveDirectoryBearerAuthentication(
        new WindowsAzureActiveDirectoryBearerAuthenticationOptions
        {
            Tenant = ConfigurationManager.AppSettings["ida:Tenant"],
            TokenValidationParameters = new TokenValidationParameters {
                    ValidAudience = ConfigurationManager.AppSettings["ida:Audience"]
            },
        });
}

The code above will validate the issuer, audience, and the signing tokens of the access token, which is usually sufficient for most scenarios. But often the developer's requirements are more than what these defaults provide. Examples of these requirements can be:

• Restricting the Web API to one or more Apps (App IDs)
• Restricting the Web API to just one or more tenants (Issuers)
• Implement custom authorization.

Always verify that the access token presented to the Web Api has the expected scopes or roles

This sample demonstrates how to manually process a JWT access token in a web API using the JSON Web Token Handler For the Microsoft .Net Framework. This sample is equivalent to the NativeClient-DotNet sample, except that, in the TodoListService, instead of using OWIN middleware to process the token, the token is processed manually in application code. The client, which demonstrates how to acquire a token for this protected API, is unchanged from the NativeClient-DotNet sample.

Scenario: protecting a Web API - acquiring a token for the protected Web API

When you want to protect a Web API, you request your clients to get a Security token for your API, and you validate it. Usually, for ASP.NET applications this validation is delegated to the OWIN middleware, but you can also validate it yourself, leveraging the System.IdentityModel.Tokens.Jwt library.

Token Validation

A token represents the outcome of an authentication operation with some artifact that can be unambiguously tied to the Identity Provider that performed the authentication, without relying on any special network infrastructure.

With Azure Active Directory taking the full responsibility of verifying user's raw credentials, the token receiver's responsibility shifts from verifying raw credentials to verifying that their caller did indeed go through your identity provider of choice and successfully authenticated. The identity provider represents successful authentication operations by issuing a token, hence the job now becomes to validate that token.

What to validate?

While you should always validate tokens issued to the resources (audience) that you are developing, your application will also obtain access tokens for other resources from AAD. AAD will provide an access token in whatever token format that is appropriate to that resource. This access token itself should be treated like an opaque blob by your application, as your app isn’t the access token’s intended audience and thus your app should not bother itself with looking into the contents of this access token. Your app should just pass it in the call to the resource. It's the called resource's responsibility to validate this access token.

Validating the claims

When an application receives an access token upon user sign-in, it should also perform a few checks against the claims in the access token. These verifications include but are not limited to:

• audience claim, to verify that the ID token was intended to be given to your application
• not before and "expiration time" claims, to verify that the ID token has not expired
• issuer claim, to verify that the token was issued to your app by the v2.0 endpoint
• nonce, as a token replay attack mitigation

You are advised to use standard library methods like JwtSecurityTokenHandler.ValidateToken Method (JwtSecurityToken) to do most of the aforementioned heavy lifting. You can further extend the validation process by making decisions based on claims received in the token. For example, multi-tenant applications can extend the standard validation by inspecting the value of the tid claim (Tenant ID) against a set of pre-selected tenants to ensure they only honor tokens from tenants of their choice. Details on the claims provided in JWT tokens are listed in the Azure AD token reference. When you debug your application and want to understand the claims held by the token, you might find it useful to use the JWT token inspector tool.

Looking for previous versions of this code sample? Check out the tags on the releases GitHub page.

How To Run This Sample

[!Note] If you want to run this sample on Azure Government, navigate to the "Azure Government Deviations" section at the bottom of this page.

To run this sample, you'll need:

• Visual Studio 2017
• An Internet connection
• An Azure Active Directory (Azure AD) tenant. For more information on how to get an Azure AD tenant, see How to get an Azure AD tenant
• A user account in your Azure AD tenant. This sample will not work with a Microsoft account (formerly Windows Live account). Therefore, if you signed in to the Azure portal with a Microsoft account and have never created a user account in your directory before, you need to do that now.

Step 1: Clone or download this repository

From your shell or command line:

git clone https://github.com/Azure-Samples/active-directory-dotnet-webapi-manual-jwt-validation.git

or download and extract the repository .zip file.

Given that the name of the sample is quiet long, and so are the names of the referenced NuGet packages, you might want to clone it in a folder close to the root of your hard drive, to avoid file size limitations on Windows.

Step 2: Register the sample application with your Azure Active Directory tenant

There are two projects in this sample. Each needs to be separately registered in your Azure AD tenant. To register these projects, you can:

• either follow the steps Step 2: Register the sample with your Azure Active Directory tenant and Step 3: Configure the sample to use your Azure AD tenant
• or use PowerShell scripts that:
  • automatically creates the Azure AD applications and related objects (passwords, permissions, dependencies) for you
  • modify the Visual Studio projects' configuration files.

Follow the steps below to manually walk through the steps to register and configure the applications.

Choose the Azure AD tenant where you want to create your applications

As a first step you'll need to:

1. Sign in to the Azure portal using either a work or school account or a personal Microsoft account.
2. If your account is present in more than one Azure AD tenant, select your profile at the top right corner in the menu on top of the page, and then switch directory. Change your portal session to the desired Azure AD tenant.

Register the service app (TodoListService-ManualJwt)

1. Navigate to the Microsoft identity platform for developers App registrations page.
2. Click New registration on top.
3. In the Register an application page that appears, enter your application's registration information:
   • In the Name section, enter a meaningful application name that will be displayed to users of the app, for example TodoListService-ManualJwt.
   • Leave Supported account types on the default setting of Accounts in this organizational directory only.
4. Click on the Register button in bottom to create the application.
5. In the app's registration screen, find the Application (client) ID value and record it for use later. You'll need it to configure the configuration file(s) later in your code.
6. Click the Save button on top to save the changes.
7. In the app's registration screen, click on the Expose an API blade to the left to open the page where you can declare the parameters to expose this app as an Api for which client applications can obtain access tokens for. The first thing that we need to do is to declare the unique resource URI that the clients will be using to obtain access tokens for this Api. To declare an resource URI, follow the following steps:
   • Click Set next to the Application ID URI to generate a URI that is unique for this app.
   • For this sample, accept the proposed Application ID URI (api://{clientId}) by selecting Save.
8. All Apis have to publish a minimum of one scope for the client's to obtain an access token successfully. To publish a scope, follow the following steps:
   • Select Add a scope button open the Add a scope screen and Enter the values as indicated below:
     • For Scope name, use access_as_user.
     • Select Admins and users options for Who can consent?
     • For Admin consent display name type Access TodoListService-ManualJwt
     • For Admin consent description type Allows the app to access TodoListService-ManualJwt as the signed-in user.
     • For User consent display name type Access TodoListService-ManualJwt
     • For User consent description type Allow the application to access TodoListService-ManualJwt on your behalf.
     • Keep State as Enabled
     • Click on the Add scope button on the bottom to save this scope.

Register the client app (TodoListClient-ManualJwt)

1. Navigate to the Microsoft identity platform for developers App registrations page.

2. Click New registration on top.

3. In the Register an application page that appears, enter your application's registration information:

   • In the Name section, enter a meaningful application name that will be displayed to users of the app, for example TodoListClient-ManualJwt.
   • Leave Supported account types on the default setting of Accounts in this organizational directory only.

4. Click on the Register button in bottom to create the application.

5. In the app's registration screen, find the Application (client) ID value and record it for use later. You'll need it to configure the configuration file(s) later in your code.

6. In the app's registration screen, click on the Authentication blade in the left.

   • In the Redirect URIs | Suggested Redirect URIs for public clients (mobile, desktop) section, select https://login.microsoftonline.com/common/oauth2/nativeclient

7. Click the Save button on top to save the changes.

8. In the app's registration screen, click on the API permissions blade in the left to open the page where we add access to the Apis that your application needs.

   • Click the Add a permission button and then,
   • Ensure that the My APIs tab is selected.
   • In the list of APIs, select the API TodoListService-ManualJwt.
   • In the Delegated permissions section, select the Access 'TodoListService-ManualJwt' in the list. Use the search box if necessary.
   • Click on the Add permissions button at the bottom.

Step 3: Configure the sample to use your Azure AD tenant

In the steps below, "ClientID" is the same as "Application ID" or "AppId".

Open the solution in Visual Studio to configure the projects

Configure the service project

Note: if you used the setup scripts, the changes below will have been applied for you

1. Open the TodoListService-ManualJwt\Web.Config file
2. Find the app key ida:TenantId and replace the existing value with your Azure AD tenant ID.
3. Find the app key ida:Audience and replace the existing value with the AppID URI of the service, like api://{clientId}, for example api://821f07ea-31b2-4a15-a154-847edf508749.
4. Find the app key ida:ClientId and replace the existing value with the application ID (clientId) of the TodoListService-ManualJwt application copied from the Azure portal.

Configure the client project

Note: if you used the setup scripts, the changes below will have been applied for you

1. Open the TodoListClient\App.Config file
2. Find the app key ida:Tenant and replace the existing value with your Azure AD tenant name.
3. Find the app key ida:ClientId and replace the existing value with the application ID (clientId) of the TodoListClient-ManualJwt application copied from the Azure portal.
4. Find the app key todo:TodoListResourceId and replace the existing value with the AppID URI of the service, like api://{clientId}, for example api://821f07ea-31b2-4a15-a154-847edf508749.
5. Find the app key todo:TodoListBaseAddress and replace the existing value with the base address of the TodoListService-ManualJwt project (by default https://localhost:44324).

Step 4: Run the sample

Clean the solution, rebuild the solution, and run it. You will need go into the solution properties and set both projects as startup projects, with the service project starting first.

Explore the sample by signing in, adding items to the To Do list, removing the user account, and starting again. Notice that if you stop the application without removing the user account, the next time you run the application you won't be prompted to sign in again - that is the sample implements a persistent cache for MSAL, and remembers the tokens from the previous run.

Did the sample not work for you as expected? Did you encounter issues trying this sample? Then please reach out to us using the GitHub Issues page.

Consider taking a moment to share your experience with us.

About The Code

The manual JWT validation occurs in the TokenValidationHandler implementation in the Global.aspx.cs file in the TodoListService-ManualJwt project. Each time a call is made to the web API, the TokenValidationHandler.SendAsync() handler is executed:

This method:

1. gets the token from the Authorization headers

2. gets the open ID configuration from the Azure AD discovery endpoint

3. ensures that the web API is consented to and provisioned in the Azure AD tenant from where the access token originated

4. verifies that the token has not expired

5. sets the parameters to validate:

   • the audience - the application accepts both its App ID URI and its AppID/clientID
   • the valid issuers - the application accepts both Azure AD V1 and Azure AD V2

6. then it delegates to the JwtSecurityTokenHandler class (provided by the Microsoft.IdentityModel.Tokens library)

The TokenValidationHandler class is registered with ASP.NET in the TodoListService-ManualJwt/Global.asx.cs file, in the Application_Start() method.

For more validation options, please refer to TokenValidationParameters.cs

How To Recreate This Sample

First, in Visual Studio 2017 create an empty solution to host the projects. Then, follow these steps to create each project.

Creating the TodoListService-ManualJwt Project

1. In Visual Studio, create a new Visual C# ASP.NET Web Application (.NET Framework). Choose Web Api in the next screen. Leave the project's chosen authentication mode as the default, that is, No Authentication".

2. Set SSL Enabled to be True. Note the SSL URL.

3. In the project properties, Web properties, set the Project Url to be the SSL URL.

4. Add the latest stable JSON Web Token Handler For the Microsoft .Net Framework NuGet, System.IdentityModel.Tokens.Jwt, to the project.

5. Add an assembly reference to System.IdentityModel.

6. In the Models folder, add a new class named TodoItem.cs. Copy the implementation of TodoItem from this sample into the class.

7. Create a folder named Utils , add a new class named ClaimConstants.cs. Copy the implementation of ClaimConstants.cs from this sample into the class.

8. Add a new, empty, Web API 2 controller named TodoListController.

9. Copy the implementation of the TodoListController from this sample into the controller.

10. Open Global.asax, and copy the implementation from this sample into the controller. Note that a single line is added at the end of Application_Start(),

    GlobalConfiguration.Configuration.MessageHandlers.Add(new TokenValidationHandler());
    

11. In web.config create keys for ida:AADInstance, ida:Tenant, and ida:Audience and set them accordingly. For the global Azure cloud, the value of ida:AADInstance is https://login.microsoftonline.com/{0}.

Creating the TodoListClient Project

1. In the solution, create a new Windows --> Windows Classic Desktop -> WPF App(.NET Framework) called TodoListClient.
2. Add the Microsoft Authentication Library (MSAL) NuGet, Microsoft.Identity.Client to the project.
3. Add assembly references to System.Net.Http, System.Web.Extensions, and System.Configuration.
4. Add a new class to the project named TodoItem.cs. Copy the code from the sample project file of the same name into this class, completely replacing the code in the file in the new project.
5. Add a new class to the project named FileCache.cs. Copy the code from the sample project file of the same name into this class, completely replacing the code in the file in the new project.
6. Copy the markup from MainWindow.xaml in the sample project into the file of the same name in the new project, completely replacing the markup in the file in the new project.
7. Copy the code from MainWindow.xaml.cs in the sample project into the file of the same name in the new project, completely replacing the code in the file in the new project.
8. In app.config create keys for ida:AADInstance, ida:Tenant, ida:ClientId, todo:TodoListResourceId, and todo:TodoListBaseAddress and set them accordingly. For the global Azure cloud, the value of ida:AADInstance is https://login.microsoftonline.com/{0}.

Finally, in the properties of the solution itself, set both projects as startup projects.

How to deploy this sample to Azure

This project has one WebApp / Web API projects. To deploy them to Azure Web Sites, you'll need, for each one, to:

• create an Azure Web Site
• publish the Web App / Web APIs to the web site, and
• update its client(s) to call the web site instead of IIS Express.

Create and publish the TodoListService-ManualJwt to an Azure Web Site

1. Sign in to the Azure portal.

2. Click Create a resource in the top left-hand corner, select Web --> Web App, and give your web site a name, for example, TodoListService-ManualJwt-contoso.azurewebsites.net.

3. Thereafter select the Subscription, Resource Group, App service plan and Location. OS will be Windows and Publish will be Code.

4. Click Create and wait for the App Service to be created.

5. Once you get the Deployment succeeded notification, then click on Go to resource to navigate to the newly created App service.

6. From the Overview tab of the App Service, download the publish profile by clicking the Get publish profile link and save it. Other deployment mechanisms, such as from source control, can also be used.

7. Switch to Visual Studio and go to the TodoListService-ManualJwt project. Right click on the project in the Solution Explorer and select Publish. Click Import Profile on the bottom bar, and import the publish profile that you downloaded earlier.

8. Click on Configure and in the Connection tab, update the Destination URL so that it is a https in the home page url, for example https://TodoListService-ManualJwt-contoso.azurewebsites.net. Click Next.

9. On the Settings tab, make sure Enable Organizational Authentication is NOT selected. Click Save. Click on Publish on the main screen.

10. Visual Studio will publish the project and automatically open a browser to the URL of the project. If you see the default web page of the project, the publication was successful.

Update the Active Directory tenant application registration for TodoListService-ManualJwt

1. Navigate back to to the Azure portal. In the left-hand navigation pane, select the Azure Active Directory service, and then select App registrations (Preview).
2. In the resultant screen, select the TodoListService-ManualJwt application.
3. From the Branding menu, update the Home page URL, to the address of your service, for example https://TodoListService-ManualJwt-contoso.azurewebsites.net. Save the configuration.
4. Add the same URL in the list of values of the Authentication -> Redirect URIs menu. If you have multiple redirect urls, make sure that there a new entry using the App service's Uri for each redirect url.

Update the TodoListClient-ManualJwt to call the TodoListService-ManualJwt Running in Azure Web Sites

1. In Visual Studio, go to the TodoListClient-ManualJwt project.
2. Open TodoListClient\App.Config. Only one change is needed - update the todo:TodoListBaseAddress key value to be the address of the website you published, for example, https://TodoListService-ManualJwt-contoso.azurewebsites.net.
3. Run the client! If you are trying multiple different client types (for example, .Net, Windows Store, Android, iOS) you can have them all call this one published web API.

NOTE: Remember, the To Do list is stored in memory in this TodoListService sample. Azure Web Sites will spin down your web site if it is inactive, and your To Do list will get emptied. Also, if you increase the instance count of the web site, requests will be distributed among the instances. To Do will, therefore, not be the same on each instance.

Azure Government Deviations

In order to run this sample on Azure Government, you can follow through the steps above with a few variations:

• Step 2:

  • You must register this sample for your AAD Tenant in Azure Government by following Step 2 above in the Azure Government portal.

• Step 3:

  • Before configuring the sample, you must make sure your Visual Studio is connected to Azure Government.
  • Navigate to the Web.config file. Replace the ida:AADInstance property in the Azure AD section with https://login.microsoftonline.us/.

Once those changes have been accounted for, you should be able to run this sample on Azure Government.

Troubleshooting

If you are using this sample with an Azure AD B2C custom policy, you might want to read #22, and change step 3. in the About The Code paragraph.

Community Help and Support

Use Stack Overflow to get support from the community. Ask your questions on Stack Overflow first and browse existing issues to see if someone has asked your question before. Make sure that your questions or comments are tagged with [msal dotnet azure-active-directory].

If you find a bug in the sample, please raise the issue on GitHub Issues.

To provide a recommendation, visit the following User Voice page.

Contributing

If you'd like to contribute to this sample, see CONTRIBUTING.MD.

This project has adopted the Microsoft Open Source Code of Conduct. For more information, see the Code of Conduct FAQ or contact [email protected] with any additional questions or comments.

More information

• Microsoft identity platform (Azure Active Directory for developers)
• MSAL.NET's conceptual documentation
• Quickstart: Register an application with the Microsoft identity platform
• Quickstart: Configure a client application to access web APIs
• Recommended pattern to acquire a token
• Token Cache serialization

For more information about token validation, see:

• Principles of Token validation
• Microsoft Identity Model Extension for .NET
• Protect a web API
• Verify scopes and roles in Web API
• TokenValidationParameters.cs

For more information about how the protocols work in this scenario and other scenarios, see Authentication Scenarios for Azure AD.