Added ForceHttpsRedirectUris option applied to the RedirectUri and Po…

…stLogoutRedirectUri. Minor comment fixes. (#202)

.editorconfig

@@ -473,9 +473,6 @@ dotnet_diagnostic.CA1062.severity = none
 # CA1303: Do not pass literals as localized parameters
 dotnet_diagnostic.CA1303.severity = none
 
-# SA1004: Documentation lines should begin with single space
-dotnet_diagnostic.SA1004.severity = none
-
 # SA1118: Parameter should not span multiple lines
 dotnet_diagnostic.SA1118.severity = none
 
@@ -536,9 +533,6 @@ dotnet_diagnostic.SA1616.severity = none
 # SA1623: Property summary documentation should match accessors
 dotnet_diagnostic.SA1623.severity = none
 
-# SA1627: Documentation text should not be empty
-dotnet_diagnostic.SA1627.severity = none
-
 # SA1642: Constructor summary documentation should begin with standard text
 dotnet_diagnostic.SA1642.severity = none
 

src/Microsoft.Identity.Web/CertificateManagement/CertificateDescription.cs

@@ -26,10 +26,10 @@ public static CertificateDescription FromCertificate(X509Certificate2 x509certif
         }
 
         /// <summary>
-        /// Creates a Certificate Description from KeyVault.
+        /// Creates a certificate description from Key Vault.
         /// </summary>
-        /// <param name="keyVaultUrl"></param>
-        /// <param name="keyVaultCertificateName"></param>
+        /// <param name="keyVaultUrl">The Key Vault URL.</param>
+        /// <param name="keyVaultCertificateName">The name of the certificate in Key Vault.</param>
         /// <returns>A certificate description.</returns>
         public static CertificateDescription FromKeyVault(string keyVaultUrl, string keyVaultCertificateName)
         {
@@ -42,9 +42,9 @@ public static CertificateDescription FromKeyVault(string keyVaultUrl, string key
         }
 
         /// <summary>
-        /// Create a certificate description from a base 64 encoded value.
+        /// Create a certificate description from a Base64 encoded value.
         /// </summary>
-        /// <param name="base64EncodedValue">base 64 encoded value.</param>
+        /// <param name="base64EncodedValue">Base64 encoded certificate value.</param>
         /// <returns>A certificate description.</returns>
         public static CertificateDescription FromBase64Encoded(string base64EncodedValue)
         {
@@ -59,7 +59,7 @@ public static CertificateDescription FromBase64Encoded(string base64EncodedValue
         /// Create a certificate description from path on disk.
         /// </summary>
         /// <param name="path">Path were to find the certificate file.</param>
-        /// <param name="password">certificate password.</param>
+        /// <param name="password">Certificate password.</param>
         /// <returns>A certificate description.</returns>
         public static CertificateDescription FromPath(string path, string password = null)
         {
@@ -72,7 +72,7 @@ public static CertificateDescription FromPath(string path, string password = nul
         }
 
         /// <summary>
-        /// Create a certificate description from a thumbprint and store location (certificate manager on Windows for instance).
+        /// Create a certificate description from a thumbprint and store location (Certificate Manager on Windows for instance).
         /// </summary>
         /// <param name="certificateThumbprint">Certificate thumbprint.</param>
         /// <param name="certificateStoreLocation">Store location where to find the certificate.</param>
@@ -93,7 +93,7 @@ public static CertificateDescription FromStoreWithThumprint(
 
         /// <summary>
         /// Create a certificate description from a certificate distinguished name (such as CN=name)
-        /// and store location (certificate manager on Windows for instance).
+        /// and store location (Certificate Manager on Windows for instance).
         /// </summary>
         /// <param name="certificateDistinguishedName">Certificate distinguished named.</param>
         /// <param name="certificateStoreLocation">Store location where to find the certificate.</param>
@@ -121,14 +121,14 @@ public static CertificateDescription FromStoreWithDistinguishedName(
         /// Container in which to find the certificate.
         /// <list type="bullet">
         /// <item>If <see cref="SourceType"/> equals <see cref="CertificateSource.KeyVault"/>, then
-        /// the container is the KeyVault base URL</item>
+        /// the container is the Key Vault base URL.</item>
         /// <item>If <see cref="SourceType"/> equals <see cref="CertificateSource.Base64Encoded"/>, then
-        /// this value is not used</item>
+        /// this value is not used.</item>
         /// <item>If <see cref="SourceType"/> equals <see cref="CertificateSource.Path"/>, then
-        /// this value is the path on disk where to find the certificate</item>
+        /// this value is the path on disk where to find the certificate.</item>
         /// <item>If <see cref="SourceType"/> equals <see cref="CertificateSource.StoreWithDistinguishedName"/>,
         /// or <see cref="CertificateSource.StoreWithThumbprint"/>, then
-        /// this value is the path to the certificate in the cert store, for instance <c>CurrentUser/My</c></item>
+        /// this value is the path to the certificate in the cert store, for instance <c>CurrentUser/My</c>.</item>
         /// </list>
         /// </summary>
         internal string Container
@@ -177,12 +177,12 @@ internal string Container
         }
 
         /// <summary>
-        /// URL of the KeyVault for instance https://msidentitywebsamples.vault.azure.net.
+        /// URL of the Key Vault for instance https://msidentitywebsamples.vault.azure.net.
         /// </summary>
         public string KeyVaultUrl { get; set; }
 
         /// <summary>
-        /// Certiticate store path, for instance "CurrentUser/My".
+        /// Certificate store path, for instance "CurrentUser/My".
         /// </summary>
         /// <remarks>This property should only be used in conjunction with DistinguishName or Thumbprint.</remarks>
         public string CertificateStorePath { get; set; }
@@ -193,7 +193,7 @@ internal string Container
         public string CertificateDistinguishedName { get; set; }
 
         /// <summary>
-        /// Name of the certificate in KeyVault.
+        /// Name of the certificate in Key Vault.
         /// </summary>
         public string KeyVaultCertificateName { get; set; }
 
@@ -213,7 +213,7 @@ internal string Container
         public string CertificatePassword { get; set; }
 
         /// <summary>
-        /// Base 64 encoded value.
+        /// Base64 encoded certificate value.
         /// </summary>
         public string Base64EncodedValue { get; set; }
 
@@ -222,11 +222,11 @@ internal string Container
         /// </summary>
         /// <list type="bullet">
         /// <item>If <see cref="SourceType"/> equals <see cref="CertificateSource.KeyVault"/>, then
-        /// the reference is the name of the certificate in KeyVault (maybe the version?)</item>
+        /// the reference is the name of the certificate in Key Vault (maybe the version?).</item>
         /// <item>If <see cref="SourceType"/> equals <see cref="CertificateSource.Base64Encoded"/>, then
-        /// this value is the base 64 encoded certificate itself</item>
+        /// this value is the base 64 encoded certificate itself.</item>
         /// <item>If <see cref="SourceType"/> equals <see cref="CertificateSource.Path"/>, then
-        /// this value is the password to access the certificate (if needed)</item>
+        /// this value is the password to access the certificate (if needed).</item>
         /// <item>If <see cref="SourceType"/> equals <see cref="CertificateSource.StoreWithDistinguishedName"/>,
         /// this value is the distinguished name.</item>
         /// <item>If <see cref="SourceType"/> equals <see cref="CertificateSource.StoreWithThumbprint"/>,
@@ -281,7 +281,7 @@ internal string ReferenceOrValue
         }
 
         /// <summary>
-        /// The certificate, either provided directly in code by the
+        /// The certificate, either provided directly in code
         /// or loaded from the description.
         /// </summary>
         public X509Certificate2 Certificate { get; internal set; }

src/Microsoft.Identity.Web/CertificateManagement/CertificateSource.cs

@@ -9,22 +9,22 @@ namespace Microsoft.Identity.Web
     public enum CertificateSource
     {
         /// <summary>
-        /// Certificate itself
+        /// Certificate itself.
         /// </summary>
         Certificate = 0,
 
         /// <summary>
-        /// KeyVault
+        /// From an Azure Key Vault.
         /// </summary>
         KeyVault = 1,
 
         /// <summary>
-        /// Base 64 encoded directly in the configuration.
+        /// Base64 encoded string directly from the configuration.
         /// </summary>
         Base64Encoded = 2,
 
         /// <summary>
-        /// Local path on disk
+        /// From local path on disk.
         /// </summary>
         Path = 3,
 
@@ -34,7 +34,7 @@ public enum CertificateSource
         StoreWithThumbprint = 4,
 
         /// <summary>
-        /// From the certificate store, described by its Distinguished name.
+        /// From the certificate store, described by its distinguished name.
         /// </summary>
         StoreWithDistinguishedName = 5,
     }

src/Microsoft.Identity.Web/CertificateManagement/DefaultCertificateLoader.cs

@@ -54,9 +54,9 @@ private static X509Certificate2 LoadFromBase64Encoded(string certificateBase64)
         }
 
         /// <summary>
-        /// Load a certificate from KeyVault, including the private key.
+        /// Load a certificate from Key Vault, including the private key.
         /// </summary>
-        /// <param name="keyVaultUrl">Url of KeyVault.</param>
+        /// <param name="keyVaultUrl">URL of Key Vault.</param>
         /// <param name="certificateName">Name of the certificate.</param>
         /// <returns>An <see cref="X509Certificate2"/> certificate.</returns>
         /// <remarks>This code is inspired by Heath Stewart's code in:

src/Microsoft.Identity.Web/CertificateManagement/ICertificateLoader.cs

@@ -4,7 +4,7 @@
 namespace Microsoft.Identity.Web
 {
     /// <summary>
-    /// Interface to implement load a certificate.
+    /// Interface to implement loading of a certificate.
     /// </summary>
     internal interface ICertificateLoader
     {

src/Microsoft.Identity.Web/ITokenAcquisitionInternal.cs

@@ -46,7 +46,7 @@ internal interface ITokenAcquisitionInternal
         /// Removes the account associated with context.HttpContext.User from the MSAL.NET cache.
         /// </summary>
         /// <param name="context">RedirectContext passed-in to a <see cref="OpenIdConnectEvents.OnRedirectToIdentityProviderForSignOut"/>
-        /// Openidconnect event.</param>
+        /// OpenID Connect event.</param>
         /// <returns></returns>
         Task RemoveAccountAsync(RedirectContext context);
     }

src/Microsoft.Identity.Web/MicrosoftIdentityOptions.cs

@@ -4,6 +4,7 @@
 using System.Collections.Generic;
 using Microsoft.AspNetCore.Authentication;
 using Microsoft.AspNetCore.Authentication.OpenIdConnect;
+using Microsoft.IdentityModel.Protocols.OpenIdConnect;
 
 namespace Microsoft.Identity.Web
 {
@@ -29,28 +30,37 @@ public class MicrosoftIdentityOptions : OpenIdConnectOptions
 
         /// <summary>
         /// In a web app, gets or sets the RedirectUri (URI where the token will be sent back by
-        /// Azure Active Directory or Azure Active Directory B2C)
+        /// Azure Active Directory or Azure Active Directory B2C).
         /// This property is exclusive with <see cref="RemoteAuthenticationOptions.CallbackPath"/> which should be used preferably if you don't want
         /// to have a different deployed configuration from your developer configuration.
         /// There are cases where RedirectUri is needed, for instance when you use a reverse proxy that transforms HTTPS
         /// URLs (external world) to HTTP URLs (inside the protected area). This can also be useful for web apps running
-        /// in containers (for the same reasons)
+        /// in containers (for the same reasons).
         /// If you don't specify the redirect URI, the redirect URI will be computed from the URL on which the app is
         /// deployed and the CallbackPath.
         /// </summary>
         public string RedirectUri { get; set; }
 
         /// <summary>
-        /// In a web app, gets or sets the PostLogoutRedirectUri
+        /// In a web app, gets or sets the PostLogoutRedirectUri.
         /// This property is exclusive with <see cref="OpenIdConnectOptions.SignedOutCallbackPath"/> which should be used preferably if you don't want
         /// to have a different deployed configuration from your developer configuration.
         /// There are cases where PostLogoutRedirectUri is needed, for instance when you use a reverse proxy that transforms HTTPS
         /// URLs (external world) to HTTP URLs (inside the protected area). This can also be useful for web apps running
-        /// in containers (for the same reasons)
+        /// in containers (for the same reasons).
         /// If you don't specify the PostLogoutRedirectUri, it will be computed by ASP.NET Core using the SignedOutCallbackPath.
         /// </summary>
         public string PostLogoutRedirectUri { get; set; }
 
+        /// <summary>
+        /// When set to true, forces the <see cref="OpenIdConnectMessage.RedirectUri"/> and the <see cref="OpenIdConnectMessage.PostLogoutRedirectUri"/> to use the HTTPS scheme.
+        /// This behavior can be desired, for instance, when you use a reverse proxy that transforms HTTPS
+        /// URLs (external world) to HTTP URLs (inside the protected area). This can also be useful for web apps running
+        /// in containers (for the same reasons), for example when deploying your web app to
+        /// Azure App Services in Linux containers.
+        /// </summary>
+        public bool ForceHttpsRedirectUris { get; set; }
+
         /// <summary>
         /// Gets or sets TokenAcquisition as a Singleton. There are scenarios, like using the Graph SDK,
         /// which require TokenAcquisition to be a Singleton.

src/Microsoft.Identity.Web/Resource/ScopesRequiredHttpContextExtensions.cs

@@ -24,8 +24,9 @@ public static class ScopesRequiredHttpContextExtensions
         /// </summary>
         /// <param name="context">HttpContext (from the controller).</param>
         /// <param name="acceptedScopes">Scopes accepted by this web API.</param>
-        /// <exception cref="HttpRequestException"/> with a <see cref="HttpResponse.StatusCode"/> set to
-        /// <see cref="HttpStatusCode.Unauthorized"/>
+        /// <exception cref="HttpRequestException"> with a <see cref="HttpResponse.StatusCode"/> set to
+        /// <see cref="HttpStatusCode.Unauthorized"/>.
+        /// </exception>
         public static void VerifyUserHasAnyAcceptedScope(this HttpContext context, params string[] acceptedScopes)
         {
             if (acceptedScopes == null)

src/Microsoft.Identity.Web/TokenAcquisition.cs

@@ -284,7 +284,7 @@ public async Task<string> GetAccessTokenForAppAsync(IEnumerable<string> scopes)
         /// Removes the account associated with context.HttpContext.User from the MSAL.NET cache.
         /// </summary>
         /// <param name="context">RedirectContext passed-in to a <see cref="OpenIdConnectEvents.OnRedirectToIdentityProviderForSignOut"/>
-        /// Openidconnect event.</param>
+        /// OpenID Connect event.</param>
         /// <returns></returns>
         public async Task RemoveAccountAsync(RedirectContext context)
         {

src/Microsoft.Identity.Web/TokenCacheProviders/Session/MsalSessionTokenCacheProvider.cs

@@ -10,21 +10,24 @@
 namespace Microsoft.Identity.Web.TokenCacheProviders.Session
 {
     /// <summary>
-    /// An implementation of token cache for Confidential clients backed by an HTTP session.
+    /// An implementation of token cache for confidential clients backed by an HTTP session.
     /// </summary>
+    /// <remarks>
     /// For this session cache to work effectively the ASP.NET Core session has to be configured properly.
     /// The latest guidance is provided at https://docs.microsoft.com/aspnet/core/fundamentals/app-state
     ///
-    /// // In the method - public void ConfigureServices(IServiceCollection services) in startup.cs, add the following
+    /// In the method <c>public void ConfigureServices(IServiceCollection services)</c> in Startup.cs, add the following:
+    /// <code>
     /// services.AddSession(option =>
     /// {
     ///     option.Cookie.IsEssential = true;
     /// });
-    ///
-    /// In the method - public void Configure(IApplicationBuilder app, IHostingEnvironment env) in startup.cs, add the following
-    ///
+    /// </code>
+    /// In the method <c>public void Configure(IApplicationBuilder app, IHostingEnvironment env)</c> in Startup.cs, add the following:
+    /// <code>
     /// app.UseSession(); // Before UseMvc()
-    ///
+    /// </code>
+    /// </remarks>
     /// <seealso>https://aka.ms/msal-net-token-cache-serialization</seealso>
     public class MsalSessionTokenCacheProvider : MsalAbstractTokenCacheProvider, IMsalTokenCacheProvider
     {