Skip to content
This repository was archived by the owner on Dec 2, 2020. It is now read-only.

API2

Jump to bottom
James edited this page May 23, 2014 · 24 revisions

API2 will be full read/write, with apps and users granting permissions.

I wanted to make the workflow compatible with OAuth2, so people could use all the existing Client libraries, but I give up. There's bits I don't understand, and bits that seem optional but that massively increase security if done. I'm just going to write a workflow that is heavily inspired by OAuth2 but is locked down for security and has all the flexibility I want to be giving users and devs. If someone who really knows OAuth 2 is prepared to work with me, I'd happily still try to make compatibility.

Here's temp Docs for what we have. When released, real docs will be at http://docs.openacalendar.org/

Please comment on this ...

Notes

All tokens are random alphanumeric strings that could be between 1 or 255 chars long - the length is picked at random to increase the number of possibilities. Always allow for 255 chars long tokens in your app.

HTTPS should be used if possible. If the site doesn't have SSL installed then that's a security risk, but if so then the normal web login form and session cookies are over HTTP so whatever.

Passing variables can be GET or POST.

At the moment, all responses are JSON as denoted by .json at the end of URLS. We may add .xml and where applicable, .atom, .rss or .ical/.ics later. We may also provide URLs with nothing at the end, in which case the server will use the Accept header to decide what to send back.

Apps

Create App, get app_token and app_secret.

Set permissions app can ask for.

  • is_write_user_actions - write that user is attending events, write to users curated lists
  • is_write_calendar - write to events, groups, etc

Set callback methods the app is allowed to use. Callback methods are explained more later.

  • is_callback_url
  • is_callback_display
  • is_callback_javascript

This stops stolen app credentials being used to widely. For example, in an Android app the app_token and app_secret must be in the app and an attacker could extract them. But if this app is configured for is_callback_javascript only and not is_callback_url, the attacker can't use those tokens in a web service.

Permissions Escalation

You can set which permissions to ask for, and users will be able to edit permissions given. User can revoke permissions later.

So apps can start by asking for read access only then ask for write access later (by repeating the same process with a different scope parameter). Or they may ask for write access but get read access only. Or they may start with write access but then be bumped down to read access only later.

Apps therefore must always call /api2/current_user.json to check permissions.

Note each user grants permissions once per app. So if a user installs the same app twice (eg Android phone and Android Tablet), they all use the permissions. So if one app asks for and obtains better permissions, the other app will have that permission to.

Get Request Token

This is called in the app direct to the API, so the user can't see this.

Call /api2/request_token.json

pass:

  • app_token
  • app_secret

One of:

  • callback_url - URL to send user back to.
  • callback_display - boolean, "true". If set, the Access Token will just be shown on screen. Use for CLI scripts that say "Go to this URL, Get an Access Code, Paste it here!"
  • callback_javascript - boolean, "true". If set, Javascript interfaces will be called. This is used for Android apps that can place a WebView on a page and detect JS calls - your app can pick up and continue as soon as a Access Code is granted.

If you request a method your app is not allowed to use, it will be ignored. If you set more than 1, it will be random what happens and that's your fault.

Optional permissions to ask for. If you try to ask for a permission that your app doesn't have, it will be ignored.

  • scope - comma or space separated list of
    • permission_write_user_actions
    • permission_write_calendar

Optional

  • user_token & user_secret - You may already have Read access for a user, and be asking for write access. In this case you know which user you want back, and if you get back a different user that gets complicated. So pass these, and this request token will be for this user only.
  • state - pass a alphanumeric string of up to 255 chars in length. This will be sent back later. Use this to mitigate against http://homakov.blogspot.co.uk/2012/07/saferweb-most-common-oauth2.html

Get as JSON:

  • request_token

Redirect User to get user permission

Redirect User in their own web browser to /api2/login.html

Pass:

  • app_token
  • request_token

Here the user is asked to login then approve the app.

If callback_url is set, users web browser is redirected to this url with the GET param:

  • authorisation_token
  • state

(Because this is a GET request, there is a limit to the size of the request. http://stackoverflow.com/questions/7724270/max-size-of-url-parameters-in-get Otherwise we would pass request_token to)

If callback_display is set, authorisation_token will just be shown to user.

If callback_javascript is set, then

  • OpenACalendar.accessGranted(authorisation_token,state) is called
  • OpenACalendar.accessDenied() is called

Exchange Authorisation Token for User Token

This is called in the app direct to the API, so the user can't see this.

Call /api2/user_token.json

Pass:

  • app_token
  • app_secret
  • request_token
  • authorisation_token

Get back

  • user_token
  • user_secret

Making your first request to check your access

Call /api2/current_user.json

Pass

  • app_token
  • user_token
  • user_secret

Get back

  • user object, with details
  • permissions object, listing permissions granted

Making requests in general

Call /api2/ ....

Pass

  • app_token
  • user_token
  • user_secret

For certain read calls, you can also pass

  • app_token
  • app_secret

Security Options

A sys admin or app owner will be able to regenerate all user_token and user_secret for that app. This won't change any permissions users has granted, but will mean that all installs of the app have to re-authenticate.

Rollout

As much as possible will be in Version 1.2 of the Software. (Some minor details may come later).

In 1.2, it will be considered "Beta" and subject to change, tho we will do our best to avoid any backwards compatibility breaks. Version 1.3 will consider it "Stable" and "locked".

In Version 1.2, only sys admins will be able to create apps. People will have to talk to me to get apps on http://opentechcalendar.co.uk/ and http://hasacalendar.co.uk/ and I will be incredibly wary of allowing is_write_calendar apps. A full interface where users can make there own apps will come in 1.3 or later.

Clone this wiki locally