DPS907 notes – Thu Dec 7 2017

Introducing IA Server and the concept of a shared security environment.


Test today

The weekly test will be done sometime during the class timeslot.


Code examples reminder

The GitHub code example repository for this week, has assets that support this topic.


Maybe we can split the authentication process…

In the previous class/session, you learned many things about the process of authentication, and cookie or token validation. While related, they are separate and distinct processes.

After thinking more about these processes, one could conclude that it is possible to split the authentication process – credential validation, and cookie/token validation – into separate apps.

Yes, we could.

This would enable us to have an app dedicated only to identity management and authentication (the credential validation part).

Then, we could create a separate app, with the authentication part it needs (cookie/token validation), as well as the ability to perform resource authorization. (To perform resource authorization, an app only needs access to the security principal on the request thread.)

Additionally, we could create more apps that could use the services of the identity management and authentication server. This enables us to create a portfolio of apps that share the same security environment.


Introducing the IA Server

One of today’s code examples is IAServer. Its name – IA Server – means “Identity and Authentication Server“. It has the following features:

  • Identity management (user accounts, claims)
  • Authentication for browser clients, and cookie issuing
  • Authentication for HTTP clients, and access token issuing


How to use IA Server

IA Server is intended to be used with another app. IA Server will take care of identity management and authentication, so you do not have to add those features to the other app.

When you are programming and testing your app, you will have two instances of Visual Studio running. One will have (and run) the IA Server, and the other will have (and run) your app. Therefore, both will be running on your computer’s localhost instance of the IIS Express web server.


Configuring all your apps with a “machine key”

As discussed earlier, the encryption and decryption process for cookies or access tokens uses a “machine key”, which is a secret and cryptographically unique value, that is created when the server operating system is installed, and is then securely stored by the operating system.

The access token issuer – which is the IA Server app – uses the machine key to encrypt the access token.

Then, the access token validator – which is your app – uses the same machine key to decrypt the access token.

Both apps are running on the same computer, so they will be using the same machine key. It all works fine.

However, when you deploy the IA Server app and your other app to a real public web host (e.g. Azure), they will likely end up being deployed to different computers (or virtual machines). What will happen then?

Your app will not work. Why? The machine keys – on different computers (or virtual machines) will not match.

How can this be fixed? By generating a custom “machine key”, and saving it with each app that participates in a shared security environment. The IA Server has a controller that will do this task. Request the resource:

A “text/plain” result will be delivered, and will look similar to the following. (Each time you request the resource, the values change. Why? Look at the controller code – the values get regenerated.)

<machineKey validationKey="7F6CB937...(snipped)...E1625114" decryptionKey="B74EFD4D...(snipped)...40D1AC26" validation="SHA1"/>

Then, in the IA Server, and in each app that will share the same security environment, add this as the last entry in the system.web element of the app’s Web.config source code file.

Please note that this gets a little more complicated in an environment with different frameworks and operating systems. While the principles learned in this course can be used to make a more complex environment work, that topic treatment is beyond the scope of this course.


Keep it clean – do not add app domain logic to IA Server

Before moving on, we urge you to dedicate the IA Server to identity management and authentication (cookie/token issuing) only. Please do not add any app domain logic to the IA Server.


Building a web service that can use the IA Server

At this point, let us state a few reminders:

A security system – like our ASP.NET Identity system – includes identity management, authentication, and authorization.

The authentication process is divided into two distinct sub-tasks, 1) credential validation, and 2) cookie/token validation.

The IA Server is an app that includes identity management, and the credential validation part of authentication.

So… how can we ensure that one of our web service apps is configured with the access token validation and authorization parts?

Well, every app that we create already is configured to handle the authorization task. (It’s built in, and loads when the app loads.)

That leaves access token validation. How can we add that? Continue reading below.


Adding access token validation to a web service

To add access token validation to a web service project, there are four tasks to be done:

  1. Using the NuGet Package Manager, add some packages
  2. Create a “startup” class that loads the access token validation component
  3. Configure the app to use the just-loaded component
  4. Add a new “machine key” value to the app’s Web.config file


Before continuing, make sure that your project does NOT already use a security environment. In other words, the app’s project template must NOT use any of the authentication settings (e.g. “Individual User Accounts”). The web service project template can be used, because it includes a ready-to-use data-rich environment (the Chinook sample database), but it is NOT configured for a security environment.


Using the NuGet Package Manager, add some packages

Using the NuGet Package Manager, add these packages:

  • Microsoft.Owin.Security.OAuth
  • Microsoft.AspNet.WebApi.Owin
  • Microsoft.Owin.Host.SystemWeb


Create a “startup” class that loads the access token validation component 

Create (or copy from an existing security-aware project) a Startup.cs source code file, in the project root folder. It will load the access token validation component, using the following code:

[assembly: OwinStartup(typeof(ProjectName.Startup))]

namespace ProjectName
  public class Startup
    public void Configuration(IAppBuilder app)
      // This app does NOT create (issue) bearer tokens, but understands how to read (decrypt) and use them
      app.UseOAuthBearerAuthentication(new Microsoft.Owin.Security.OAuth.OAuthBearerAuthenticationOptions());


Configure the app to use the just-loaded component

In the App_Start > WebApiConfig.cs source code file, the Register method of the WebApiConfig class needs some additional statements to configure the app to use the just-loaded access token validation component. Just before the statement that configures attribute routing, add these statements:

  // Configure Web API to use only bearer token authentication.
  config.Filters.Add(new HostAuthenticationFilter(OAuthDefaults.AuthenticationType));


Add a new “machine key” value to the app’s Web.config file

Using the procedure that you learned above, generate a new machine key, by using the IA Server app.

Then, add it to that IA Server app, and to your app.


At this point in time, your app will be able to perform access token validation. As a result, whenever you use the [Authorize] attribute in your controllers (or use any other code that accesses the security principal), the app will be able to make authorization decisions.


Working with the IA Server and your app

As noted earlier, when you are working with a separated apps (IA Server and your app), each app’s project is loaded in Visual Studio. That means you have two instances of Visual Studio running.

Then, you run/execute the apps. Each will be configured on its own customized TCP port, and run on your computer’s IIS Express developer web server. Yes, you still interact with your apps using Fiddler.

In Fiddler, compose requests to the IA Server app for these reasons:

  1. Register a new user account (to the /api/account/register endpoint)
  2. Request an access token (to the /token endpoint)

In Fiddler, compose requests to the your app for this reason:

  1. Request a resource (GET, POST, etc.), and include the access token in the request


Compose a typical GET request that includes a token

The image below shows a typical GET request that includes a token. The request needs an “Authorization” request header, in addition to whatever else gets configured.

Click to open it full-size in a new tab/window.



Compose a typical POST request that includes a token

The image below shows a typical POST request that includes a token. The request needs an “Authorization” request header, in addition to whatever else gets configured.




Today, we learned that the authentication process has two distinct sub-tasks, each of which can be done in separated apps.

Finally, we learned more about separated apps, including a dedicated and sharable identity management and authentication (issuer) server, and an app that can use a shared security environment.



























%d bloggers like this: