Archive

Archive for the ‘Windows’ Category

Creating sequence diagrams

October 31, 2011 Leave a comment

In this document, we briefly describe a few different ways to create sequence diagrams.

This post was most recently updated in October 2013. It is intended for programmers in a degree-level academic program that focuses on software development. This post will likely be updated a few times in the near future, to add more detail and information.

.

A brief survey of sequence diagram creation toolsets

Students in Seneca’s ICT software development programs learn to use Rational Rose to create sequence diagrams, and other software system design modeling assets.

Visual Studio 2012 Ultimate Edition now includes tooling that enables the creation of sequence diagrams.

Online, there are many tools that are offered, in both free and pay-for versions. In the following section, we’ll look at one of these tools.

.

Websequencediagrams.com

Websequencediagrams.com is an online tool that enables you to create and save sequence diagrams. Its syntax is easy and discoverable. It enables you to save your work in a PNG image, a PDF, or as source text. It also provides online tooling, via an API.

A recent post by the author (Web service security principles – OAuth 2.0 example) included two sequence diagrams.

The source text for the first diagram is below:

.

participant Resource\nOwner as RO
participant "Web\nBrowser" as ClientUI
participant Client\nApp as Client
participant Authorization\nServer as AS
participant Resource\nServer as RS

RO->ClientUI: [1] want protected resource
activate RO
activate ClientUI

ClientUI->Client: [2] GET protected resource
activate Client

Client-->ClientUI: [3] HTTP 302 redirect
deactivate Client
deactivate ClientUI

ClientUI->AS: [4] GET authentication UI
activate ClientUI
activate AS
AS-->ClientUI: [5] respond with authentication UI

ClientUI-->RO: [6] view authentication UI

RO->ClientUI: [7] enter credentials
ClientUI->AS: [8] POST the credentials

AS-->ClientUI: [9] HTTP 302 redirect to redirection endpoint
deactivate AS
deactivate ClientUI

ClientUI->Client: [10] GET auth grant exchanged
activate ClientUI
activate Client

Client->AS: [11] POST request access token
activate AS

AS-->Client: [12] respond with access token
deactivate AS

Client-->ClientUI: [13] HTTP 302 redirect
deactivate Client
deactivate ClientUI

ClientUI->Client: [14] GET protected resource
activate Client
activate ClientUI

Client->RS: [15] GET protected resource (with access token)
activate RS

RS-->Client: [16] respond with the resource
deactivate RS

Client-->ClientUI: [17] render resource in browser

deactivate Client
ClientUI-->RO: [18] view the resource
deactivate ClientUI

deactivate RO

.

The source text for the second diagram is below:

.

participant Resource\nOwner as RO
participant "Web\nBrowser" as ClientUI
participant Client\nApp as Client
participant Authorization\nServer as AS
participant Resource\nServer as RS

RO->ClientUI: [1] want protected resource
activate RO
activate ClientUI

ClientUI->Client: [2] GET protected resource
activate Client

Client->RS: [15] GET protected resource (with access token)
activate RS

RS-->Client: [16] respond with the resource
deactivate RS

Client-->ClientUI: [17] render resource in browser

deactivate Client
ClientUI-->RO: [18] view the resource
deactivate ClientUI

deactivate RO

.

.

.

.

.

.

.

Brief introduction to securing a WCF Web API service with an access token

October 30, 2011 Leave a comment

This post is a brief introduction to securing a WCF Web API service with an access token.

This document was most recently updated in October 2011. It is intended to be used by entry-level web service programmers.

.

Overview of the scenario

Token-based schemes are often used for web services that require security. Recently, in class/lecture, we described many of the relevant security principles, and the implementation components, using the OAuth 2.0 Authorization Protocol as an example.

This post includes code that illustrates the bare essentials of handling an access token.

Warning – The code below is NOT a reference sample, or a best practice example. It simply illustrates the concept, in a clearly-understandable manner. Also, it does NOT deal with authentication and authorization issues, authorization stores, or the other “moving parts” that a full and complete solution includes.

.

Sample service code

Use your template to create a new WCF Web API service. Code the service class as follows:


using System;
using System.Collections.Generic;
using System.Linq;
using System.Web;
// Web service namespaces
using System.ServiceModel;
using System.ServiceModel.Web;
// Additional namespaces
using System.Net;
using System.Net.Http;
using Microsoft.ApplicationServer.Http.Dispatcher;
using System.Net.Http.Headers;

[ServiceContract]
public class Operations
{
    // Custom authorization token
    public string customToken { get; set; }

    // Collection of access tokens, which will be an in-memory "authorization store"
    protected List<string> AccessTokenStore;

    // Constructor
    public Operations()
    {
        this.customToken = HttpContext.Current.Request.Headers["X-ICTtoken"];

        // Un-comment the following if you want to protect the whole service
        //if (this.customToken != "whatever")
        //    throw new HttpResponseException(HttpStatusCode.Forbidden);

        // Create an in-memory "authorization store", with a few access tokens
        AccessTokenStore = new List<string>();
        AccessTokenStore.Add("triUt6ustoeQ");
        AccessTokenStore.Add("KOEn4Ejouqle");
        AccessTokenStore.Add("rIuv5u7hoeno");
        AccessTokenStore.Add("y7UcIeJ9eCIa");
        AccessTokenStore.Add("Joestievief9");
    }

    // Remove this method from an in-production (deployed) web service
    [WebGet(UriTemplate = "")]
    public string ServiceRoot()
    {
        return "Append /test to the URI to use the HTTP Test Client";
    }

    [WebGet(UriTemplate = "example1")]
    public List<string> Example1(HttpRequestMessage request)
    {
        // Get the authorization header
        AuthenticationHeaderValue auth = request.Headers.Authorization;
        // The scheme should be "Bearer", and the parameter should be the access token

        if (auth == null)
        {
            throw new HttpResponseException(HttpStatusCode.Unauthorized);
        }
        else
        {
            // Create a response object
            List<string> response = new List<string>();
            // Report the results
            response.Add("The authorization scheme was: " + auth.Scheme);
            response.Add("The parameter was: " + auth.Parameter);

            // Check if the access token is in the store
            if (AccessTokenStore.Find(t => t == auth.Parameter) == null)
            {
                response.Add("The access token was NOT FOUND in the authorization store");
            }
            else
            {
                response.Add("This is a valid access token");
            }

            return response;
        }
    }

}

.

Test your service

Run the HTTP Test Client for the service.

Request the “example1” URI. It should respond with 401 unauthorized.

Now, add an “authorization header”:

Authorization:Basic foobar

The response should appear as follows:


<?xml version="1.0" encoding="utf-8"?>
<ArrayOfString xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <string>The authorization scheme was: Basic</string>
  <string>The parameter was: foobar</string>
  <string>The access token was NOT FOUND in the authorization store</string>
</ArrayOfString>

.

Next, change the authorization header:

Authorization:Bearer rIuv5u7hoeno

(or one of the valid authorization codes)

The response should appear as follows:


<?xml version="1.0" encoding="utf-8"?>
<ArrayOfString xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <string>The authorization scheme was: Bearer</string>
  <string>The parameter was: rIuv5u7hoeno</string>
  <string>This is a valid access token</string>
</ArrayOfString>

.


.

.

.

Web service security principles – OAuth 2.0 example

October 30, 2011 Leave a comment

This post discusses web service security principles, using the OAuth 2.0 Authorization Framework.

This document was most recently updated in October, 2013. It is intended for entry-level web service programmers.

.

Introduction to the scenarios

This post describes the use of a web service to deliver resources to requestors. The web service’s resources will be protected, and requestors must use the OAuth 2.0 Authorization Framework. Two scenarios are described:

1. The first scenario covers the use case where a client app, which does not yet have a valid access token, requests a protected resource.

2. The second scenario covers the use case where a client app, which has a valid access token, requests a protected resource.

A separate client app, perhaps an ASP.NET web app, would be used to request resources from the web service. Users of the client app will be able to request their own resources after authenticating.

.

OAuth 2.0 Authorization Framework information

The OAuth 2.0 Authorization Framework is described in draft-ietf-oauth-v2.

A gentle overview of OAuth can be found in this Wikipedia article.

It is currently a “draft” specification, RFC 6749, and is on the standards track. A related RFC 6750 covers access token usage.

OAuth defines four roles:

oauth-resource-ownerResource owner

An entity (e.g. an end user, typically a person, or a proxy such as credentials in a secure/trusted store) capable of granting access to a protected resource.

.

oauth-resource-serverResource server

A server that hosts a protected resource. It responds to requests by validating an access token.

.

oauth-client-appClient

Also known as a client app, this is an application that makes requests for a protected resource, on behalf of the resource owner, and with its authorization.

.

oauth-authorization-serverAuthorization server

A server that authenticates resource owners, client apps, and issues access tokens.

.

OAuth is a framework that enables a client app to use an access token to request a protected resource. The access token is issued to the client app by an authorization server, with the approval of the resource owner.

There are two defined types of client apps:

  1. Confidential – Capable of maintaining confidentiality of client app credentials.
  2. Public – Not capable of maintaining confidentiality of client app credentials.

.

There are four defined flows or scenarios that enable a resource owner to authorize the issuance of an access token:

  1. Authorization code – A resource owner is able to authenticate directly with an authorization server, and passes on an “authorization code” to the client app.
  2. Implicit – For client apps which are implemented in a browser using a scripting language (such as JavaScript).
  3. Resource owner password credentials – Where there is a high degree of trust between the resource owner and the client app (e.g. a trusted client app on a resource owner’s mobile device).
  4. Client credentials – For access to protected resources that are under the control of the client app (and not any specific/individual resource owner).

.

This post will cover the first flow/scenario, “authorization code”, with a “confidential” client.

.

Terminology and assumptions for the scenarios

This post uses terminology from the OAuth documents, plus the following:

UI = user interface

Web browser = an HTTP requestor application that renders HTML content

Client app = web app, an executable that runs on a web server (this is the OAuth ‘client’)

.

The following diagram is a high-level overview of the software components in the scenarios.

Web service as a resource server v2

.

The authorization server and the resource server share an authorization store. The authorization store holds the following kinds of information collections:

  • resource owner credentials
  • client app credentials (which has a client app identifier that will be used by the web browser)
  • authorization grant (which has a limited lifetime and scope)
  • access token (which has a limited lifetime and scope)

.

Notice that a client app is a distinct entity or construct. It must have its own identity that’s separate from a resource owner. A client app can be used by different resource owners.

.

For the following scenarios, the reader can assume that the resource owner credentials and the client app credentials already exist. Further, the authorization server has the programming, UI, and endpoints that enable the maintenance of these credentials.

The reader can also assume that the authorization server has the programming, UI, and endpoints that enable the maintenance of authorization grants and access tokens.

.

Scenario – first request for a protected resource

This scenario covers the use case where a client app, which does not yet have a valid access token, requests a protected resource.

This scenario is documented on a sequence diagram, shown below. Each signal is identified with a number in square brackets, [#], and you will find them in the text that follows.

.

How was this sequence diagram created? Click here and read this post for details. 

.

A resource owner, using a web browser, begins interacting with content in a client app. This begins a new “session” between the resource owner‘s user-agent (the web browser), and the client app.

The resource owner performs an action (e.g. clicks on a link or a button) [1] in the web browser, which causes a “GET protected resource” request to be created. The web browser sends the request to the client app [2].

Note: The web browser does NOT typically have/show the protected resource URIs from the resource server. The client app typically publishes (HTML) links that are in its domain, and maintains the mapping/lookup in its executable code.

In other words, you will typically NOT see this kind of link in the HTML markup of the web browser:

http://resourceserver.com/customer/3/

Instead, you will see this kind of link:

http://clientapp.com/customer/3

.

The client app asks “does this session have a valid access token?”

The answer will be “no”, because this is the first request for a protected resource.

Next, the client app asks “does the request from the web browser have a valid authorization grant?”

Again, the answer will be “no” (because this is the first request for a protected resource).

Consequently, the following sequence will be initiated, which will result in the acquisition of a valid access token:

  1. The resource owner authenticates with the authorization server
  2. The authorization server delivers an authorization grant to the client app
  3. The client app requests that the authorization server exchange the authorization grant for an access token

.

Before continuing, the essence of the original “GET protected resource” request must be retained. The sequence (below) will include three (3) HTTP 302 redirects, and we will be unable to persist the original request in a query string parameter.

There are several state persistence schemes available to us. For example, the client app can save this information in session state. Or, it can be sent (in the following response) as a web browser cookie. Whatever scheme you select as the programmer, you just need to retrieve the value later, when you need it.

.

Sequence step 1: The resource owner authenticates with the authorization server

The client app responds back [3] to the web browser with the following:

  1. a 302 redirect status code
  2. a “location” header with the URI of the authorization server‘s authentication UI, and the following query string key-value pairs…
    • response_type=code – for a typical interaction
    • client_id= the client app identifier
    • redirect_uri= a previously-established (between the client app and the authorization server) “redirection endpoint”

.

The web browser creates a new request, [4] “GET authentication UI”, and sends it to the (above) URI of the authorization server‘s authentication UI.

Note: The authorization server‘s authentication UI may be a specially-created page/interface, solely for the use of resource owners who want to authorize a client app. Alternatively, it may be the page/interface that is used by other general interactive users of the resource server.

.

The authorization server validates the request (to ensure that all required key-value pairs are present), and responds with the authentication UI [5], which will typically be an HTML form. (The key-value pairs are retained, in the URI query string, or in the authorization server‘s state management and persistence system.)

.

The resource owner views the form [6], enters their credentials [7], and submits them (typically with a button click). The web browser creates a [8] “POST resource owner credentials” request, and sends the request to the authorization server.

After successfully authenticating, the authorization server responds back [9] to the web browser with the following:

  1. a 302 redirect status code
  2. a “location” header with the URI of the client app‘s redirection endpoint, and the following query string key-value pair…
    • code= the authorization grant (known as the authorization code) that was generated by the authorization server

.

Sequence step 2: The authorization server delivers an authorization grant to the client app

The web browser now has a valid authorization grant.

Using the URI from the response’s “location” header, the web browser creates a new request, [10] “GET authorization grant exchanged”, and sends it to the client app.

The client app inspects the request, which was received on the redirection endpoint, and asks “does the request from the web browser have a valid authorization grant?”

The answer will be “yes” (because a valid authorization grant was received on the redirection endpoint).

Before responding to the web browser, the client app continues with the following.

.

Sequence step 3: The client app requests that the authorization server exchange the authorization grant for an access token

A valid authorization grant can be exchanged for an access token. Therefore, the client app will create a new request, [11] “POST request access token“, and send it to the “token endpoint” on the authorization server. The request includes:

  1. an “authorization” header, which includes the client app credentials
  2. HTML form-encoded key-value pairs for the following parameters…
    • grant_type=authorization_code
    • code= the authorization grant (known as the authorization code) that was generated by the authorization server
    • redirect_uri=the previously-established (between the client app and the authorization server) redirection endpoint

.

The authorization server will inspect the request. It validates the client app credentials (with a lookup to the authorization store). It validates the authorization grant (with a lookup to the authorization store). If successful, it responds with an access token [12].

The access token consists of a number of parameters, serialized as a JSON object, in the message body of an HTTP 200 response. The parameters include:

  • access_token – string – the actual access token
  • token_type – string – for example, “bearer”
  • expires_in – integer, optional – the lifetime, in seconds, of the access token

.

Now that the client app has a valid access token, it typically persists it in session state.

The client app is now ready to respond to the “GET authorization grant exchanged” request from the web browser (in sequence step 2 above).

The client app creates a response [13] that includes the following information, and sends it to the web browser:

  1. a 302 redirect status code
  2. a “location” header with the URI of the original “GET protected resource” request (which may be retrieved from a web browser cookie, or the client app‘s session state)

.

Upon receipt, the web browser creates a [14] “GET protected resource” request, and sends it to the client app.

As above (when we started this journey), the client app asks “does this session have a valid access token?”

This time, the answer will be “yes”.

The client app creates a [15] “GET protected resource (with access token)” request, and sends it to the resource server. It includes:

  1. a request URI for the actual resource
  2. an “authorization” header that includes 1) the token_type, and 2) the access_token values

.

After validating the access token, the resource server responds back to the client app with the requested resource [16].

The client app now has the protected resource that was originally requested. The protected resource is rendered for the web browser [17], where it can be viewed [18] by the resource owner.

.

Scenario – subsequent requests for protected resources

This scenario covers the use case where a client app, which has a valid access token, requests a protected resource.

This scenario is documented on a sequence diagram, shown below. Each signal is identified with a number in square brackets, [#], and you will find them in the text that follows. The numbers used for the signals are the same as you saw in the first sequence diagram (but signals 3 through 14 inclusive aren’t there, because this scenario’s client app has a valid access token).

.

The resource owner performs an action (e.g. clicks on a link or a button) [1] in the web browser, which causes a “GET protected resource” request to be created. The web browser sends the request to the client app [2].

As above, the client app asks “does this session have a valid access token?”

As you would expect, the answer will be “yes”.

The client app creates a [15] “GET protected resource (with access token)” request, and sends it to the resource server. It includes:

  1. a request URI for the actual resource
  2. an “authorization” header that includes 1) the token_type, and 2) the access_token values

.

After validating the access token, the resource server responds back to the client app with the requested resource [16].

The client app now has the protected resource that was originally requested. The protected resource is rendered [17] for the web browser, where it can be viewed by the resource owner [18].

.

.

.

.

.

.

.

.

.

.

Handle hypermedia in a WCF Web API service

October 11, 2011 Leave a comment

You have worked with XML and JSON in WCF Web API services. This post will introduce you to the handling of hypermedia.

Read more…

WCF Web API service, with EF data model, supporting POST, PUT, DELETE (on an ASP.NET web site)

October 3, 2011 Leave a comment

This post builds upon the topics in WCF Web API service with an Entity Framework data model. We add the ability to support POST, PUT, and DELETE operations.

Read more…