System Explanation/Overview

[Kieran Hardern]

I am yet to write an official docomeent to explain everything. However I'll make a quick attempt here. Hopefully questions will give me a better idea what I don't explain very well.

 

System overview: user's perspective

 

1. User goes to an external organisation and selects an option to log in
   
2. User is redirected to VATSIM, where they log in and confirm they are happy for their details to be provided
   
3. User is redirected back to the external site and is logged in

 

System overview: developer's perspective

 

Note: most/all of this is handled for you by the example code. Don't feel you have to read and understand all this to get going!

 

• User selects the option to log on.
  
• System sends a signed request to VATSIM (/api/login_token/). This includes the redirect URL for the user (or a parameter specifying no return URL), identified later**
  
• VATSIM returns a "request token" (and a corresponding secret key).
  
• User is redirected to VATSIM with the token string (but not the secret) in the URL (auth/pre_login/?oauth_token=tokenstring). The token string can also be posted by the user... however typically that is not an advantage.
  
• User logs in and authorises this request token to access their details
  
• User is redirected back to the first site at the location provided in the initial request**. This return also includes a new 'verifier' string (example.com/returnurl/?oauth_token=tokenstring&oauth_verifier=verifierstring). If the initial request specified no return URL, the verification string is displayed to the user to copy & paste. If the user cancels their login, the above parameters are null and the parameter oauth_cancel is set (but null).
  
• You utilise this verifier, request token and it's corresponding secret key to ask VATSIM who the member is (/api/login_return/)
  
• VATSIM returns the user's data that was authorised.

 

All automatic requests go to the location /api/. The type of request then follows (e.g. login_token/) and finally the output format. Currently JSON and XML outputs have been created, with default being json.

 

e.g. /api/login_token/json/

 

All pages will return 2 parameters.

 

'request' with child items of 'result' and 'message'. The result will simple be a string: success or fail. Message will be blank for success, or contain a reason in the case of fail.

 

The second parameter depends upon the request you are calling and includes the useful data you need. I'll give a full overview of them when I have more time (however you can just print them out to have a look!).

 

The idea behind this 2 parameter system is so that you can error check before trying to access the returned data.

 

Technical parts

 

All parameters can be sent via headers, post or get (in that priority order) as defined by the OAuth 1.0 protocol. I'd always recommend using headers or post with the exception of when you're redirecting a user, where get is perfectly acceptable.

 

Token Request (Point 2 above)

 

/api/login_token/

 

This page accepts mandatory parameters:

oauth_consumer_key

oauth_signature_method="HMAC-SHA1" or ="RSA-SHA1"

oauth_timestamp (unix timestamp)

oauth_nonce (random, unique string)

oauth_callback (full URL to return or 'oob' which specifies out-of-band i.e. no return URL)

oauth_signature (signature generated by your signature method, above)

 

and optional parameters:

oauth_allow_suspended=1 or 0

oauth_allow_inactive=1 or 0

 

If not specified, the above default to 0.

 

This page returns 'token' which contains:

 

oauth_token

oauth_token_secret

oauth_callback_confirmed

 

JSON response type:

{"request":{"result":"success","message":""},"token":{"oauth_token":"SSO_DEMO_53d1a0ec4bab00.66097748","oauth_token_secret":"92a59475ed97382f10897ece0d47204e0a6d3077","oauth_callback_confirmed":"true"}}

XML response type:

<?xml version="1.0" encoding="UTF-8"?>
<root><request><result>success</result><message/></request><token><oauth_token>SSO_DEMO_53d1a0ec4bab00.66097748</oauth_token><oauth_token_secret>92a59475ed97382f10897ece0d47204e0a6d3077</oauth_token_secret><oauth_callback_confirmed>true</oauth_callback_confirmed></token></root>

Plain response type:

message=&oauth_callback_confirmed=true&oauth_token=SSO_DEMO_53d1a0ec4bab00.66097748&oauth_token_secret=92a59475ed97382f10897ece0d47204e0a6d3077&result=success

 

Redirect member (3)

 

Member should be redirected with the following parameter set:

oauth_token

 

User returned (6)

 

If the user is redirected back, they are returned with the following parameters in the URL (get data):

oauth_token

oauth_verifier

 

These are null if the user is redirected back having cancelled their login. In this situation oauth_cancel is also returned and null.

 

Obtain user's data(7)

 

/api/login_return/

 

Note here that I skip the conversion of a request token to an access token. This is simply because the token is one-time, which means that the security value of exchanging tokens it lost and so therefore we'd just have 2 extra round trips to process that achieve nothing.

 

The request contains:

oauth_consumer_key

oauth_token

oauth_verifier

oauth_signature_method

oauth_timestamp

oauth_nonce

oauth_signature

 

and returns 'user' which contains all of the details you are permitted regarding this user. For example:

 

JSON response type:

{"request":{"result":"success","message":""},"user":{"id":"1300007","name_first":"7th","name_last":"Test","rating":{"id":"7","short":"C3","long":"Senior Controller","GRP":"Senior Controller"},"pilot_rating":{"rating":"0"},"email":"[email protected]","experience":"N","reg_date":"2014-05-14 17:17:26","country":{"code":"GB","name":"United Kingdom"},"region":{"code":"USA-S","name":"South America"},"division":{"code":"CAM","name":"Central America"},"subdivision":{"code":null,"name":null}}}

XML response type:

<root><request><result>success</result><message/></request><user><id>1300007</id><name_first>7th</name_first><name_last>Test</name_last><rating><id>7</id><short>C3</short><long>Senior Controller</long><GRP>Senior Controller</GRP></rating><pilot_rating><rating>0</rating></pilot_rating><email>[email protected]</email><experience>N</experience><reg_date>2014-05-14 17:17:26</reg_date><country><code>GB</code><name>United Kingdom</name></country><region><code>USA-S</code><name>South America</name></region><division><code>CAM</code><name>Central America</name></division><subdivision><code/><name/></subdivision></user></root>

Plain response type:

country=GB&division=CAM&experience=N&id=1300007&message=&name_first=7th&name_last=Test&pilot_rating=1&rating=7&reg_date=2014-05-14%2017%3A17%3A26&region=USA-S&result=success&subdivision=

 

Note: name_first and name_last are UTF8 encoded

Edited October 28, 2014 at 07:13 PM by Guest

[Kieran Hardern]

Small upgrade included, post above amended to reflect change. This won't affect anyone utilising the system currently.

 

The oauth_callback parameter can now be specified as 'oob' ("out-of-band"). This is intended for when there is no return URL and the verification code is to be displayed to the member instead, to copy and paste. This is intended for applications whereby you don't want the user to see the interaction of a server in the background and have the member copy & paste the key into the program instead.

[Michael Dugan 1240047]

A more formatted/readable printout of the return for ARTCC level...Most of us will only be interested in user data, so something like $response->user->id would retrieve the CID since it is returned as a stdCl[Mod - Happy Thoughts] object.

 

object(stdCl[Mod - Happy Thoughts])#407 (2) { 
["request"]=> object(stdCl[Mod - Happy Thoughts])#411 (2) { 
	["result"]=> string(7) "success" 
	["message"]=> string(0) "" 
} 
["user"]=> object(stdCl[Mod - Happy Thoughts])#410 (12) { 
	["id"]=> string(7) "mycid_integer" 
	["name_first"]=> string(7) "Michael" 
	["name_last"]=> string(5) "Dugan" 
	["rating"]=> object(stdCl[Mod - Happy Thoughts])#412 (4) {
		["id"]=> string(1) "5" 
		["short"]=> string(2) "C1" 
		["long"]=> string(10) "Controller" 
		["GRP"]=> string(18) "Enroute Controller"
		} 
	["pilot_rating"]=> object(stdCl[Mod - Happy Thoughts])#413 (1) { 
		["rating"]=> string(1) "0" 
	} 
	["email"]=> string(19) "[email protected]" 
	["experience"]=> string(0) "" 
	["reg_date"]=> string(19) "2014-06-04 07:20:10" 
	["country"]=> object(stdCl[Mod - Happy Thoughts])#414 (2) { 
		["code"]=> string(2) "US" 
		["name"]=> string(13) "United States" 
	} 
	["region"]=> object(stdCl[Mod - Happy Thoughts])#415 (2) { 
		["code"]=> string(5) "USA-N" 
		["name"]=> string(13) "North America" 
	} 
	["division"]=> object(stdCl[Mod - Happy Thoughts])#416 (2) { 
		["code"]=> string(3) "USA" 
		["name"]=> string(13) "United States" 
	} 
	["subdivision"]=> object(stdCl[Mod - Happy Thoughts])#417 (2) { 
		["code"]=> NULL ["name"]=> NULL 
		} 
	} 
}

[Kieran Hardern]

Minor updates again, nothing that would make what you've done go wrong

[Kieran Hardern]

I'm going to lock this to keep it tidy for future viewers. Questions can be sent in new topics.