Announcing online JWT Debugger tool

JSON Web Token (JWT) is a really nice IETF spec for encoding, signing and encrypting a set of claims using JSON. JWT is a standalone spec that is already used several places, but is also an essential part of the emerging OpenID Connect.

Today I’m anonuncing a online JWT debugger tool that allows you to decode and encode JWTs. This tool is part of the Federation Lab test and debugging suite for identity protocols. The Federation Lab also contains testing tools for OpenID Connect and SAML.

This is considered a beta version, and I’ve not quality controlled the output. The tool is also currently limited to the HS256 algoritm, but if people like the tool we may add more algoritms. Please give feedback if the tool does not work as expected or you have feature requests.

OAuth 2.0 with Phonegap + ChildBrowser using the JSO library

Aside

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

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>
<html>
    <head>
        <title>OAuth Callback endpoint</title>
        <meta charset="utf-8" />
    </head>
    <body>
        Processing OAuth response...
    </body>
</html>

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

<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" charset="utf-8" src="js/jquery.js"></script>
<script type="text/javascript" charset="utf-8" src="jso/jso.js"></script>
<script type="text/javascript">

    var deviceready = function() {

        /*
         * Setup and install the ChildBrowser plugin to Phongap/Cordova.
         */
        if(window.plugins.childBrowser == null) {
            ChildBrowser.install();
        }

        // Use ChildBrowser instead of redirecting the main page.
        jso_registerRedirectHandler(window.plugins.childBrowser.showWebPage);

        /*
         * Register a handler on the childbrowser that detects redirects and
         * lets JSO to detect incomming OAuth responses and deal with the content.
         */
        window.plugins.childBrowser.onLocationChange = function(url){
            url = decodeURIComponent(url);
            console.log("Checking location: " + url);
            jso_checkfortoken('facebook', url, function() {
                console.log("Closing child browser, because a valid response was detected.");
                window.plugins.childBrowser.close();
            });
        };

        /*
         * Configure the OAuth providers to use.
         */
        jso_configure({
            "facebook": {
                client_id: "myclientid",
                redirect_uri: "https://myhost.org/callback.html",
                authorization: "https://www.facebook.com/dialog/oauth",
                presenttoken: "qs"
            }
        });

        // For debugging purposes you can wipe existing cached tokens...
        // jso_wipe();
        jso_dump();

        // Perform the protected OAuth calls.
        $.oajax({
            url: "https://graph.facebook.com/me/home",
            jso_provider: "facebook",
            jso_scopes: ["read_stream"],
            jso_allowia: true,
            dataType: 'json',
            success: function(data) {
                console.log("Response (facebook):");
                console.log(data);
            }
        });

    };

    document.addEventListener('deviceready', this.deviceready, false);

</script>

Technical details on how DiscoJuice works

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.

As a result the preferred provider is always shown on top of the list, even when the user moves between service providers running in completely separate domains. DiscoJuice achieve this even though the DiscoJuice script runs in the local context of the service provider.

SimpleSAMLphp version 1.9

UNINETT have now made version 1.9.0 of simpleSAMLphp available for download.

There have been some bugfixes since the previous release candidate. We have also made a larger fix to session expiration handling, which means that we now honor the session lifetime as set by the SAML 2.0 IdP. This may in some cases mean that users session will have a shorter lifetime than before.

The changelog is available from:

The upgrade notes have been updated:

The new release can be downloaded from:

sha1sum:

d9904da80c4990b2fec6ab054c9779d4ee885326 simplesamlphp-1.9.0.tar.gz

OAuth 2.0 Providers and State

It seems there is a bunch of OAuth 2.0 providers that does not support the (required to be supported) state parameter.

I just updated the jso library to be able to deal with that.

When you are unable to keep state, you’ll run into at least two challenges:

  • you don’t know from who the access token is sent (if you accept multiple providers on the same callback)
  • you don’t know what scopes you sent in the request. It would be natural to fallback to this scope in your token cache, if scopes were not provided in the response. Now, instead, you need to configure global scope fallbacks.

The jso documentation is updated, on how to deal with this.

Foodle has passed 3000 federated users from 180 institutions around the world

Foodle today passed 3000 registered federated users. Many of these users comes from norwegian universities, high schools and also lower education, but far from all. Users comes from 180 different institutions around the world. 32 of these has more than 20 unique users.

The usage of Foodle measured in page visits has seen a steady growth since January 1st 2008.

The Y scale on the graph above is monthly unique visits as measured by Google Analytics.

Web Application Cloud Engine for edu. Teaser: App Store

I’m currently working with a web application cloud engine, and this is a teaser of a very simple application running in the engine, representing a kind of an App Store making use of open APIs.

Soon we’ll present more advanced web application demos making use of distributed and highly available cloud storage, cross-federated authentication, privacy controls, SOA gatekeeper, and a whole lot of sparkling OAuth love and magic. We may run into WebDAV, WebFinger, Contact search, Invitation, group exchange with VOOT, notifications, gadgets and a lot more.

Stay tuned for updates.

Best-Practice for dealing with OAuth 2.0 Token expiration at the Consumer

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

If you know about other popular providers that do not follow the specification on expired tokens, contact me and I’ll adjust this document.

Federated OAuth 2.0 SAML VOOT Chat Proof of Concept

Today I’m demoing a proof of concept chat service making use of federated Login and cross-federated group exchange with the VOOT protocol. The chat application is written in Javascript, and is making use of HTML5 WebSockets for Real time communication. The server side is running on Node.js.

The javascript client is using OAuth 2.0 implicit grant with the JSO library we recently released. The user access token is requested with a specific scope for having access to groups. The access token is cahced in localstorage, and send to the chat server during the first registration message. The VOOT provider is done using a new PHP OAuth 2.0 library we have not released yet. It supports using MongoDB and Mysql for storage.

This is only a simple demo of what cross-federated real-time collaboration software can be like. Next step could be adding WebRCT video or audio, file, slide sharing etc.

See also: