Introduce complete challenge support and add a new event to control how the challenge is returned to the caller

Author: kevinchalet

src/AspNet.Security.OAuth.Introspection/Events/ApplyChallengeContext.cs

@@ -0,0 +1,71 @@
+/*
+ * Licensed under the Apache License, Version 2.0 (http://www.apache.org/licenses/LICENSE-2.0)
+ * See https://github.com/aspnet-contrib/AspNet.Security.OAuth.Extensions for more information
+ * concerning the license and the contributors participating to this project.
+ */
+
+using JetBrains.Annotations;
+using Microsoft.AspNetCore.Authentication;
+using Microsoft.AspNetCore.Http;
+using Microsoft.AspNetCore.Http.Authentication;
+
+namespace AspNet.Security.OAuth.Introspection
+{
+    /// <summary>
+    /// Allows customization of the challenge process.
+    /// </summary>
+    public class ApplyChallengeContext : BaseControlContext
+    {
+        public ApplyChallengeContext(
+            [NotNull] HttpContext context,
+            [NotNull] OAuthIntrospectionOptions options,
+            [NotNull] AuthenticationProperties properties)
+            : base(context)
+        {
+            Options = options;
+            Properties = properties;
+        }
+
+        /// <summary>
+        /// Gets the options used by the introspection middleware.
+        /// </summary>
+        public OAuthIntrospectionOptions Options { get; }
+
+        /// <summary>
+        /// Gets the authentication properties associated with the challenge.
+        /// </summary>
+        public AuthenticationProperties Properties { get; }
+
+        /// <summary>
+        /// Gets or sets the "error" value returned to the caller as part
+        /// of the WWW-Authenticate header. This property may be null when
+        /// <see cref="OAuthIntrospectionOptions.IncludeErrorDetails"/> is set to <c>false</c>.
+        /// </summary>
+        public string Error { get; set; }
+
+        /// <summary>
+        /// Gets or sets the "error_description" value returned to the caller as part
+        /// of the WWW-Authenticate header. This property may be null when
+        /// <see cref="OAuthIntrospectionOptions.IncludeErrorDetails"/> is set to <c>false</c>.
+        /// </summary>
+        public string ErrorDescription { get; set; }
+
+        /// <summary>
+        /// Gets or sets the "error_uri" value returned to the caller as part of the
+        /// WWW-Authenticate header. This property is always null unless explicitly set.
+        /// </summary>
+        public string ErrorUri { get; set; }
+
+        /// <summary>
+        /// Gets or sets the "realm" value returned to
+        /// the caller as part of the WWW-Authenticate header.
+        /// </summary>
+        public string Realm { get; set; }
+
+        /// <summary>
+        /// Gets or sets the "scope" value returned to
+        /// the caller as part of the WWW-Authenticate header.
+        /// </summary>
+        public string Scope { get; set; }
+    }
+}

src/AspNet.Security.OAuth.Introspection/OAuthIntrospectionConstants.cs

@@ -22,25 +22,47 @@ public static class Claims
             public const string Username = "username";
         }
 
+        public static class Errors
+        {
+            public const string InsufficientScope = "insufficient_scope";
+            public const string InvalidRequest = "invalid_request";
+            public const string InvalidToken = "invalid_token";
+        }
+
         public static class Metadata
         {
             public const string IntrospectionEndpoint = "introspection_endpoint";
         }
 
         public static class Parameters
         {
+            public const string Error = "error";
+            public const string ErrorDescription = "error_description";
+            public const string ErrorUri = "error_uri";
+            public const string Realm = "realm";
+            public const string Scope = "scope";
             public const string Token = "token";
             public const string TokenTypeHint = "token_type_hint";
         }
 
         public static class Properties
         {
             public const string Audiences = ".audiences";
+            public const string Error = ".error";
+            public const string ErrorDescription = ".error_description";
+            public const string ErrorUri = ".error_uri";
+            public const string Realm = ".realm";
+            public const string Scope = ".scope";
             public const string Scopes = ".scopes";
             public const string TicketId = ".ticket_id";
             public const string Token = "access_token";
         }
 
+        public static class Schemes
+        {
+            public const string Bearer = "Bearer";
+        }
+
         public static class TokenTypes
         {
             public const string AccessToken = "access_token";

src/AspNet.Security.OAuth.Introspection/OAuthIntrospectionError.cs

@@ -0,0 +1,33 @@
+namespace AspNet.Security.OAuth.Introspection
+{
+    /// <summary>
+    /// Represents an OAuth2 introspection error.
+    /// </summary>
+    public class OAuthIntrospectionError
+    {
+        /// <summary>
+        /// Gets or sets the error code.
+        /// </summary>
+        public string Error { get; set; }
+
+        /// <summary>
+        /// Gets or sets the error_description.
+        /// </summary>
+        public string ErrorDescription { get; set; }
+
+        /// <summary>
+        /// Gets or sets the error_uri.
+        /// </summary>
+        public string ErrorUri { get; set; }
+
+        /// <summary>
+        /// Gets or sets the realm.
+        /// </summary>
+        public string Realm { get; set; }
+
+        /// <summary>
+        /// Gets or sets the scope.
+        /// </summary>
+        public string Scope { get; set; }
+    }
+}

src/AspNet.Security.OAuth.Introspection/OAuthIntrospectionEvents.cs

@@ -15,40 +15,50 @@ namespace AspNet.Security.OAuth.Introspection
     public class OAuthIntrospectionEvents
     {
         /// <summary>
-        /// Invoked when a ticket is to be created from an introspection response.
+        /// Invoked when a challenge response is returned to the caller.
         /// </summary>
-        public Func<CreateTicketContext, Task> OnCreateTicket { get; set; } = context => Task.FromResult(0);
+        public Func<ApplyChallengeContext, Task> OnApplyChallenge { get; set; } = context => Task.FromResult(0);
 
         /// <summary>
-        /// Invoked when a token is to be parsed from a newly-received request.
+        /// Invoked when a ticket is to be created from an introspection response.
         /// </summary>
-        public Func<RetrieveTokenContext, Task> OnRetrieveToken { get; set; } = context => Task.FromResult(0);
+        public Func<CreateTicketContext, Task> OnCreateTicket { get; set; } = context => Task.FromResult(0);
 
         /// <summary>
         /// Invoked when a token is to be sent to the authorization server for introspection.
         /// </summary>
         public Func<RequestTokenIntrospectionContext, Task> OnRequestTokenIntrospection { get; set; } = context => Task.FromResult(0);
 
+        /// <summary>
+        /// Invoked when a token is to be parsed from a newly-received request.
+        /// </summary>
+        public Func<RetrieveTokenContext, Task> OnRetrieveToken { get; set; } = context => Task.FromResult(0);
+
         /// <summary>
         /// Invoked when a token is to be validated, before final processing.
         /// </summary>
         public Func<ValidateTokenContext, Task> OnValidateToken { get; set; } = context => Task.FromResult(0);
 
         /// <summary>
-        /// Invoked when a ticket is to be created from an introspection response.
+        /// Invoked when a challenge response is returned to the caller.
         /// </summary>
-        public virtual Task CreateTicket(CreateTicketContext context) => OnCreateTicket(context);
+        public virtual Task ApplyChallenge(ApplyChallengeContext context) => OnApplyChallenge(context);
 
         /// <summary>
-        /// Invoked when a token is to be parsed from a newly-received request.
+        /// Invoked when a ticket is to be created from an introspection response.
         /// </summary>
-        public virtual Task RetrieveToken(RetrieveTokenContext context) => OnRetrieveToken(context);
+        public virtual Task CreateTicket(CreateTicketContext context) => OnCreateTicket(context);
 
         /// <summary>
         /// Invoked when a token is to be sent to the authorization server for introspection.
         /// </summary>
         public virtual Task RequestTokenIntrospection(RequestTokenIntrospectionContext context) => OnRequestTokenIntrospection(context);
 
+        /// <summary>
+        /// Invoked when a token is to be parsed from a newly-received request.
+        /// </summary>
+        public virtual Task RetrieveToken(RetrieveTokenContext context) => OnRetrieveToken(context);
+
         /// <summary>
         /// Invoked when a token is to be validated, before final processing.
         /// </summary>

src/AspNet.Security.OAuth.Introspection/OAuthIntrospectionExtensions.cs

@@ -18,7 +18,7 @@ namespace Microsoft.AspNetCore.Builder
     public static class OAuthIntrospectionExtensions
     {
         /// <summary>
-        /// Adds a new instance of the OAuth2 introspection middleware in the ASP.NET 5 pipeline.
+        /// Adds a new instance of the OAuth2 introspection middleware in the ASP.NET Core pipeline.
         /// </summary>
         /// <param name="app">The application builder.</param>
         /// <param name="configuration">The delegate used to configure the introspection options.</param>
@@ -44,7 +44,7 @@ public static IApplicationBuilder UseOAuthIntrospection(
         }
 
         /// <summary>
-        /// Adds a new instance of the OAuth2 introspection middleware in the ASP.NET 5 pipeline.
+        /// Adds a new instance of the OAuth2 introspection middleware in the ASP.NET Core pipeline.
         /// </summary>
         /// <param name="app">The application builder.</param>
         /// <param name="options">The options used to configure the introspection middleware.</param>

src/AspNet.Security.OAuth.Introspection/OAuthIntrospectionFeature.cs

@@ -0,0 +1,15 @@
+namespace AspNet.Security.OAuth.Introspection
+{
+    /// <summary>
+    /// Exposes the OAuth2 introspection details
+    /// associated with the current request.
+    /// </summary>
+    public class OAuthIntrospectionFeature
+    {
+        /// <summary>
+        /// Gets or sets the error details returned
+        /// as part of the challenge response.
+        /// </summary>
+        public OAuthIntrospectionError Error { get; set; }
+    }
+}