From 593f4ff043ba1b964f7219b533284389df114c7c Mon Sep 17 00:00:00 2001 From: Dominick Baier Date: Fri, 3 Mar 2017 09:14:08 +0100 Subject: [PATCH 1/3] docs: add information about protocol extensibility --- docs/index.rst | 1 + docs/topics/add_protocols.rst | 83 +++++++++++++++++++++++++++++++++++ 2 files changed, 84 insertions(+) create mode 100644 docs/topics/add_protocols.rst diff --git a/docs/index.rst b/docs/index.rst index 81b0e7eb51..c98840d87e 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -98,6 +98,7 @@ IdentityServer is officially certified by the OpenID Foundation and part of the topics/reference_tokens topics/windows topics/cors + topics/add_protocols .. toctree:: :maxdepth: 2 diff --git a/docs/topics/add_protocols.rst b/docs/topics/add_protocols.rst new file mode 100644 index 0000000000..5beb4df2ce --- /dev/null +++ b/docs/topics/add_protocols.rst @@ -0,0 +1,83 @@ +Adding new Protocols +==================== + +IdentityServer4 allows adding support for other protocols besides the built-in +support for OpenID Connect and OAuth 2.0. + +You can add those additional protocol endpoints either as middleware or using e.g. MVC controllers. +In both cases you have access to the ASP.NET Core DI system which allows re-using our +internal services like access to client definitions or key material. + +A sample for adding WS-Federation support can be found `here `_. + +Typical authentication workflow +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +An authentication request typically works like this: + +* authentication request arrives at protocol endpoint +* protocol endpoint does input validation +* redirection to login page with a return URL set back to protocol endpoint (if user is anonymous) + * access to current request details via the ``IIdentityServerInteractionService`` + * authentication of user (either locally or via external authentication middleware) + * signing in the user + * redirect back to protocol endpoint +* creation of protocol response (token creation and redirect back to client) + +Useful IdentityServer services +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +To achieve the above workflow, some interaction points with IdentityServer are needed. + +**Access to configuration and redirecting to the login page** + +You can get access to the IdentityServer configuration by injecting the `IdentityServerOptions` +class into your code. This, e.g. has the configured path to the login page:: + + var returnUrl = Url.Action("Index"); + returnUrl = returnUrl.AddQueryString(Request.QueryString.Value); + + var loginUrl = _options.UserInteraction.LoginUrl; + var url = loginUrl.AddQueryString(_options.UserInteraction.LoginReturnUrlParameter, returnUrl); + + return Redirect(url); + +**Interaction between the login page and current protocol request** + +The ``IIdentityServerInteractionService`` supports turning a protocol return URL into a +parsed and validated context object:: + + var context = await _interaction.GetAuthorizationContextAsync(returnUrl); + +By default the interaction service only understands OpenID Connect protocol messages. +To extend support, you can write your own ``IReturnUrlParser``:: + + public interface IReturnUrlParser + { + bool IsValidReturnUrl(string returnUrl); + Task ParseAsync(string returnUrl); + } + +..and then register the parser in DI:: + + builder.Services.AddTransient(); + +This allows the login page to get to information like the client configuration and other +protocol parameters. + +**Access to configuration and key material for creating the protocol response** + +By injecting the `IKeyMaterialService` into your code, you get access to the configured +signing credential and validation keys:: + + var credential = await _keys.GetSigningCredentialsAsync(); + var key = credential.Key as Microsoft.IdentityModel.Tokens.X509SecurityKey; + + var descriptor = new SecurityTokenDescriptor + { + AppliesToAddress = result.Client.ClientId, + Lifetime = new Lifetime(DateTime.UtcNow, DateTime.UtcNow.AddSeconds(result.Client.IdentityTokenLifetime)), + ReplyToAddress = result.Client.RedirectUris.First(), + SigningCredentials = new X509SigningCredentials(key.Certificate, result.RelyingParty.SignatureAlgorithm, result.RelyingParty.DigestAlgorithm), + Subject = outgoingSubject, + TokenIssuerName = _contextAccessor.HttpContext.GetIdentityServerIssuerUri(), + TokenType = result.RelyingParty.TokenType + }; \ No newline at end of file From 9a2a645b91cb44f6d659f78e002a1ee2d21c0af9 Mon Sep 17 00:00:00 2001 From: Dominick Baier Date: Fri, 3 Mar 2017 09:18:29 +0100 Subject: [PATCH 2/3] docs: add back ticks --- docs/topics/add_protocols.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/topics/add_protocols.rst b/docs/topics/add_protocols.rst index 5beb4df2ce..5e09554f76 100644 --- a/docs/topics/add_protocols.rst +++ b/docs/topics/add_protocols.rst @@ -29,7 +29,7 @@ To achieve the above workflow, some interaction points with IdentityServer are n **Access to configuration and redirecting to the login page** -You can get access to the IdentityServer configuration by injecting the `IdentityServerOptions` +You can get access to the IdentityServer configuration by injecting the ``IdentityServerOptions`` class into your code. This, e.g. has the configured path to the login page:: var returnUrl = Url.Action("Index"); @@ -65,7 +65,7 @@ protocol parameters. **Access to configuration and key material for creating the protocol response** -By injecting the `IKeyMaterialService` into your code, you get access to the configured +By injecting the ``IKeyMaterialService`` into your code, you get access to the configured signing credential and validation keys:: var credential = await _keys.GetSigningCredentialsAsync(); From 494527b7f4d7cc4b067831da0064d04eaef81340 Mon Sep 17 00:00:00 2001 From: Jan-Pieter Zoutewelle Date: Mon, 6 Mar 2017 17:53:43 +0100 Subject: [PATCH 3/3] Update 1_client_credentials.rst (#880) Add MVC package option instead of referring to templates only --- docs/quickstarts/1_client_credentials.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/quickstarts/1_client_credentials.rst b/docs/quickstarts/1_client_credentials.rst index ee256c74c6..d664405745 100644 --- a/docs/quickstarts/1_client_credentials.rst +++ b/docs/quickstarts/1_client_credentials.rst @@ -82,7 +82,7 @@ Adding an API ^^^^^^^^^^^^^ Next, add an API to your solution. -You can use the ASP.NET Core Web API template for that. +You can use the ASP.NET Core Web API template for that, or add the ``Microsoft.AspNetCore.Mvc`` package to your project. Again, we recommend you take control over the ports and use the same technique as you used to configure Kestrel and the launch profile as before. This walkthrough assumes you have configured your API to run on ``http://localhost:5001``.