Metadata resiliency updates and minor edits

Author: Kalyan Krishna

README.md

@@ -1,17 +1,50 @@
 ---
+page_type: sample
+languages:
+  - csharp
+products:
+  - aspnet-core
+  - microsoft-identity-web
+  - azure-active-directory  
+name: How to manually validate a JWT access token using the Microsoft identity platform 
+urlFragment: active-directory-dotnet-webapi-manual-jwt-validation
 services: active-directory
-platforms: dotnet
+platforms: dotnetcore
 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 the Microsoft identity platform (formerly Azure Active Directory for developers)
+# How to manually validate a JWT access token using the Microsoft identity platform
+
+- [Overview](#overview)
+- [About this sample](#about-this-sample)
+- [Scenario: protecting a Web API - acquiring a token for the protected Web API](#scenario-protecting-a-web-api---acquiring-a-token-for-the-protected-web-api)
+  - [Token Validation](#token-validation)
+  - [What to validate?](#what-to-validate)
+  - [Validating the claims](#validating-the-claims)
+- [Prerequisites](#prerequisites)
+- [Setup](#setup)
+- [Explore the sample](#explore-the-sample)
+- [About The Code](#about-the-code)
+- [How To Recreate This Sample](#how-to-recreate-this-sample)
+  - [Creating the TodoListService-ManualJwt Project](#creating-the-todolistservice-manualjwt-project)
+  - [Creating the TodoListClient Project](#creating-the-todolistclient-project)
+- [How to deploy this sample to Azure](#how-to-deploy-this-sample-to-azure)
+- [Azure Government Deviations](#azure-government-deviations)
+- [Troubleshooting](#troubleshooting)
+- [Community Help and Support](#community-help-and-support)
+- [Contributing](#contributing)
+- [More information](#more-information)
 
 ![Build badge](https://identitydivision.visualstudio.com/_apis/public/build/definitions/a7934fdd-dcde-4492-a406-7fad6ac00e17/18/badge)
 
+## Overview
+
+This sample demonstrates how to manually validate an access token issued to a web API protected by the Microsoft Identity Platform. Here a .NET Desktop App (WPF) calls a protected ASP.NET Web API that is secured using Azure AD.
+
 ## About this sample
 
 A Web API that accepts bearer token as a proof of authentication is secured by [validating the token](https://docs.microsoft.com/en-us/azure/active-directory/develop/access-tokens#validating-tokens) they receive from the callers. When a developer generates a skeleton Web API code using [Visual Studio](https://aka.ms/vsdownload), 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](https://github.com/aspnet/Security) and [Microsoft Identity Model Extension for .NET](https://github.com/AzureAD/azure-activedirectory-identitymodel-extensions-for-dotnet) to validate tokens is provided below.
@@ -205,7 +238,7 @@ Open the project in your IDE (like Visual Studio or Visual Studio Code) to confi
 1. Open the `TodoListClient\App.Config` file.
 1. Find the key `ida:Tenant` and replace the existing value with your Azure AD tenant name.
 1. Find the key `ida:ClientId` and replace the existing value with the application ID (clientId) of `TodoListClient-ManualJwt` app copied from the Azure portal.
-1. Find the key `todo:TodoListResourceId` and replace the value with the App ID URI you registered earlier, when exposing an API. For instance use `api://<application_id>`.
+1. Find the key `todo:TodoListResourceId` and replace the existing value with the App ID URI you registered earlier, when exposing an API. For instance use `api://<application_id>`.
 1. Find the key `todo:TodoListBaseAddress` and replace the existing value with the base address of `TodoListService-ManualJwt` (by default `https://localhost:44324`).
 
 ## Running the sample
@@ -214,9 +247,11 @@ Open the project in your IDE (like Visual Studio or Visual Studio Code) to confi
 >
 > Clean the solution, rebuild the solution, and run it.  You might want to go into the solution properties and set both projects as startup projects, with the service project starting first.
 
+## Explore the sample
+
 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](https://github.com/AzureAD/microsoft-authentication-library-for-dotnet/wiki/token-cache-serialization), 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](../../issues) page.
+> :information_source:  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](../../issues) page.
 
 > [Consider taking a moment to share your experience with us.](https://forms.office.com/Pages/ResponsePage.aspx?id=v4j5cvGGr0GRqy180BHbR73pcsbpbxNJuZCMKN0lURpUMjFRQjA0RElFUFNPV0dCUVBGQzk0QkhKTiQlQCN0PWcu)
 

TodoListService-ManualJwt/Controllers/TodoListController.cs

@@ -45,7 +45,7 @@ public IEnumerable<TodoItem> Get()
             CheckExpectedClaim();
 
             // A user's To Do list is keyed off of the NameIdentifier claim, which contains an immutable, unique identifier for the user.
-            Claim subject = ClaimsPrincipal.Current.FindFirst(ClaimTypes.NameIdentifier);
+            Claim subject = ClaimsPrincipal.Current.FindFirst(ClaimConstants.Name);
 
             return from todo in todoBag
                    where todo.Owner == subject.Value
@@ -59,7 +59,7 @@ public void Post(TodoItem todo)
 
             if (null != todo && !string.IsNullOrWhiteSpace(todo.Title))
             {
-                todoBag.Add(new TodoItem { Title = todo.Title, Owner = ClaimsPrincipal.Current.FindFirst(ClaimTypes.NameIdentifier).Value });
+                todoBag.Add(new TodoItem { Title = todo.Title, Owner = ClaimsPrincipal.Current.FindFirst(ClaimConstants.Name).Value });
             }
         }
 
@@ -74,7 +74,7 @@ private void CheckExpectedClaim()
             // The Scope claim tells you what permissions the client application has in the service.
             // In this case we look for a scope value of access_as_user, or full access to the service as the user.
 
-            if (!ClaimsPrincipal.Current.HasClaim(ClaimConstants.ScopeClaimType, ClaimConstants.ScopeClaimValue))
+            if (!ClaimsPrincipal.Current.HasClaim(ClaimConstants.ScpClaimType, ClaimConstants.ScopeClaimValue))
             {
                 throw new HttpResponseException(
                     new HttpResponseMessage { 

TodoListService-ManualJwt/Global.asax.cs

@@ -22,6 +22,7 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
  */
 
+using Microsoft.IdentityModel.JsonWebTokens;
 using Microsoft.IdentityModel.Protocols;
 using Microsoft.IdentityModel.Protocols.OpenIdConnect;
 using Microsoft.IdentityModel.Tokens;
@@ -68,15 +69,19 @@ internal class TokenValidationHandler : DelegatingHandler
         // The Authority is the sign-in URL of the tenant.
         // The Audience is the value of one of the 'aud' claims the service expects to find in token to assure the token is addressed to it.
 
-        private string _audience = ConfigurationManager.AppSettings["ida:Audience"];        
+        private string _audience = ConfigurationManager.AppSettings["ida:Audience"];
         private string _clientId = ConfigurationManager.AppSettings["ida:ClientId"];
         private string _tenant = ConfigurationManager.AppSettings["ida:TenantId"];
         private ISecurityTokenValidator _tokenValidator;
         private string _authority;
+        private ConfigurationManager<OpenIdConnectConfiguration> _configManager;
 
         public TokenValidationHandler()
         {
             _authority = string.Format(CultureInfo.InvariantCulture, ConfigurationManager.AppSettings["ida:AADInstance"], _tenant);
+            // The ConfigurationManager class holds properties to control the metadata refresh interval. For more details, https://docs.microsoft.com/en-us/dotnet/api/microsoft.identitymodel.protocols.configurationmanager-1?view=azure-dotnet
+            _configManager = new ConfigurationManager<OpenIdConnectConfiguration>($"{_authority}/.well-known/openid-configuration", new OpenIdConnectConfigurationRetriever());
+
             _tokenValidator = new JwtSecurityTokenHandler();
         }
 
@@ -100,7 +105,7 @@ protected async override Task<HttpResponseMessage> SendAsync(HttpRequestMessage
             OpenIdConnectConfiguration config = null;
             try
             {
-                config = await GetConfigurationManager().GetConfigurationAsync(cancellationToken).ConfigureAwait(false);
+                config = await _configManager.GetConfigurationAsync(cancellationToken).ConfigureAwait(false);
             }
             catch (Exception ex)
             {
@@ -124,23 +129,37 @@ protected async override Task<HttpResponseMessage> SendAsync(HttpRequestMessage
             };
 
             // Initialize the token validation parameters
-            TokenValidationParameters validationParameters = new TokenValidationParameters
+            TokenValidationParameters validationParameters = GetTokenValidationParameters(config, validissuers);
+
+            try
             {
-                // App Id URI and AppId of this service application are both valid audiences.
-                ValidAudiences = new[] { _audience, _clientId },
+                if (string.IsNullOrWhiteSpace(request.Headers.Authorization.Parameter))
+                {
+#if DEBUG
+                    return BuildResponseErrorMessage(HttpStatusCode.Unauthorized, "No token provided in the 'Authorization' header");
+#else
+                return new HttpResponseMessage(HttpStatusCode.Unauthorized);
+#endif
+                }
 
-                // Support Azure AD V1 and V2 endpoints.
-                ValidIssuers = validissuers,
-                IssuerSigningKeys = config.SigningKeys
+                string jwtToken = request.Headers.Authorization.Parameter;
+                JsonWebTokenHandler tokenHandler = new JsonWebTokenHandler();
+                TokenValidationResult result = tokenHandler.ValidateToken(jwtToken, validationParameters);
 
-                // Please inspect TokenValidationParameters class for a lot more validation parameters.
-            };
+                // Refresh the metadata (cached keys) if the metadata refresh has invalidated the cache (https://github.com/AzureAD/azure-activedirectory-identitymodel-extensions-for-dotnet/wiki/Resilience-on-metadata-refresh)
+                if (result.Exception != null && result.Exception is SecurityTokenSignatureKeyNotFoundException)
+                {
+                    _configManager.RequestRefresh();
+                    config = await _configManager.GetConfigurationAsync().ConfigureAwait(false);
+                    validationParameters = GetTokenValidationParameters(config, validissuers);
 
-            try
-            {
-                // Validate token.
-                SecurityToken securityToken;
-                var claimsPrincipal = _tokenValidator.ValidateToken(request.Headers.Authorization.Parameter, validationParameters, out securityToken);
+                    // attempt to validate token again after refresh
+                    result = tokenHandler.ValidateToken(jwtToken, validationParameters);
+                }
+
+
+                // Create a claims principal
+                ClaimsPrincipal claimsPrincipal = new ClaimsPrincipal(result.ClaimsIdentity);
 
 #pragma warning disable 1998
                 // This check is required to ensure that the Web API only accepts tokens from tenants where it has been consented to and provisioned.
@@ -165,7 +184,7 @@ protected async override Task<HttpResponseMessage> SendAsync(HttpRequestMessage
 
                 // If the token is scoped, verify that required permission is set in the scope claim.
                 // This could be done later at the controller level as well
-                return ClaimsPrincipal.Current.FindFirst(ClaimConstants.ScopeClaimType).Value != ClaimConstants.ScopeClaimValue
+                return ClaimsPrincipal.Current.FindFirst(ClaimConstants.ScpClaimType).Value != ClaimConstants.ScopeClaimValue
                     ? BuildResponseErrorMessage(HttpStatusCode.Forbidden)
                     : await base.SendAsync(request, cancellationToken);
             }
@@ -187,6 +206,22 @@ protected async override Task<HttpResponseMessage> SendAsync(HttpRequestMessage
             }
         }
 
+        private TokenValidationParameters GetTokenValidationParameters(OpenIdConnectConfiguration config, IList<string> validissuers)
+        {
+            TokenValidationParameters validationParameters = new TokenValidationParameters
+            {
+                // App Id URI and AppId of this service application are both valid audiences.
+                ValidAudiences = new[] { _audience, _clientId },
+
+                // Support Azure AD V1 and V2 endpoints.
+                ValidIssuers = validissuers,
+                IssuerSigningKeys = config.SigningKeys
+
+                // Please inspect TokenValidationParameters class for a lot more validation parameters.
+            };
+            return validationParameters;
+        }
+
         private HttpResponseMessage BuildResponseErrorMessage(HttpStatusCode statusCode, string error_description = "")
         {
             var response = new HttpResponseMessage(statusCode);
@@ -196,13 +231,5 @@ private HttpResponseMessage BuildResponseErrorMessage(HttpStatusCode statusCode,
                 new AuthenticationHeaderValue("Bearer", "authorization_uri=\"" + _authority + "\"" + "," + "resource_id=" + _audience + $",error_description={error_description}"));
             return response;
         }
-
-        /// <summary>
-        /// The ConfigurationManager class holds properties to control the metadata refresh interval. 
-        /// For more details, https://docs.microsoft.com/en-us/dotnet/api/microsoft.identitymodel.protocols.configurationmanager-1?view=azure-dotnet
-        /// </summary>
-        /// <returns></returns>
-        private ConfigurationManager<OpenIdConnectConfiguration> GetConfigurationManager() =>
-            new ConfigurationManager<OpenIdConnectConfiguration>($"{_authority}/.well-known/openid-configuration", new OpenIdConnectConfigurationRetriever());
     }
 }