Simple Web Token (SWT)

Article
11/09/2015

This 2009 paper was designed as a proposed standard for Simple Web Token (SWT) for the Internet Engineering Task Force (IETF). Although it is not complete and is not a help topic, it provides interesting information about the format and use of SWT tokens.

Abstract

Version 0.9.5.1, November 04, 2009

Simple Web Token (SWT) provides a format for transmitting an assertion between two parties. The assertion is a set of name/value pairs that have been HTML form encoded and then the resulting string is asserted by a SHA 256 HMAC using a key shared between the parties.

Authors

Dick Hardt (dick.hardt@microsoft.com), Editor
Yaron Goland (yarong@microsoft.com)

License

This Specification is available under the Open Web Foundation Agreement Version 0.9, which is available at [http://groups.google.com/group/open-web-board/web/owf-agreement-for-final-specs---pt-9-draft][Note: Updated URL pending.]You can review the signed copies of the Open Web Foundation Agreement Version 0.9 for this Specification at [Insert Group Agreement Store URI], which may also include additional parties to those listed above. Your use of this Specification may be subject to other third party rights. THIS SPECIFICATION IS PROVIDED “AS IS.” The contributors expressly disclaim any warranties (express, implied, or otherwise), including implied warranties of merchantability, non-infringement, fitness for a particular purpose, or title, related to the Specification. The entire risk as to implementing or otherwise using the Specification is assumed by the Specification implementer and user. IN NO EVENT WILL ANY PARTY BE LIABLE TO ANY OTHER PARTY FOR LOST PROFITS OR ANY FORM OF INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES OF ANY CHARACTER FROM ANY CAUSES OF ACTION OF ANY KIND WITH RESPECT TO THIS SPECIFICATION OR ITS GOVERNING AGREEMENT, WHETHER BASED ON BREACH OF CONTRACT, TORT (INCLUDING NEGLIGENCE), OR OTHERWISE, AND WHETHER OR NOT THE OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Overview

Simple Web Token (SWT) defines a format for transmitting a simple assertion that is compact and formatted to be easily included in a header for protocols such as HTTP. A simple assertion can be represented as a set of name/value pairs. HTML form encoded values meet the desired objectives of being well understood and a safe format for HTTP headers.

Because SWTs will convey important identity and access information we need a way to prevent tampering. We therefore introduce the only mandatory name/value pair in SWT - HMACSHA256. This is always the last name/value pair in a SWT and the value is the SHA 256 HMAC of the other name/value pairs in the SWT.

The choice of other name/value pairs used in the SWT is outside the scope of this specification. That said there are a number of conditions and attributes that have proven their utility in a variety of assertion frameworks, specifically: Issuer, Audience and ExpiresOn. While the use of these name/value pairs is not mandatory we define them here to ease interoperability.

Finally, we expect that many attributes will be created by parties exchanging SWTs. We use reverse DNS names to help ease the creation of new attribute names without worrying about name collisions. We also support the use of URIs as names as well. Names that are neither reverse DNS names nor URIs are private names, defined by an agreement between the producer and consumer of the SWT and as such are subject to collision. The names defined in this specification are reserved.

Notation and Conventions

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119] (Bradner, B., “Key words for use in RFCs to Indicate Requirement Levels,”). Domain name examples use [RFC2606] (Eastlake, D. and A. Panitz, “Reserved Top Level DNS Names,”).

Generating a SWT

The party generating a SWT is the producer of the SWT. The party verifying a SWT is the consumer of the SWT. Prior to generating a SWT, the producer and consumer have agreed to the attributes to be contained in the SWT, and have exchanged a randomly generated 256 bit key out of band. To generate a SWT, the producer performs the following steps:

Collect the Name/Value pairs to be transported in the SWT and form encode them as application/x-www-form-urlencoded per 17.13.4 of HTML 4.01
Input the form encoded SWT and the agreed upon key to the SHA 256 HMAC process.
Take the resulting HMAC value and encode it using Base64 per Section 4 of RFC 4648.
Following the form encoding rules to add the name "HMACSHA256" and the base 64 encoded HMAC value to the end of the form encoded SWT.

Verifying a SWT

The consumer of a SWT performs the following steps to verify a SWT was produced by the producer, and has not been tampered with:

Take the submitted SWT and split the string into the portion prior to “&HMACSHA256=” and the remaining portion, which is the URL encoded HMAC. The first portion is noHMACSWT.
URL decode the remaining portion of the SWT string. This is the submittedHMAC.
Generate a HMAC for noHMACSWT using the agreed key and then encode using Base64 per Base64 Encoding per Section 4 of RFC 4648. The resulting string will be localHMAC.
Perform a character by character comparison of submittedHMAC and localHMAC. If the strings are equal then the HMAC on the SWT is valid.

SWT Example

A SWT producer wants to issue a SWT with the following information:

Issuer = issuer.example.com
ExpiresOn = 1/1/2010, Midnight
com.example.group = gold
over18 = true

With an HMAC key value (represented in base 64) of:

N4QeKa3c062VBjnVK6fb+rnwURkcwGXh7EoNK34n0uM=

In this example Issuer and ExpiresOn are reserved names from this specification. The attribute com.example.group is some agreed on definition of the syntax and semantics of group created by the owner of the example.com domain. over18 is a privately defined attribute settled on between the producer and the consumer of the SWT.

Before we can encode the SWT, we need to turn ExpiresOn into the number of seconds from 1/1/1970, Midnight UTC until the time of expiration, 1/1/2010, Midnight. The result is 1262304000.

Encoding

Encode the name/value pairs into a HTML form. The result is (line breaks inserted for readability):
```
Issuer=issuer.example.com&
ExpiresOn=1262304000&
com.example.group=gold&
over18=true
```
Next, calculate the HMAC of the previous value using the key.

Base64 encode the HMAC. The result is:

AT55+2jLQeuigpg0xm/vn7tjpSGXBUfFe0UXb0/9opE=

URL encode the resulting base64 encoded HMAC and attach it at the end of the assertion. The resulting SWT is (line breaks inserted for readability):

Issuer=issuer.example.com&
ExpiresOn=1262304000&
com.example.group=gold&
over18=true&
HMACSHA256=
AT55%2B2jLQeuigpg0xm%2Fvn7tjpSGXBUfFe0UXb0%2F9opE%3D

Decoding

Split the SWT using: &HMACSHA256= we get a noHMACSWT string of (line feeds added for readability):

Issuer=issuer.example.com&
ExpiresOn=1262304000&
com.example.group=gold&
over18=true&

and the submittedHMAC string of:

AT55%2B2jLQeuigpg0xm%2Fvn7tjpSGXBUfFe0UXb0%2F9opE%3D

Next, url decode the submittedHMAC and the result is:
```
AT55+2jLQeuigpg0xm/vn7tjpSGXBUfFe0UXb0/9opE=
```
We then calculate the localHMAC using noHMACSWT and the HMAC key value, base64 encoding the result and get the following localHMAC value:
```
AT55+2jLQeuigpg0xm/vn7tjpSGXBUfFe0UXb0/9opE=
```
We compare submittedHMAC and localHMAC and see they are the same string. We then URL decode noHMACSWT to get access to the SWT values.

SWT Attribute Names

Reserved Names

The following name/value pairs are optional. They are defined to ease interoperability for the many common scenarios where they are useful.

Name	Value Syntax	Value Semantics
Issuer	A UTF-8 String	Identifies the party that issues the SWT.
ExpiresOn	An ASCII string representing an unsigned base 10 integer number.	Identifies the moment when the SWT is not to be accepted for further processing. The expiration date/time is recorded as the number of seconds that will pass from 1970-01-01T0:0:0Z until the moment of expiration as measured in UTC.
Audience	A UTF-8 String	Identifies the SWT audience that the SWT is intended for. The intent being that if a SWT consumer receives a SWT with an audience value that does not identify the SWT audience then the SWT is to be rejected.

Issuer

A UTF-8 String

Identifies the party that issues the SWT.

ExpiresOn

An ASCII string representing an unsigned base 10 integer number.

Identifies the moment when the SWT is not to be accepted for further processing.

The expiration date/time is recorded as the number of seconds that will pass from 1970-01-01T0:0:0Z until the moment of expiration as measured in UTC.

Audience

A UTF-8 String

Identifies the SWT audience that the SWT is intended for. The intent being that if a SWT consumer receives a SWT with an audience value that does not identify the SWT audience then the SWT is to be rejected.

Public Names

A SWT producer may use a reverse DNS name or a URI to define additional attributes.

Private Names

A producer and consumer of a SWT may agree on any attribute name that is not a reserved or a public name. These names must not be in the list of reserved names defined in the “Reserved Names” section above. Unlike public names, these private names are subject to collision and should be used with caution.