JWT – JSON Web Token

JWT is

JWT (JSON Web Token) is “a compact URL-safe means of representing claims to be transferred between two parties,” by its definition. (http://self-issued.info/docs/draft-ietf-oauth-json-web-token.html)

What is “claim”, then? Claim is “a peice of information asserted about a subject.” Claims are represented name/value pairs. Claims are in plain text withint JWT.

Examples of claims

  • urn:wordpress:claims:userid=1234
  • urn:foo:claims:age=27
  • urn:bar:claims:over18= true

Getting to know the each part of the request url

For example, this is a request url

param1=value1&param2=value2&client_id=my.test.local&key_uri=https://login.yourapp.local/keys/jwt.test.pem&cipher=ES512&sig=AOXiKKHYOrfGOihBDOsS2yyNVTD_29ykbPJf8hplXpUdAiRCkuU1bBtQa0dDvJpJX71UAC9vJfE2n2ZUuIIB_eWMAW85gs9ZSAWJYZ_NmtGXX-z0f_kzWO7tymTHJ1r9OMVH5CGppQGj4P8XU0pyYKBH4VQWfAbk1jEBvT0ftOLJwab9

It’s quite frustrating that you don’t know what it means when people use a technical term and everyone other than you seems to understand what he/she means. I often feel that with security things… So I write down here what I understand so far.

client_id

it’s the id you register with your authorisation service provider. If you use twitter api, then you need to register your client (can be web site, mobile, or whatever) and receive the id. It will be the id you use to access their api and get the authentication.

key_uri

It is the uri that you visit and receive the public key. With the public key you encrypt your require url and add the encrypted string as signature.

cipher

encrypting algorithm

sig

Signature, the encrypted string of your url request. from the example, the whole url part except &sig bit is called “payload” Your authentication service provider will use the signature to verify that the request is correct.

Access Token

the piece of data which proves your authorisation to access data on behalf of the user.

How does the authorisation happen with OAuth 2.0

You uses OAuth to call apis, like facebook, twitter, Huddle apis.

First, initial request

You issue a request to the authorise endpoint of the Authorisation server.

GET /request?response_type=code&client_id=s6BhdRkqt&redirect_uri=MyAppUri%3A%2F%2FMyAppServer.com/receiveAuthCode
HTTP/1.1
Host: login.huddle.net

Second, you get a response that will allow the end-user authorise the grant

HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8
. . .

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">

<html id="api" xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
   <head>
      <title>Log in to authorise this request<title>
   </head>
   <body>
      . . .
      <form action="https://login.yourapp.net/authoriseGrantRequest" method="POST">
         . . .
      </form>
   </body>
</html>

If the user successfully authorises the request, the server will redirect the user back to your registered pag, passing the Authorisation Code back.

HTTP/1.1 302 Found
Location: yourapp://yourapp.net/receiveAuthCode?code=ilWsRn1uB1

Third, obtain an Access token and its associated Refresh token

The Access token expires after a set period of time (say, 5 minutes) and must be refreshed by calling back to the authorisation server. The Refresh token is used then.

POST /token HTTP/1.1
Host: login.yourapp.net
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&client_id=s6BhdRkqt&redirect_uri=MyAppUri%3A%2F%2FMyAppServer.com/receiveAuthCode&code=i1WsRn1uB1

If the Authorisation code is valid, you get a standard HTTP 200 response similar to this.

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store

{
   "access_token":"S1AV32hkKG",
   "expires_in":300,
   "refresh_token":"8xLOxBtZp8"
}

Finally, api calls

Now as you have everything you need, you can start making calls to api. Include the Access token in the authorization header field of HTTP requests.

GET https://api.yourapp.net/v2/calendar/workspaces/all HTTP/1.1
Authorization: OAuth2 vF9dft4qmT
Accept: application/xml
Host: api.yourapp.net

Alternatively, the token can be passed as a querystring parameter.

GET https://api.yourapp.net/v2/calendar/workspaces/all?oauth_token=vF9dft4qmT HTTP/1.1
Accept: application/xml
Host: api.yourapp.net

If the Access token is expired, as it does in 5 mins, you will need to refresh it periodically with refresh token.

POST /refresh HTTP/1.1
Host: login.yourapp.net
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&client_id=s6BhdRkqt&refresh_token=n4E9O119d

Hope this helps, and I will add more details as I go on with my current security project.

JWT – JSON Web Token

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s