From 09cd44f4eae4766ce7f83709f13706836a95161b Mon Sep 17 00:00:00 2001
From: Brock Allen <brockallen@gmail.com>
Date: Tue, 26 Sep 2017 17:40:46 -0400
Subject: [PATCH] update docs for 2.0

---
 docs/index.rst                                |   1 +
 docs/reference/client.rst                     |  16 ++-
 docs/reference/options.rst                    |  20 +--
 docs/reference/profileservice.rst             |  50 +++++++
 docs/topics/apis.rst                          | 123 ++++++++++--------
 docs/topics/clients.rst                       |   2 +-
 docs/topics/deployment.rst                    |   3 +-
 docs/topics/logging.rst                       |  47 ++++---
 docs/topics/signin.rst                        |  38 ++++--
 docs/topics/signin_external_providers.rst     |  82 +++++++-----
 docs/topics/signout.rst                       |  27 ++--
 docs/topics/signout_external_providers.rst    |  46 ++++---
 docs/topics/signout_federated.rst             |  43 +-----
 docs/topics/startup.rst                       |  16 ++-
 docs/topics/windows.rst                       |  38 +++---
 .../Quickstart/Account/AccountController.cs   |   1 -
 .../Options/AuthenticationOptions.cs          |   2 +-
 17 files changed, 325 insertions(+), 230 deletions(-)
 create mode 100644 docs/reference/profileservice.rst

diff --git a/docs/index.rst b/docs/index.rst
index c4f041405..c8c4601aa 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -132,6 +132,7 @@ IdentityServer is officially certified by the OpenID Foundation and part of the
    reference/api_resource
    reference/client
    reference/grant_validation_result
+   reference/profileservice
    reference/interactionservice
    reference/options
 
diff --git a/docs/reference/client.rst b/docs/reference/client.rst
index 31cf4e95c..74f3d933f 100644
--- a/docs/reference/client.rst
+++ b/docs/reference/client.rst
@@ -34,16 +34,22 @@ Basics
     This is useful to harden flows that allow multiple response types 
     (e.g. by disallowing a hybrid flow client that is supposed to use `code id_token` to add the `token` response type 
     and thus leaking the token to the browser.
+``Properties``
+    Dictionary to hold any custom client-specific values as needed.
 
 Authentication/Logout
 ^^^^^^^^^^^^^^^^^^^^^
 
 ``PostLogoutRedirectUris``
     Specifies allowed URIs to redirect to after logout. See the `OIDC Connect Session Management spec <https://openid.net/specs/openid-connect-session-1_0.html>`_ for more details.
-``LogoutUri``
-    Specifies logout URI at client for HTTP based logout. See the `OIDC Front-Channel spec <https://openid.net/specs/openid-connect-frontchannel-1_0.html>`_ for more details.
-``LogoutSessionRequired``
-    Specifies if the user's session id should be sent to the LogoutUri. Defaults to true.
+``FrontChannelLogoutUri``
+    Specifies logout URI at client for HTTP based front-channel logout. See the `OIDC Front-Channel spec <https://openid.net/specs/openid-connect-frontchannel-1_0.html>`_ for more details.
+``FrontChannelLogoutSessionRequired``
+    Specifies if the user's session id should be sent to the FrontChannelLogoutUri. Defaults to true.
+``BackChannelLogoutUri``
+    Specifies logout URI at client for HTTP based back-channel logout. See the `OIDC Back-Channel spec <https://openid.net/specs/openid-connect-backchannel-1_0.html>`_ for more details.
+``BackChannelLogoutSessionRequired``
+    Specifies if the user's session id should be sent in the request to the BackChannelLogoutUri. Defaults to true.
 ``EnableLocalLogin``
     Specifies if this client can use local accounts, or external IdPs only. Defaults to `true`.
 ``IdentityProviderRestrictions``
@@ -94,6 +100,8 @@ Consent Screen
     Specifies whether a consent screen is required. Defaults to `true`.
 ``AllowRememberConsent``
     Specifies whether user can choose to store consent decisions. Defaults to `true`.
+``ConsentLifetime``
+    Lifetime of a user consent in seconds. Defaults to null (no expiration).
 ``ClientName``
     Client display name (used for logging and consent screen)
 ``ClientUri``
diff --git a/docs/reference/options.rst b/docs/reference/options.rst
index 8efdd8efb..ccf0f8581 100644
--- a/docs/reference/options.rst
+++ b/docs/reference/options.rst
@@ -6,6 +6,9 @@ IdentityServer Options
     Set the issuer name that will appear in the discovery document and the issued JWT tokens.
     It is recommended to not set this property, which infers the issuer name from the host name that is used by the clients.
 
+* ``PublicOrigin``
+    The origin of this server instance, e.g. https://myorigin.com. If not set, the origin name is inferred from the request.
+
 Endpoints
 ^^^^^^^^^
 Allows enabling/disabling individual endpoints, e.g. token, authorize, userinfo etc.
@@ -20,18 +23,17 @@ The ``CustomEntries`` dictionary allows adding custom elements to the discovery
 
 Authentication
 ^^^^^^^^^^^^^^
-* ``AuthenticationScheme``
-    If set, specifies the cookie middleware you want to use. If not set, IdentityServer will use a built-in cookie middleware with default values.
+* ``CookieLifetime``
+    The authentication cookie lifetime (only effective if the IdentityServer-provided cookie handler is used).
 
-* ``RequireAuthenticatedUserForSignOutMessage``
-    Indicates if user must be authenticated to accept parameters to end session endpoint. Defaults to ``false``.
+* ``CookieSlidingExpiration``
+    Specified if the cookie should be sliding or not (only effective if the IdentityServer-provided cookie handler is used).
 
-* ``FederatedSignOutPaths``
-    Collection of paths that match ``SignedOutCallbackPath`` on any middleware being used to support external identity providers (such as AzureAD, or ADFS).
-    ``SignedOutCallbackPath`` is used as the "signout cleanup" endpoint called from upstream identity providers when the user signs out of that upstream provider.
-    This ``SignedOutCallbackPath`` is typically invoked in an ``<iframe>`` from the upstream identity provider, and is intended to sign the user out of the application. 
-    Given that IdentityServer should notify all of its client applications when a user signs out, IdentityServer must extend the behavior at these ``SignedOutCallbackPath`` endpoints to sign the user our of any client applictions of IdentityServer.
+* ``RequireAuthenticatedUserForSignOutMessage``
+    Indicates if user must be authenticated to accept parameters to end session endpoint. Defaults to false.
 
+* ``CheckSessionCookieName``
+    The name of the cookie used for the check session endpoint.
 
 Events
 ^^^^^^
diff --git a/docs/reference/profileservice.rst b/docs/reference/profileservice.rst
new file mode 100644
index 000000000..ea054d47b
--- /dev/null
+++ b/docs/reference/profileservice.rst
@@ -0,0 +1,50 @@
+.. _refProfileService:
+Profile Service
+===============
+
+Often IdentityServer requires identity information about users when creating tokens or when handling requests to the userinfo or introspection endpoints.
+By default, IdentityServer only has the claims in the authentication cookie to draw upon for this identity data.
+
+It is impractical to put all of the possible claims needed for users into the cookie, so IdentityServer defines an extensibility point for allowing claims to be dynamically loaded as needed for a user.
+This extensibility point is the ``IProfileService`` and it is common for a developer to implement this interface to access a custom database or API that contains the identity data for users.
+
+IProfileService APIs
+^^^^^^^^^^^^^^^^^^^^
+
+``GetProfileDataAsync``
+    The API that is expected to load claims for a user. It is passed an instance of ``ProfileDataRequestContext``.
+
+``IsActiveAsync``
+    The API that is expected to indicate if a user is currently allowed to obtain tokens. It is passed an instance of ``IsActiveContext``.
+
+ProfileDataRequestContext
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Models the request for user claims and is the vehicle to return those claims. It contains these properties:
+
+``Subject``
+    The ``ClaimsPrincipal`` modeling the user. If the request The claims from the user's cooke will be in the ``ClaimsPrincipal``.
+``Client``
+    The ``Client`` for which the claims are being requested.
+``RequestedClaimTypes``
+    The collection of claim types being requested.
+``Caller``
+    An identifier for the context in which the claims are being requested (e.g. an identity token, an access token, or the user info endpoint). The constant ``IdentityServerConstants.ProfileDataCallers`` contains the different constant values.
+``IssuedClaims``
+    The list of ``Claim``s that will be returned. This is expected to be populated by the custom ``IProfileService`` implementation.
+``AddRequestedClaims``
+    Extension method on the ``ProfileDataRequestContext`` to populate the ``IssuedClaims``, but first filters the claims based on ``RequestedClaimTypes``.
+
+IsActiveContext
+^^^^^^^^^^^^^^^
+
+Models the request to determine is the user is currently allowed to obtain tokens. It contains these properties:
+
+``Subject``
+    The ``ClaimsPrincipal`` modeling the user. If the request The claims from the user's cooke will be in the ``ClaimsPrincipal``.
+``Client``
+    The ``Client`` for which the claims are being requested.
+``Caller``
+    An identifier for the context in which the claims are being requested (e.g. an identity token, an access token, or the user info endpoint). The constant ``IdentityServerConstants.ProfileDataCallers`` contains the different constant values.
+``IsActive``
+    The flag indicating if the user is allowed to obtain tokens. This is expected to be assigned by the custom ``IProfileService`` implementation.
diff --git a/docs/topics/apis.rst b/docs/topics/apis.rst
index 092b658ea..be4b6ad10 100644
--- a/docs/topics/apis.rst
+++ b/docs/topics/apis.rst
@@ -6,63 +6,73 @@ IdentityServer issues access tokens in the `JWT <https://tools.ietf.org/html/rfc
 Every relevant platform today has support for validating JWT tokens, a good list of JWT libraries can be found `here <https://jwt.io>`_.
 Popular libraries are e.g.:
 
-* `JWT bearer authentication middleware <https://www.nuget.org/packages/Microsoft.AspNetCore.Authentication.JwtBearer/>`_ for ASP.NET Core
+* `JWT bearer authentication handler <https://www.nuget.org/packages/Microsoft.AspNetCore.Authentication.JwtBearer/>`_ for ASP.NET Core
 * `JWT bearer authentication middleware <https://www.nuget.org/packages/Microsoft.Owin.Security.Jwt>`_ for Katana
 * `jsonwebtoken <https://www.npmjs.com/package/jsonwebtoken>`_ for nodejs
 
-Protecting an MVC Core-based API is only a matter of adding the nuget package *(Microsoft.AspNetCore.Authentication.JwtBearer)* to your project
-and adding the middleware to the ASP.NET Core pipeline::
+Protecting a ASP.NET Core-based API is only a matter of configuring the JWT bearer authentication handler in DI, and adding the authentication middleware to the pipeline::
 
     public class Startup
     {
-        public void Configure(IApplicationBuilder app)
+        public void ConfigureServices(IServiceCollection services)
         {
-            app.UseJwtBearerAuthentication(new JwtBearerOptions
-            {
-                // base-address of your identityserver
-                Authority = "https://demo.identityserver.io",
-                
-                // name of the API resource
-                Audience = "api1",
-
-                AutomaticAuthenticate = true,
-                AutomaticChallenge = true
-            });
+            services.AddMvc();
 
+            services.AddAuthentication("Bearer")
+                .AddJwtBearer(options =>
+                {
+                    // base-address of your identityserver
+                    options.Authority = "https://demo.identityserver.io";
+
+                    // name of the API resource
+                    options.Audience = "api1";
+                });
+        }
+
+        public void Configure(IApplicationBuilder app, ILoggerFactory loggerFactory)
+        {
+            app.UseAuthentication();
             app.UseMvc();
         }
     }
-
-The IdentityServer authentication middleware
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Our authentication middleware serves the same purpose as the above middleware 
-(in fact it uses the Microsoft JWT middleware internally), but adds a couple of additional features:
+    
+The IdentityServer authentication handler
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Our authentication handler serves the same purpose as the above handler 
+(in fact it uses the Microsoft JWT library internally), but adds a couple of additional features:
 
 * support for both JWTs and reference tokens
 * extensible caching for reference tokens
 * unified configuration model
 * scope validation
 
-For the simplest case, our middleware looks very similar to the above snippet::
+For the simplest case, our handler configuration looks very similar to the above snippet::
 
     public class Startup
     {
-        public void Configure(IApplicationBuilder app)
+        public void ConfigureServices(IServiceCollection services)
         {
-            app.UseIdentityServerAuthentication(new IdentityServerAuthenticationOptions
-            {
-                Authority = "https://demo.identityserver.io",
-                ApiName = "api1"
+            services.AddMvc();
 
-                AutomaticAuthenticate = true,
-                AutomaticChallenge = true
-            });
+            services.AddAuthentication("Bearer")
+                .AddIdentityServerAuthentication(options =>
+                {
+                    // base-address of your identityserver
+                    options.Authority = "https://demo.identityserver.io";
 
+                    // name of the API resource
+                    options.ApiName = "api1";
+                });
+        }
+
+        public void Configure(IApplicationBuilder app, ILoggerFactory loggerFactory)
+        {
+            app.UseAuthentication();
             app.UseMvc();
         }
     }
 
-You can get the middleware from `nuget <https://www.nuget.org/packages/IdentityServer4.AccessTokenValidation/>`_ 
+You can get the package from `nuget <https://www.nuget.org/packages/IdentityServer4.AccessTokenValidation/>`_ 
 or `github <https://github.com/IdentityServer/IdentityServer4.AccessTokenValidation>`_.
 
 Supporting reference tokens
@@ -70,32 +80,32 @@ Supporting reference tokens
 If the incoming token is not a JWT, our middleware will contact the introspection endpoint found in the discovery document to validate the token.
 Since the introspection endpoint requires authentication, you need to supply the configured API secret, e.g.::
 
-    app.UseIdentityServerAuthentication(new IdentityServerAuthenticationOptions
+    .AddIdentityServerAuthentication(options =>
     {
-        Authority = "https://demo.identityserver.io",
-        ApiName = "api1",
-        ApiSecret = "secret",
+        // base-address of your identityserver
+        options.Authority = "https://demo.identityserver.io";
 
-        AutomaticAuthenticate = true,
-        AutomaticChallenge = true
-    });
+        // name of the API resource
+        options.ApiName = "api1";
+        options.ApiSecret = "secret";
+    })
 
 Typically, you don't want to do a roundtrip to the introspection endpoint for each incoming request. The middleware has a built-in cache that you can enable like this::
 
-    app.UseIdentityServerAuthentication(new IdentityServerAuthenticationOptions
+    .AddIdentityServerAuthentication(options =>
     {
-        Authority = "https://demo.identityserver.io",
-        ApiName = "api1",
-        ApiSecret = "secret",
+        // base-address of your identityserver
+        options.Authority = "https://demo.identityserver.io";
 
-        EnableCaching = true,
-        CacheDuration = TimeSpan.FromMinutes(10), // that's the default
+        // name of the API resource
+        options.ApiName = "api1";
+        options.ApiSecret = "secret";
 
-        AutomaticAuthenticate = true,
-        AutomaticChallenge = true
-    });
+        options.EnableCaching = true;
+        options.CacheDuration = TimeSpan.FromMinutes(10); // that's the default
+    })
 
-The middleware will use whatever `IDistributedCache` implementation is registered in the DI container (e.g. the standad `IDistributedInMemoryCache`).
+The handler will use whatever `IDistributedCache` implementation is registered in the DI container (e.g. the standad `IDistributedInMemoryCache`).
 
 Validating scopes
 ^^^^^^^^^^^^^^^^^
@@ -104,16 +114,17 @@ The `ApiName` property checks if the token has a matching audience (or short ``a
 In IdentityServer you can also sub-divide APIs into multiple scopes. If you need that granularity and want to check those scopes at the middleware level, 
 you can add the ``AllowedScopes`` property::
 
-    app.UseIdentityServerAuthentication(new IdentityServerAuthenticationOptions
+    .AddIdentityServerAuthentication(options =>
     {
-        Authority = "https://demo.identityserver.io",
-        ApiName = "api1",
-        
-        AllowedScopes = { "api1.read", "api1.write" }
-
-        AutomaticAuthenticate = true,
-        AutomaticChallenge = true
-    });
+        // base-address of your identityserver
+        options.Authority = "https://demo.identityserver.io";
+
+        // name of the API resource
+        options.ApiName = "api1";
+        options.ApiSecret = "secret";
+
+        options.AllowedScopes = { "api1.read", "api1.write" };
+    })
 
 
 **Note on Targeting Earlier .NET Frameworks**
diff --git a/docs/topics/clients.rst b/docs/topics/clients.rst
index 484c6455a..e633dc5a6 100644
--- a/docs/topics/clients.rst
+++ b/docs/topics/clients.rst
@@ -81,7 +81,7 @@ This flow gives you the best security because the access tokens are transmitted
         
         RedirectUris =           { "http://localhost:21402/signin-oidc" },
         PostLogoutRedirectUris = { "http://localhost:21402/" },
-        LogoutUri =                "http://localhost:21402/signout-oidc",
+        FrontChannelLogoutUri =  "http://localhost:21402/signout-oidc",
 
         AllowedScopes = 
         {
diff --git a/docs/topics/deployment.rst b/docs/topics/deployment.rst
index 8e145b75c..3f2728673 100644
--- a/docs/topics/deployment.rst
+++ b/docs/topics/deployment.rst
@@ -2,8 +2,9 @@ Deployment
 ==========
 Your identity server is `just` a standard ASP.NET Core appplication including the IdentityServer middleware.
 Read the official Microsoft `documenatation <https://docs.microsoft.com/en-us/aspnet/core/publishing>`_ on publishing and deployment first.
+You will also most likely need to configure the `ASP.NET Core data protection <https://docs.microsoft.com/en-us/aspnet/core/security/data-protection/configuration/overview?tabs=aspnetcore2x>`_ for a load-balanced environment.
 
-One common question is how to configure ASP.NET Core correctly behind a load-balancer or a reverse proxy. Check this github `issue <https://github.com/aspnet/Docs/issues/2384>`_ for more info.
+.. note:: One common question is how to configure ASP.NET Core correctly behind a load-balancer or a reverse proxy. Check this github `issue <https://github.com/aspnet/Docs/issues/2384>`_ for more info.
 
 Configuration data
 ^^^^^^^^^^^^^^^^^^
diff --git a/docs/topics/logging.rst b/docs/topics/logging.rst
index eaba8ac01..4abd35bf5 100644
--- a/docs/topics/logging.rst
+++ b/docs/topics/logging.rst
@@ -25,31 +25,38 @@ From Package Manager Console verify that Default Project drop-down has your proj
     install-package Serilog.Sinks.File
     install-package Serilog.Sinks.Literate
 
-You want to setup logging as early as possible in your application host, e.g. in the constructor of your startup class, e.g::
+You want to setup logging as early as possible in your application host, e.g. in ``Main``::
 
-    public class Startup
+    public class Program
     {
-        public Startup(ILoggerFactory loggerFactory, IHostingEnvironment environment)
+        public static void Main(string[] args)
         {
-            var serilog = new LoggerConfiguration()
-                .MinimumLevel.Verbose()
+            Console.Title = "IdentityServer4";
+
+            Log.Logger = new LoggerConfiguration()
+                .MinimumLevel.Debug()
+                .MinimumLevel.Override("Microsoft", LogEventLevel.Warning)
+                .MinimumLevel.Override("System", LogEventLevel.Warning)
+                .MinimumLevel.Override("Microsoft.AspNetCore.Authentication", LogEventLevel.Information)
                 .Enrich.FromLogContext()
-                .WriteTo.File(@"identityserver4_log.txt");
-
-            if (environment.IsDevelopment())
-            {
-                serilog.WriteTo.LiterateConsole(outputTemplate: "[{Timestamp:HH:mm:ss} {Level}] {SourceContext}{NewLine}{Message}{NewLine}{Exception}{NewLine}");
-            }
-
-            loggerFactory
-                .WithFilter(new FilterLoggerSettings
-                {
-                    { "IdentityServer", LogLevel.Debug },
-                    { "Microsoft", LogLevel.Information },
-                    { "System", LogLevel.Error },
-                })
-                .AddSerilog(serilog.CreateLogger());
+                .WriteTo.File(@"identityserver4_log.txt")
+                .WriteTo.Console(outputTemplate: "[{Timestamp:HH:mm:ss} {Level}] {SourceContext}{NewLine}{Message:lj}{NewLine}{Exception}{NewLine}", theme: AnsiConsoleTheme.Literate)
+                .CreateLogger();
+
+            BuildWebHost(args).Run();
         }
+
+        public static IWebHost BuildWebHost(string[] args)
+        {
+            return WebHost.CreateDefaultBuilder(args)
+                    .UseStartup<Startup>()
+                    .ConfigureLogging(builder =>
+                    {
+                        builder.ClearProviders();
+                        builder.AddSerilog();
+                    })
+                    .Build();
+        }            
     }
 
 Further reading
diff --git a/docs/topics/signin.rst b/docs/topics/signin.rst
index ba7f107f6..a856c5f63 100644
--- a/docs/topics/signin.rst
+++ b/docs/topics/signin.rst
@@ -6,13 +6,31 @@ In order for IdentityServer to issue tokens on behalf of a user, that user must
 
 Cookie authentication
 ^^^^^^^^^^^^^^^^^^^^^
-Authentication is tracked with a cookie managed by the `cookie authentication <https://docs.microsoft.com/en-us/aspnet/core/security/authentication/cookie>`_ middleware from ASP.NET Core.
-You can register the cookie middleware yourself, or IdentityServer can automatically register it.
+Authentication is tracked with a cookie managed by the `cookie authentication <https://docs.microsoft.com/en-us/aspnet/core/security/authentication/cookie>`_ handler from ASP.NET Core.
+You can register the cookie handler yourself, or you can use the one that IdentityServer automatically registers.
+IdentityServer uses whichever cookie handler that matches the ``DefaultAuthenticateScheme`` as configured on the ``AuthenticationOptions`` when using ``AddAuthentication`` from ASP.NET Core.
 
-If you wish to use your own cookie authentication middleware (typically to change the default settings), then you must tell IdentityServer by setting the 
-``AuthenticationScheme`` configuration property via the :ref:`options <refOptions>`.
-If you do not configure this, then IdentityServer will register the middleware using the constant ``IdentityServerConstants.DefaultCookieAuthenticationScheme`` 
-as the authentication scheme.
+Overriding cookie handler configuration
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If you wish to use your own cookie authentication handler (typically to change the default settings), then you must configure it yourself.
+This must be done in ``ConfigureServices`` after registering IdentityServer in DI (with ``AddIdentityServer``).
+For example::
+
+    services.AddIdentityServer()
+        .AddInMemoryClients(Clients.Get())
+        .AddInMemoryIdentityResources(Resources.GetIdentityResources())
+        .AddInMemoryApiResources(Resources.GetApiResources())
+        .AddDeveloperSigningCredential()
+        .AddTestUsers(TestUsers.Users);
+
+    services.AddAuthentication("MyCookie")
+        .AddCookie("MyCookie", options =>
+        {
+            options.ExpireTimeSpan = ...;
+        });
+
+.. note:: IdentityServer internally calls both ``AddAuthentication`` and ``AddCookie`` with a custom scheme (via the constant ``IdentityServerConstants.DefaultCookieAuthenticationScheme``), so to override them you must make the same calls after ``AddIdentityServer``.
 
 Login User Interface and Identity Management System
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -38,13 +56,13 @@ On your login page you might require information about the context of the reques
 (such as client, prompt parameter, IdP hint, or something else).
 This is made available via the ``GetAuthorizationContextAsync`` API on the the :ref:`interaction service <refInteractionService>`.
 
-AuthenticationManager and Claims
+Issuing a cookie and Claims
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-The ``AuthenticationManager`` from ASP.NET Core is used to issue the authentication cookie and sign a user in. 
-The authentication scheme used must match the cookie middleware you are using (see above).
+There are authentication-related extension methods on the ``HttpContext`` from ASP.NET Core to issue the authentication cookie and sign a user in. 
+The authentication scheme used must match the cookie handler you are using (see above).
 
 When you sign the user in you must issue at least a ``sub`` claim and a ``name`` claim.
-IdentityServer provides a few ``SignInAsync`` extension methods on the ``AuthenticationManager`` to make this more convenient.
+IdentityServer also provides a few ``SignInAsync`` extension methods on the ``HttpContext`` to make this more convenient.
 
 You can also optionally issue an ``idp`` claim (for the identity provider name), an ``amr`` claim (for the authentication method used), and/or an ``auth_time`` claim (for the epoch time a user authenticated).
 If you do not provide these, then IdentityServer will provide default values.
diff --git a/docs/topics/signin_external_providers.rst b/docs/topics/signin_external_providers.rst
index 48e8c7654..d5fa64038 100644
--- a/docs/topics/signin_external_providers.rst
+++ b/docs/topics/signin_external_providers.rst
@@ -6,46 +6,59 @@ ASP.NET Core has a flexible way to deal with external authentication. This invol
 
 .. Note:: If you are using ASP.NET Identity, many of the underlying technical details are hidden from you. It is recommended that you also read the Microsoft `docs <https://docs.microsoft.com/en-us/aspnet/core/security/authentication/social/>`_ and do the ASP.NET Identity :ref:`quickstart <refAspNetIdentityQuickstart>`.
 
-Adding authentication middleware
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-The protocol implementation that is needed to talk to an external provider is encapsulated in an so-called *authentication middleware*.
+Adding authentication handlers for external providers
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+The protocol implementation that is needed to talk to an external provider is encapsulated in an *authentication handler*.
 Some providers use proprietary protocols (e.g. social providers like Facebook) and some use standard protocols, e.g. OpenID Connect, WS-Federation or SAML2p.
 
-See this :ref:`quickstart <refExternalAuthenticationQuickstart>` for step-by-step instructions for adding middleware and configuring it.
+See this :ref:`quickstart <refExternalAuthenticationQuickstart>` for step-by-step instructions for adding external authentication and configuring it.
 
 The role of cookies
 ^^^^^^^^^^^^^^^^^^^
-One parameter on the authentication middleware options is called the ``SignInScheme``, e.g.::
+One option on an external authentication handlers is called ``SignInScheme``, e.g.::
 
-   app.UseGoogleAuthentication(new GoogleOptions
-    {
-        AuthenticationScheme = "unique name of middleware",
-        SignInScheme = "name of cookie middleware to use",
+    services.AddAuthentication()
+        .AddGoogle("Google", options =>
+        {
+            options.SignInScheme = "scheme of cookie handler to use";
 
-        ClientId = "..."",
-        ClientSecret = "..."
-    });
+            options.ClientId = "...";
+            options.ClientSecret = "...";
+        })
 
-The signin scheme specifies the name of the cookie middleware that will temporarily store the outcome of the external authentication, 
+The signin scheme specifies the name of the cookie handler that will temporarily store the outcome of the external authentication, 
 e.g. the claims that got sent by the external provider. This is necessary, since there are typically a couple of redirects involved until you are done with the 
 external authentication process.
 
-If you don't take over control of your cookie configuration by setting your own authentication scheme on the IdentityServer options (see :ref:`here <refSignIn>`),
-we automatically register a cookie middleware called ``idsrv.external``.
+Given that this is such a common practise, IdentityServer registers a cookie handler specifically for this external provider workflow.
+The scheme is represented via the ``IdentityServerConstants.ExternalCookieAuthenticationScheme`` constant.
+If you were to use our external cookie handler, then for the ``SignInScheme`` above you'd assign the value to be the ``IdentityServerConstants.ExternalCookieAuthenticationScheme`` constant::
 
-You can also register your own like this::
+    services.AddAuthentication()
+        .AddGoogle("Google", options =>
+        {
+            options.SignInScheme = IdentityServerConstants.ExternalCookieAuthenticationScheme;
 
-    app.UseCookieAuthentication(new CookieAuthenticationOptions
-    {
-        AuthenticationScheme = "my.custom.scheme",
-        AutomaticAuthenticate = false,
-        AutomaticChallenge = false
-    });
+            options.ClientId = "...";
+            options.ClientSecret = "...";
+        })
+
+You can also register your own custom cookie handler instead, like this::
+
+    services.AddAuthentication()
+        .AddCookie("YourCustomScheme")
+        .AddGoogle("Google", options =>
+        {
+            options.SignInScheme = "YourCustomScheme";
+
+            options.ClientId = "...";
+            options.ClientSecret = "...";
+        })
 
 
 Triggering the authentication middleware
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-You invoke an external authentication middleware via the ``ChallengeAsync`` method on the ASP.NET Core authentication manager (or using the MVC ``ChallengeResult``).
+You invoke an external authentication middleware via the ``ChallengeAsync`` extension method on the ``HttpContext`` (or using the MVC ``ChallengeResult``).
 
 You typically want to pass in some options to the challenge operation, e.g. the path to your callback page and the name of the provider for bookkeeping, e.g.::
 
@@ -74,15 +87,21 @@ On the callback page your typical tasks are:
 **Inspecting the external identity**::
 
     // read external identity from the temporary cookie
-    var info = await HttpContext.Authentication.GetAuthenticateInfoAsync(IdentityServerConstants.ExternalCookieAuthenticationScheme);
-    var tempUser = info?.Principal;
-    if (tempUser == null)
+    var result = await HttpContext.AuthenticateAsync(IdentityServerConstants.ExternalCookieAuthenticationScheme);
+    if (result?.Succeeded != true)
+    {
+        throw new Exception("External authentication error");
+    }
+
+    // retrieve claims of the external user
+    var externalUser = result.Principal;
+    if (externalUser == null)
     {
         throw new Exception("External authentication error");
     }
 
     // retrieve claims of the external user
-    var claims = tempUser.Claims.ToList();
+    var claims = externalUser.Claims.ToList();
 
     // try to determine the unique id of the external user - the most common claim type for that are the sub claim and the NameIdentifier
     // depending on the external provider, some other claim type might be used
@@ -95,14 +114,19 @@ On the callback page your typical tasks are:
     {
         throw new Exception("Unknown userid");
     }
+    
+    var externalUserId = userIdClaim.Value;
+    var externalProvider = userIdClaim.Issuer;
+
+    // use externalProvider and externalUserId to find your user, or provision a new user
 
 **Clean-up and sign-in**::
 
     // issue authentication cookie for user
-    await HttpContext.Authentication.SignInAsync(user.SubjectId, user.Username, provider, props, additionalClaims.ToArray());
+    await HttpContext.SignInAsync(user.SubjectId, user.Username, provider, props, additionalClaims.ToArray());
 
     // delete temporary cookie used during external authentication
-    await HttpContext.Authentication.SignOutAsync(IdentityServerConstants.ExternalCookieAuthenticationScheme);
+    await HttpContext.SignOutAsync(IdentityServerConstants.ExternalCookieAuthenticationScheme);
 
     // validate return URL and redirect back to authorization endpoint or a local page
     if (_interaction.IsValidReturnUrl(returnUrl) || Url.IsLocalUrl(returnUrl))
diff --git a/docs/topics/signout.rst b/docs/topics/signout.rst
index 1a69ea6a3..0d2ea4df8 100644
--- a/docs/topics/signout.rst
+++ b/docs/topics/signout.rst
@@ -8,14 +8,14 @@ but given the nature of IdentityServer we must consider signing the user out of
 Removing the authentication cookie
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-To remove the authentication cookie, simply use the ``SignOut`` API on the ``AuthenticationManager`` provided by ASP.NET Core.
+To remove the authentication cookie, simply use the ``SignOutAsync`` extension method on the ``HttpContext``.
 You will need to pass the scheme used (which is provided by ``IdentityServerConstants.DefaultCookieAuthenticationScheme`` unless you have changed it)::
 
-    await HttpContext.Authentication.SignOutAsync(IdentityServerConstants.DefaultCookieAuthenticationScheme);
+    await HttpContext.SignOutAsync(IdentityServerConstants.DefaultCookieAuthenticationScheme);
 
 Or you can use the convenience extension method that is provided by IdentityServer::
 
-    await HttpContext.Authentication.SignOutAsync();
+    await HttpContext.SignOutAsync();
 
 .. Note:: Typically you should prompt the user for signout (meaning require a POST), otherwise an attacker could hotlink to your logout page causing the user to be automatically logged out.
 
@@ -23,18 +23,27 @@ Notifying clients that the user has signed-out
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 As part of the signout process you will want to ensure client applications are informed that the user has signed out.
-IdentityServer supports the `front-channel <https://openid.net/specs/openid-connect-frontchannel-1_0.html>`_ specification for server-side clients (e.g. MVC) 
+IdentityServer supports the `front-channel <https://openid.net/specs/openid-connect-frontchannel-1_0.html>`_ specification for server-side clients (e.g. MVC),
+the `back-channel <https://openid.net/specs/openid-connect-backchannel-1_0.html>`_  specification for server-side clients (e.g. MVC),
 and the `session management <https://openid.net/specs/openid-connect-session-1_0.html>`_ specification for browser-based JavaScript clients (e.g. SPA, React, Angular, etc.).
 
-**Server-side clients**
+**Front-channel server-side clients**
 
-To signout the user from the server-side client applications, the "logged out" page in IdentityServer must render an ``<iframe>`` to notify the clients that the user has signed out.
+To signout the user from the server-side client applications via the front-channel spec, the "logged out" page in IdentityServer must render an ``<iframe>`` to notify the clients that the user has signed out.
+Clients that wish to be notified must have the ``FrontChannelLogoutUri`` configuration value set.
 IdentityServer tracks which clients the user has signed into, and provides an API called ``GetLogoutContextAsync`` on the ``IIdentityServerInteractionService`` (:ref:`details <refInteractionService>`). 
 This API returns a ``LogoutRequest`` object with a ``SignOutIFrameUrl`` property that your logged out page must render into an ``<iframe>``.
 
+**Back-channel server-side clients**
+
+To signout the user from the server-side client applications via the back-channel spec, the ``SignOutIFrameUrl`` endpoint in IdentityServer will automatically trigger server-to-server invocation passing a signed sign-out request to the client.
+This means that even if there are no front-channel clients, the "logged out" page in IdentityServer must still render an ``<iframe>`` to the ``SignOutIFrameUrl`` as described above.
+Clients that wish to be notified must have the ``BackChannelLogoutUri`` configuration value set.
+
 **Browser-based JavaScript clients**
 
-Given how the `session management <https://openid.net/specs/openid-connect-session-1_0.html>`_ specification is designed, there is nothing special that you need to do to notify these clients that the user has signed out.
+Given how the `session management <https://openid.net/specs/openid-connect-session-1_0.html>`_ specification is designed, there is nothing special in IdentityServer that you need to do to notify these clients that the user has signed out.
+The clients, though, must perform monitoring on the `check_session_iframe`, and this is implemented by the `oidc-client JavaScript library <https://github.com/IdentityModel/oidc-client-js/>`_.
 
 Sign-out initiated by a client application
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -46,7 +55,5 @@ This state might be of use to the logout page, and the identifier for the state
 The ``GetLogoutContextAsync`` API on the :ref:`interaction service <refInteractionService>` can be used to load the state.
 Of interest on the ``ShowSignoutPrompt`` is the ``ShowSignoutPrompt`` which indicates if the request for sign-out has been authenticated, and therefore it's safe to not prompt the user for sign-out.
 
-By default this state is managed in a cookie.
+By default this state is managed as a protected data structure passed via the `logoutId` value.
 If you wish to use some other persistence between the end session endpoint and the logout page, then you can implement ``IMessageStore<LogoutMessage>`` and register the implementation in DI.
-
-When the "logged out" page renders the ``SignOutIFrameUrl`` described above, the state is then cleaned up.
diff --git a/docs/topics/signout_external_providers.rst b/docs/topics/signout_external_providers.rst
index 04b7b464c..d755db02c 100644
--- a/docs/topics/signout_external_providers.rst
+++ b/docs/topics/signout_external_providers.rst
@@ -17,24 +17,36 @@ The workflow at sign-out is then to revoke IdentityServer's authentication cooki
 The post-logout redirect shoud maintain the necessary sign-out state described :ref:`here <refSignOut>` (i.e. the ``logoutId`` parameter value).
 To redirect back to IdentityServer after the external provider sign-out, the ``RedirectUri`` should be used on the ``AuthenticationProperties`` when using ASP.NET Core's ``SignOutAsync`` API, for example::
 
-    // delete local authentication cookie
-    await HttpContext.Authentication.SignOutAsync();
-
-    string url = Url.Action("Logout", new { logoutId = logoutId });
-    try
-    {
-        // hack: try/catch to handle social providers that throw
-        await HttpContext.Authentication.SignOutAsync(vm.ExternalAuthenticationScheme, 
-            new AuthenticationProperties { RedirectUri = url });
-    }
-    catch(NotSupportedException) // this is for the external providers that don't have signout
+    [HttpPost]
+    [ValidateAntiForgeryToken]
+    public async Task<IActionResult> Logout(LogoutInputModel model)
     {
+        // build a model so the logged out page knows what to display
+        var vm = await _account.BuildLoggedOutViewModelAsync(model.LogoutId);
+
+        var user = HttpContext.User;
+        if (user?.Identity.IsAuthenticated == true)
+        {
+            // delete local authentication cookie
+            await HttpContext.SignOutAsync();
+
+            // raise the logout event
+            await _events.RaiseAsync(new UserLogoutSuccessEvent(user.GetSubjectId(), user.GetName()));
+        }
+
+        // check if we need to trigger sign-out at an upstream identity provider
+        if (vm.TriggerExternalSignout)
+        {
+            // build a return URL so the upstream provider will redirect back
+            // to us after the user has logged out. this allows us to then
+            // complete our single sign-out processing.
+            string url = Url.Action("Logout", new { logoutId = vm.LogoutId });
+
+            // this triggers a redirect to the external provider for sign-out
+            return SignOut(new AuthenticationProperties { RedirectUri = url }, vm.ExternalAuthenticationScheme);
+        }
+
+        return View("LoggedOut", vm);
     }
-    catch(InvalidOperationException) // this is for Windows/Negotiate
-    {
-    }
-
-
-.. Note:: It is necessary to wrap the call to ``SignOutAsync`` in a ``try/catch`` because not all external providers support sign-out, and they express it by throwing.
 
 Once the user is signed-out of the external provider and then redirected back, the normal sign-out processing at IdentityServer should execute which involves processing the ``logoutId`` and doing all necessary cleanup.
diff --git a/docs/topics/signout_federated.rst b/docs/topics/signout_federated.rst
index b6ad8c469..fa696368a 100644
--- a/docs/topics/signout_federated.rst
+++ b/docs/topics/signout_federated.rst
@@ -18,44 +18,5 @@ which means we are missing the sign-out notifications to IdentityServer's client
 We must add code for each of these federated sign-out endpoints to render the necessary notifications to achieve federated sign-out.
 
 Fortunately IdentityServer already contains this code. 
-You simply need to configure IdentityServer with the federated sign-out paths that the external identity providers will use for federated sign-out.
-This is done in the callback function of ``AddIdentityServer`` when configuring IdentityServer. 
-Simply add the appropriate paths to the ``FederatedSignOutPaths`` collection on the :ref:`authentiction options <refOptions>`.
-For example, from ``ConfigureServices``::
-
-    public IServiceProvider ConfigureServices(IServiceCollection services)
-    {
-        services.AddIdentityServer(options =>
-        {
-            options.Authentication.FederatedSignOutPaths.Add("/signout-callback-aad");
-            options.Authentication.FederatedSignOutPaths.Add("/signout-callback-adfs");
-        });
-    }
-
-Which corresponds to the external identity providers that would be configured in ``Configure``::
-
-    public void Configure(IApplicationBuilder app)
-    {
-        app.UseIdentityServer();
-
-        app.UseOpenIdConnectAuthentication(new OpenIdConnectOptions
-        {
-            AuthenticationScheme = "aad",
-            // ...
-            CallbackPath = new PathString("/signin-aad"),
-            SignedOutCallbackPath = new PathString("/signout-callback-aad"),
-            RemoteSignOutPath = new PathString("/signout-aad"),
-        });
-
-        app.UseOpenIdConnectAuthentication(new OpenIdConnectOptions
-        {
-            AuthenticationScheme = "adfs",
-            // ...
-            CallbackPath = new PathString("/signin-adfs"),
-            SignedOutCallbackPath = new PathString("/signout-callback-adfs"),
-            RemoteSignOutPath = new PathString("/signout-adfs"),
-        });
-
-        app.UseStaticFiles();
-        app.UseMvcWithDefaultRoute();
-    }
+When requests come into IdentityServer and invoke the handlers for external authentication providers, IdentityServer detects if these are federated signout requests and if they are it will automatically render the same ``<iframe>`` as :ref:`described here for signout <refSignOut>`.
+In short, federated signout is automatically supported.
diff --git a/docs/topics/startup.rst b/docs/topics/startup.rst
index 947bbcbea..5b1e1d3c1 100644
--- a/docs/topics/startup.rst
+++ b/docs/topics/startup.rst
@@ -24,13 +24,13 @@ This will return you a builder object that in turn has a number of convenience m
 * ``AddSigningCredential``
     Adds a signing key service that provides the specified key material to the various token creation/validation services.
     You can pass in either an ``X509Certificate2``, a ``SigningCredential`` or a reference to a certificate from the certificate store.
-* ``AddTemporarySigningCredential``
-    Creates temporary key material at startup time. This is for dev only scenarios when you don't have a certificate to use.
 * ``AddDeveloperSigningCredential``
-    Same purpose as the temporary signing credential. But this version persists the key to the file system so it stays stable
-    between server restarts. This addresses issues when the client/api metadata caches get out of sync during development.
-* ``AddValidationKeys``
-    Adds keys for validating tokens. They will be used by the internal token validator and will show up in the discovery document.
+    Creates temporary key material at startup time. This is for dev only scenarios when you don't have a certificate to use.
+    The generated key will be persisted to the file system so it stays stable between server restarts (can be disabled by passing ``false``). 
+    This addresses issues when the client/api metadata caches get out of sync during development.
+* ``AddValidationKey``
+    Adds a key for validating tokens. They will be used by the internal token validator and will show up in the discovery document.
+    You can pass in either an ``X509Certificate2``, a ``SigningCredential`` or a reference to a certificate from the certificate store.
     This is useful for key roll-over scenarios.
 
 **In-Memory configuration stores**
@@ -75,7 +75,7 @@ The use of ``TestUser`` is not recommended in production.
     Adds ``IResourceOwnerPasswordValidator`` implementation for validating user credentials for the resource owner password credentials grant type.
 
 * ``AddProfileService``
-    Adds ``IProfileService`` implementation for connecting to your custom user profile store.
+    Adds ``IProfileService`` implementation for connecting to your :ref:`custom user profile store<refProfileService>`.
     The ``DefaultProfileService`` class provides the default implementation which relies upon the authentication cookie as the only source of claims for issuing in tokens.
 
 * ``AddAuthorizeInteractionResponseGenerator``
@@ -118,6 +118,8 @@ You need to add IdentityServer to the pipeline by calling::
         app.UseIdentityServer();
     }
 
+.. note:: ``UseIdentityServer`` includes a call to ``UseAuthentication``, so it's not necessary to have both.
+
 There is no additional configuration for the middleware.
 
 Be aware that order matters in the pipeline. 
diff --git a/docs/topics/windows.rst b/docs/topics/windows.rst
index ce688fdc3..53d04f930 100644
--- a/docs/topics/windows.rst
+++ b/docs/topics/windows.rst
@@ -4,31 +4,12 @@ Windows Authentication
 On supported platforms, you can use IdentityServer to authenticate users using Windows authentication (e.g. against Active Directory).
 Currently Windows authentication is available when you host IdentityServer using:
 
-* Kestrel on Windows using IIS and the IIS integration package
+* `Kestrel <https://docs.microsoft.com/en-us/aspnet/core/fundamentals/servers/kestrel>`_ on Windows using IIS and the IIS integration package
+* `HTTP.sys <https://docs.microsoft.com/en-us/aspnet/core/fundamentals/servers/httpsys>`_ server on Windows
 
-* WebListener on Windows
-
-In both cases, Windows authentication is treated as external authentication that has to be invoked using an ASP.NET authentication manager challenge command.
+In both cases, Windows authentication is triggered by using the ``ChallengeAsync`` API on the ``HttpContext`` using the scheme ``"Windows"``.
 The account controller in our `quickstart UI <https://github.com/IdentityServer/IdentityServer4.Quickstart.UI>`_ implements the necessary logic.
 
-Using WebListener
-^^^^^^^^^^^^^^^^^
-When using WebListener you need to enable Windows authentication when setting up the host, e.g.::
-
-    var host = new WebHostBuilder()
-        .UseWebListener(options =>
-        {
-            options.ListenerSettings.Authentication.Schemes = AuthenticationSchemes.Negotiate | AuthenticationSchemes.NTLM;
-            options.ListenerSettings.Authentication.AllowAnonymous = true;
-        })
-        .UseUrls("https://myserver:443")
-        .UseContentRoot(Directory.GetCurrentDirectory())
-        .UseStartup<Startup>()
-        .Build();
-
-The WebListener plumbing will insert Windows authentication middleware for each authentication scheme you selected.
-You can enumerate the schemes by using the ASP.NET Core authentication manager ``GetAvailableSchemes`` method, and invoke it using the ``ChallengeAsync`` method.
-
 Using Kestrel
 ^^^^^^^^^^^^^
 When using Kestrel, you must run "behind" IIS and use the IIS integration::
@@ -41,6 +22,17 @@ When using Kestrel, you must run "behind" IIS and use the IIS integration::
         .UseStartup<Startup>()
         .Build();
 
+
+Kestrel is automatically configured when using the ``WebHost.CreateDefaultBuilder`` approach for setting up the ``WebHostBuilder``.
+
 Also the virtual directory in IIS (or IIS Express) must have Windows and anonymous authentication enabled.
 
-Just as WebListener, the IIS integration will insert a Windows authentication middleware into the HTTP pipeline that can be invoked via the authentication manager.
+The IIS integration layer will configure a Windows authentication handler into DI that can be invoked via the authentication service.
+Typically in IdentityServer it is advisable to disable this automatic behavior. 
+This is done in ``ConfigureServices``::
+
+    services.Configure<IISOptions>(iis => 
+    {
+        iis.AuthenticationDisplayName = "Windows";
+        iis.AutomaticAuthentication = false;
+    });
diff --git a/src/Host/Quickstart/Account/AccountController.cs b/src/Host/Quickstart/Account/AccountController.cs
index 99900de32..fcf49e8ef 100644
--- a/src/Host/Quickstart/Account/AccountController.cs
+++ b/src/Host/Quickstart/Account/AccountController.cs
@@ -327,7 +327,6 @@ public async Task<IActionResult> Logout(LogoutInputModel model)
                 string url = Url.Action("Logout", new { logoutId = vm.LogoutId });
 
                 // this triggers a redirect to the external provider for sign-out
-                // hack: try/catch to handle social providers that throw
                 return SignOut(new AuthenticationProperties { RedirectUri = url }, vm.ExternalAuthenticationScheme);
             }
 
diff --git a/src/IdentityServer4/Configuration/DependencyInjection/Options/AuthenticationOptions.cs b/src/IdentityServer4/Configuration/DependencyInjection/Options/AuthenticationOptions.cs
index 6efafab77..94e39d1bd 100644
--- a/src/IdentityServer4/Configuration/DependencyInjection/Options/AuthenticationOptions.cs
+++ b/src/IdentityServer4/Configuration/DependencyInjection/Options/AuthenticationOptions.cs
@@ -12,7 +12,7 @@ namespace IdentityServer4.Configuration
     public class AuthenticationOptions
     {
         /// <summary>
-        /// Sets the cookie lifetime (only effective if the built-in cookie middleware is used)
+        /// Sets the cookie lifetime (only effective if the IdentityServer-provided cookie handler is used)
         /// </summary>
         public TimeSpan CookieLifetime { get; set; } = Constants.DefaultCookieTimeSpan;