andreas@uninett

Demo of connecting to Feide Connect platform within a mobile hybrid app (phonegap). We used https://github.com/andreassolberg/jso to integrate.

Today, we released a new API debugging, prototyping and test tool that is available at:

http://httpjs.net

When you arrive at the site, you'll immediately be delegated a separate sub domain, such as http://f12.httpjs.net. This subdomain is now ready to receive any kind of HTTP requests. At the site, you get a javascript editor window, where you can prototype the server side of the API server.

All requests sent to your new domain, will be processed in your browser with your custom javascript implementation. The web site will display the full HTTP log for you to inspect.

This tool is very useful for rapid development, and testing of API clients. In example, you may select a template OAuth Server implementation to start from, then attempt to return variations, invalid responses and similar to inspect how your client behaves.

UWAP Autoconfiguration with Wordpress Plugin

UNINETT WebApp Park is a collaborative infrastructure, extending Feide with simpler authentication for web services, group and authorization, activity streams, federated widgets and more.

Authentication and authorization with APIs are slightly more complex than with traditional access to web sites. The client is typically more intelligent, it being a javascript web application or a mobile native app; and communicates with a backend using an API. APIs typically also are exposed to third party app developers that may obtain access by both authenticating the third party client and the end user using it. This three-tier trust model is often referred to as "delegated authorization".

Providing a solution that only tells a client or app who the user is, is of limited usefulness. Instead the apps is in need of a supporting infrastructure that allows end users to proper authenticate and provide delegated authorization for the client or application to behave on their behalf towards one or more APIs.

For service providers themselves to setup the system infrastructure to support third party APIs with delegated authorization quickly becomes a large task to manage and maintain.

UNINETT WebApp Park (UWAP) is a prototype on a next generation Identity and supporting platform for modern applications, where the latest feature addition is API Authorization as a Service.

UWAP aims at extreme scalability, implying self-service consoles for all aspects of the added functionalities.

Managing an API

Registering a new API is as simple as a few clicks as an authenticated user at the Deverloper dashboard.

When an API is registered, the administrators have access to a management dashboard for this API Gatekeeper.

The API will also get a public page, accessible for third party developers that wants to access the API.

Setting up an Client or Mobile Application

To setup a client or mobile application to use the API protected by UWAP, the client developers will need to first register the client.

Next, the developers have access to the client credentials, and may request authorization to use generic UWAP APIs or APIs protected by the API Gatekeeper.

In this use case, we want to request access to use the example API registered above.

Moderating API Authorization for New Clients

The administrators of the API, will now be alerted that a new client is requesting authorization, involved scopes, that requires explicit moderation.

The administrators will now be presented with a moderation queue at the manamgenent console of the API.

Building an API

When building an protected API, UWAP makes it very much easier for the API developer to approach the three-tier authorization model.

The API will establish a bi-directional trust channel with the UWAP engine, involving HTTPS and a client token.

End-users accessing the client

If the client have cached an authorization token, the client will send the user to the UWAP authorization endpoint for authentication via Feide and confirming authorization of the API.

Now, the first time the user is using a specific client to access a specific API, the user would need to verify and grant that this client may access the API with the presented permissions.

(Notice this is a prototype. The UI of the grant screen will be improved a lot, containing more information about the API, the API owner and more)

Not dealing properly with token validity can cause rare and unwanted effects for end-users. You don't want to do that. This documents tries to sum up the best practice on this.

Estimate the validity period of an obtained token

When the consumer obtains a new access token, it will usually store the token in some storage for potential future use. It is very reccomended to also estimate the validity period for a token when sent to storage, in order to know that the token is expired without the need to "test" it.

At the time the consumer receives an access token response, the validity period of the token can be decided using any of these indicators, in the given order:

The expires_in property in the access token response. This value is reccomended to be included by the provider.

A special scope indicating validity period of the token. In example a scope offline may be defined to mean infinite validity.

A default value of validity period, typically per provider.

A default value of the consumer implementation, if none of the above is given. It may be infinite, or it may be a limited period.

Note 1: there is no way to indicate infinite validity period in the expires_in property (unfortunately).

Note 2: Of the indicators listed above, only the expires_in parameter is obtained in a standarized way. All other parameters are somehow configured in the client, based upon textual documentation of the provider API, or out of band agreements.

Detecting an expired tokens when using it

Even if you follow best-practice to associate a stored access token with a validity period, for a number of reasons you also should be able to deal with the fact that the token is invalid even if you assume it is valid:

the OAuth spec does not provide measures to protect against clock skew

as all of the indicators (except expires_in) are defined in documentation, out of band or manually entered, if the default value of the provider changes, the consumer is unlikely to adopt to the new validity period immediately.

the token may be invalidated by other means at the provider than expiration. There is no mechamisms built in for notifying the consumer about a token being invalidated.

Consequently, a consumers will have to deal with the situation of using an expired token.

First, it is extremely important that the consumer is able to detect the difference between generic errors at the protected endpoint and errors due to an expired token. If and only if the token is expired it is very important that the consumer uses the refresh token or starts a new flow to obtain a new valid token.

The OAuth 2.0 Core spec does not mention with a single word how to detect expired tokens. Instead this is discussed in each of the token type specs, including the popular Bearer Tokens.

For the bearer tokens, an expired token will result in the following response from a protected endpoint:

HTTP/1.1 401 Unauthorized WWW-Authenticate: Bearer realm="example", error="invalid_token", error_description="The access token expired"

The consumer should check for both the status code 401, and that the error field is set to invalid_token before requesting a new token from the provider.

Facebook

Facebook claims to be using OAuth 2.0 for its graph API. OAuth 2.0 library writers will have to balance facebook and spec compliance with care.

When a consumer uses an expired token, Facebook responds with:

HTTP/1.1 400 Bad Request WWW-Authenticate: OAuth "Facebook Platform" "invalid_token" "Error validating access token: Session has expired at unix time 1334415600. The current unix time is 1334822619."

It could be tempting to treat all 4XX responses as expired tokens, but that is not reccomended.

Instead I would provide a specific fallback for Facebook, like this:

if (status_code === 401 && parsed_www_authenticate["error"] === "invalid_token") throw new InvalidTokenException(); if (status_code === 400 && www_authenticate contains 'OAuth "Facebook Platform" "invalid_token"') throw new InvalidTokenException();

Other broken providers

This document is also the README-Phonegap.md of the JSO library.

Using JSO with Phonegap and ChildBrowser

Using JSO to perform OAuth 2.0 authorization in WebApps running on mobile devices in hybrid environment is an important deployment scenario for JSO.

Here is a detailed instruction on setting up JSO with Phonegap for iOS and configure OAuth 2.0 with Google. You may use it with Facebook or other OAuth providers as well.

Preparations

Install XCode from App Store, and iOS development kit

Install Phonegap 2.0, Cordova 2.0

Setup App

To create a new App

./create /Users/andreas/Sites/cordovatest no.erlang.test "CordovaJSOTest"

Install ChildBrowser

The original ChildBrowser plugin is available here.

However, it is not compatible with Cordova 2.0. Instead, you may use this fork of ChildBrowser which should be working with Cordova 2.0:

What you need to do is to copy these files:

in to your WebApp project area, by using drag and drop into the Plugins folder in XCode.

Now you need to edit the file found in Resources/Cordova.plist found in your WebApp project area.

In this file you need to add one array entry with '*' into ExternalHosts, and two entries into Plugins:

ChildBrowser -> ChildBrowser.js

ChildBrowserCommand -> ChildBrowserCommand

as seen on the screenshot.

Setting up your WebApp with ChildBrowser

I'd suggest to test and verify that you get ChildBrowser working before moving on to the OAuth stuff.

In your index.html file try this, and verify using the Simulator.

<script type="text/javascript" charset="utf-8" src="cordova-2.0.0.js"></script> <script type="text/javascript" charset="utf-8" src="ChildBrowser.js"></script> <script type="text/javascript"> var deviceready = function() { if(window.plugins.childBrowser == null) { ChildBrowser.install(); } window.plugins.childBrowser.showWebPage("http://google.com"); }; document.addEventListener('deviceready', this.deviceready, false); </script>

Setting up JSO

Download the latest version of JSO:

The documentation on JSO is available there as well.

The callback URL needs to point somewhere, and one approach would be to put a callback HTML page somewhere, it does not really matter where, although a host you trust. And put a pretty blank page there:

<!doctype html> OAuth Callback endpoint Processing OAuth response...

Now, setup your application index page. Here is a working example:

Here is a short description of the UNINETT WebApp Park Architecture.

Announcing UNINETT WebApp Park

There are several roles of the play of DiscoJuice, each falls into separate same-origin policies. (not all the domain names are not real, but used as an example)

The web service provider, that needs to know which provider to login the user; service.example.org.

The DiscoJuice static content, including the script, some UI elements, such as images and css; provided from static.discojuice.org.

DiscoJuice JSON Metadata feeds, a compact optimized metadata document for federations using JSON; metadata.federation.org

An IP to geo JSONP lookup service; running on geo.discojuice.org.

One or more existing discovery services; wayf.swtich.ch

A new central passive discovery service; store.discojuice.org

Installing DiscoJuice

The web service, includes in the web template of the service at service.example.org a script element referring to the static DiscoJuice javascript running at static.discojuice.org.

Also the web service includes a response.html page at service.example.org. This is used to receive responses from IdP Discovery Services.

DiscoJuice Operations

When a user clicks a login button or otherwise invokes DiscoJuice. The browser loads the script from static.discojuice.org, but runs in the context of service.example.org. The script draws the core UI of DiscoJuice on the screen, embedded in the web page running on service.example.org. The CSS and images are loaded from static.discojuice.org.

Now, DiscoJuice loads one or more metadata feeds using JSONP from metadata.federation.org. metadata.federation.org also caches provider logos adjusted to an appropriate size (approx 40x60px). On metadata.federation.org an engine runs to generate JSON metadata from SAML 2.0 Metadata, and postprocessing logos etc.

In parallell, the uses the JSONP interface of geo.discojuice.org to get the estimated geo-location of the current user, based upon lookup of IP address. This is used to preselect the country in the UI, and as a fallback geo-location of the user used to sort the entities based upon distance.

Then DiscoJuice if configured make passive IdP Discovery Requests to a set of configured Discovery Services. These requests is compatible with all existing WAYFs or Discovery Services, by using the IdP Discovery Protocol. The user is not redirected, instead the scripts load a hidden iframe within the body of the web service. The iframe's src points to the IdP Discovery endpoint at the discovery service endpoint of a remote discovery service. The return parameter to these iframe URLs are pointing back to the response.html running on service.example.org. These requests are made to check if the user has preselected any provider in any of the remote discovery services. Obviously these requests are made passive and does not always return any result, but never involves UI. The iframe content is redirected back to the response.html page with the selected provider as a query string parameter. The response.html page has a inline script that parses the response from the IdP Discovery protocol, and sends this to the parent frame (this run in the same-origin), DiscoJuice main script receives this and adjust the list of providers.

When the user has selected a provider, DiscoJuice can store use a simple addition to the IdP Discovery Protocol to be able to set the value of the selected provider on a remote domain; such as store.discojuice.org. DiscoJuice includes a hidden iframe similar to the approach above, but with a providerID set in the request. DiscoJuice has two implementation of an extended version of the Discovery Protocol, a server-side and a client-side implementation. The servier-side implementation typically uses cookies to store the selected provided in the context of store.discojuice.org. A client side implementation can use cookies or localStorage. store.discojuice.org uses access control to only leak preferred providers to clients registered in metadata, using the already established elements for that in SAML 2.0 metadata.