DPS907 notes – Tue Dec 5 2017

Another look at authentication.


Theme for this week, and code examples

We have learned the foundations of identity management (including user accounts and claims), and authentication. Last week, and in the recent Assignment 6, you built upon the identity management foundations.

This week, we will look again at the authentication process. Then, we will be able to design a system that will enable scale and flexibility, to support multiple apps that share the same security environment.

Code examples for today include:

IAServer – A server app that’s dedicated to identity management and authentication tasks

SecuredCustomer – A secured web service that uses the security environment that’s managed by the app above


Revisit: How a security-aware app loads (starts up)

Last week, you learned a “simplified sequence” of steps/actions that happen when an app loads into server memory. Today, we add more detail, so that we can make progress.

Here is a more-detailed sequence of actions that happen when the app is loaded:

1. In the HttpApplication subclass (WebApiApplication), the Application_Start method runs

2. (for a Web API project…) In the WebApiConfig class, the Register method runs

3. The ASP.NET runtime scans the project, looking for evidence of an OWIN configuration

4. In the Startup class, the Configuration method is run (which in turn calls the ConfigureAuth method)

5. The user accounts database is initialized

6. The user manager component is loaded into memory – it is the API to the ASP.NET Identity system

7. (if we are authenticating browser users…) The sign in manager is loaded into memory
The sign in manager’s job is to validate credentials, and issue a cookie that is included in the response

8. Cookie characteristics/properties are configured

9. Load the cookie validation component…
A CookieAuthenticationProvider object is loaded by the UseCookieAuthentication method
If a request includes a cookie, this component will decrypt/decode it, and if valid, create an IPrincipal object and attach it to the request

10. Access token characteristics/properties are configured

11. Load the access token components (token-issuing and token-validating)…
Token-issuing component:
ApplicationOAuthProvider object (inherits from OAuthAuthorizationServerProvider, loaded by UseOAuthAuthorizationServer method, which is called by UseOAuthBearerTokens method)
This object will validate credentials, and issue an access token as the response
Token-validating component:
OAuthBearerAuthenticationMiddleware (loaded by UseOAuthBearerAuthentication method, which is also called by UseOAuthBearerTokens method)
If a request includes an access token, this component will decrypt/decode it, and if valid, create an IPrincipal object and attach it to the request


How do we know all this? Well, here are the links that have more information about each numbered action:

1. ASP.NET Application Life Cycle overview for IIS 7.0 – web

2. Statements in the HttpApplication subclass, verified by debug breakpoints

3, 4. OWIN Middleware in the IIS integrated pipeline – web
OWIN Startup Class Detection – web

5, 6, 7, 8, 10. Statements in the Startup class ConfigureAuth method, verified by debug breakpoints

9. Statements (as above), verified (as above)
A primer on OWIN cookie authentication middleware for the ASP.NET developer – web

11. Statements (as above), verified (as above), and…
MSDN OAuthBearerAuthenticationMiddleware Class doc – web
MSDN OAuthBearerAuthenticationExtensions Class doc – web
MSDN OAuthBearerAuthenticationOptions Class doc – web
SO UseOAuthBearerTokens vs. UseOAuthBearerAuthentication – web


These information sources were also useful. You can read/skim these to learn more:

OWIN OAuth 2.0 Authorization Server – web

ASP.NET Web API 2: HTTP Message Lifecycle (poster) – pdf

Lifecycle of an ASP.NET MVC 5 Application – webpdf

Web API v2 Security Architecture – part of a Pluralsight online course (free) – web

Authentication Filters in ASP.NET Web API 2 – web

A selection of articles that cover the scenario where a request includes a bearer access token in the Authorization request header. Bottom line, the AuthenticateAsync method, in OAuthBearerAuthenticationHandler validates the token. Sources: SO post, MSDN doc, MSDN blog post


Why do we care about this?

Security is hard. For programmers who are new to the ASP.NET Identity system, it can appear to be large and complex. Yes, it does provide a ready-to-use solution for what we care about (identity management, authentication, authorization).

However, we must know more about this solution, to answer real-world questions like these:

How can we modify the system, so that we can perform additional tasks after a successful authentication? (For example save/record the login date-and-time.)

How can we add another separate app (web app or web service) to the server, and share or re-use the existing identity management and authentication parts? It would be annoying for everyone – us as programmers, and our users – to require another user account etc.

Answers to these and related questions are presented below.


Understanding more about the authentication process

You already know that authentication is one of the three tasks done by any security system (the others are identity management and authorization).

Let’s take another look at authentication. It can actually be divided into two distinct sub-tasks:

  1. User account credential validation
  2. Cookie/token validation


User account credential validation

In a web app, where the request comes from a browser, a user will enter their credentials on an HTML Form. In an ASP.NET MVC web app, the request is typically processed by the Account controller, specifically its Login method. The resource URI is typically host.example.com/account/login.

Look at the sequence of steps/actions above.

This is done by 7 and 8.

In a web service, where the request comes from an HTTP client, a user’s app will gather a user’s credentials by using its own native user interface. In an ASP.NET Web API web service, the request is typically processed by the ApplicationOAuthProvider class, specifically its GrantResourceOwnerCredentials method. The resource URI is typically host.example.com/token.

Look at the sequence of steps/actions above.

This is done by 10 and 11.

During this user account credential validation process, the following happens:

  1. The method validates the credentials, by attempting to match them to a user account in the identity store
  2. If successful, a cookie or access token is created and “issued”

The web app method creates a cookie, which gets returned with the response. Often the response will redirect the just-authenticated user to another web page (resource). As you have learned before, the user’s browser stores the cookie, and then includes it with each subsequent request back to the web app.

The web service method creates an access token, which gets returned as the response. As you have learned before, the user’s HTTP client must do whatever’s necessary to save/store the access token, and then include it (in a request header) with each subsequent request back to the web service.


Cookie/token validation

In the web app scenario, assume that the incoming request – to any page (resource) in the web app – includes a cookie.

In the web service scenario, assume that the incoming request – to any resource in the web service – includes an access token.

During this cookie/token validation process, the following happens:

  1. The cookie/token is decrypted, and validated
  2. If successful, an IPrincipal object – specifically a ClaimsPrincipal – is created, using the user account and claims data that is found in the cookie/token; the IPrincipal object is then attached to the request thread

How is the cookie/token decrypted by the server? Using a value known as a “machine key”. This 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 machine key is used to encrypt identity data into a cookie/token. At the browser or HTTP client, the cookie/token cannot be decrypted, as neither has the machine key. In a single isolated web app or web service scenario, the server is both the token issuer, and the token validator.

How is the cookie/token “validated”? Well, a number of things are done:

  • Was it issued by a trusted authority (yes, the issuer and validator are the same app on the same server)
  • Is it valid from a date-and-time perspective (it has an “expiry date” value)
  • Can the identity data be correctly transformed into an identity object (ClaimsPrincipal)

If all this works, then (as stated above) a ClaimsPrincipal object is created, using the user account and claims data that is found in the cookie/token. The object is then attached to the request thread, and functions that happen later in the request-processing pipleline can query the security principal and perform authorization tasks.

Look at the sequence of steps/actions above.

In a web app, this is done by 9.

In a web service, this is done by 11.



Today, you learned more about the way in which an app loads/starts.

This information was useful, because it helped us identify the components involved in the authentication process.

Next, we’ll take advantage of this new knowledge.


Get started on the assignment

Assignment 7 is now available.

Before leaving the classroom at the end of the timeslot, hand in your work report.





























%d bloggers like this: