OAuth continued - Open the JSON API via OAuth

[sebgie]

Clients

In order to make the Ghost API accessible publicly we need to extend our support for OAuth and add different endpoints to the API for adding clients and dealing with authorization requests.

Ghost is going to support two different kinds of clients, Web and Installed Applications and JavaScript-centric applications that run on the Client Side. There is no full public access for everyone as we need to make sure that the operator of a blog is still able to deny access to clients that are not approved.

Web and Installed Applications

The Ghost API supports web, desktop and mobile application.

Public access to API endpoints:

Web and installed applications are allowed to access all API endpoints that don't require authentication by using the client authentication as described in RFC 6749 - 2.3. Client credentials (client_id and client_secret) have to be transmitted with each request to one of the public endpoints to get access. Desktop and mobile applications are distributed to individual machines, and it is assumed that these clients cannot keep secrets. Therefore no special access rights are granted when using client credentials to access the API for now.

Authenticated access to API endpoints:

If an application wants to access endpoints that requires authentication it has to use the Authorization Code Grant method described in RFC 6749 - 4.1. This grant type requires the user to be redirected to your Ghost blog, where the user authenticates the application. After successful authentication a short lived, single-use code is returned which allows the application to acquire access and refresh token on behalf of the user.

Client Side

The Ghost API supports JavaScript-centric applications. These applications are allowed to access the Ghost API but are treated differently since they typically can't keep a secret.

Public access to API endpoints:

Requests to public endpoints must send a valid client id of a registered client. This is similar to what Google does for Google Maps.

Client side applications are allowed to a access endpoints that don't require authentication if the request comes from a known domain via ajax request (localhost is allowed during development) and contains the client id of a registered application. Checking header values does not guarantee that the client is genuine, but it should prevent random attempts to access the API and allow to revoke access from unwanted clients.

Authenticated access to API endpoints:

If a client side application wants to access an endpoint that requires authentication it has to use the Implicit Grant method described in RFC 6749 - 4.2. This grant type take into account that the application can't keep a secret and therefore provides no code to acquire access and refresh tokens but returns an access token immediately. Refresh tokens are not available and a user has to authorize the app again whenever the access token expires.

To get an access token the application has to redirect the user to a Ghost server where the user authorizes the application. After successful authorization an access token is returned which grants access to the API for a limited time.

Scopes

OAuth allows to optionally specify the scope of a client. Ghost provides the concept of app permissions and I would suggest to use the same permission model for clients as well. Permissions have to be specified when the app is registered and should be presented to the user when an user authorizes an app to access the API.

Authorize endpoint

The Authorization Code Grant and Implicit Grant flows require the user to be redirected to an authorization page that runs on the Ghost server. We have to determine where we could add this page to our ember admin and how to redirect the user back to the inquiring client.

Register a client

Adding a client is done by an authorized user that manually sets up the allowed application and then copies the client credentials to the appropriate places in the client. Examples for such registration pages can be found on the developer pages of Twitter, Facebook or GitHub.

Adding the client manually is easily doable for services that only run on one domain. In our case a client application would have to be registered for every single installation of Ghost. This would require a user to add the application to Ghost before s/he could use a 3rd party client. A draft for registering clients automatically (https://tools.ietf.org/html/draft-ietf-oauth-dyn-reg-20) has been published but isn't a specification yet.

Based on the draft for registering clients automatically I would propose to allow the registration of new clients during the authorization process. That means that a 3rd party client can send registration information along with the authorization information if the client is used with a service for the first time. The user is then asked to add the new client, if he approves the authorization process continues.

Default clients

As Ghost admin and Ghost frontend also need to access the API and authenticate using oAuth there will be two default clients that are available on every Ghost blog. client_id and client_secret are generated randomly for every blog.

• Ghost admin (exists but needs update)
• Ghost frontend (new)

---

This is an overview issue for implementing further OAuth features. Issues for implementation are:

• Add columns to client table (Add columns to client table #4174)
• API endpoints for clients (API endpoints for clients #4175)
• Client API permissions (Client API permissions #4176)
• Client management screen ember ghost-ui (Client management screen #4177)
• Authorize screen ember ghost-ui (Authorize screen #4178)
• Add access control for public endpoints (Web and Installed Application) (Add access control for public endpoints (Web and Installed Application) #4179)
• Add access control for public endpoints (Public Clients) (Add access control for public endpoints (Public Clients) #4180)
• Remove authentication for public endpoints (Remove authentication for public endpoints #4181)
• Make Ember admin work with new access control (Make Ember admin work with new access control #4182)
• Implement authenticated access for Public Clients (Implicit Code Grant) (Implement authenticated access for Public Clients (Implicit Code Grant) #4183)
• Implement authenticated access for Web and Installed Apps (Authorization Code Grant) (Implement authenticated access for Public Clients (Authorization Code Grant) #4388)
• Client permissions (Scope) (tbd)

Bonus:

• Ghost frontend client (Default client entry for Ghost frontend #4184)
• Add dynamic client registration to auth screen (tbd)
• Development mode for Clients (tbd)

[novaugust]

Sa-weeeeet!

[sebgie]

Updated with references to implementation issues.

[jamlfy]

and while the implementation is done, as you can access the blog from the api?

[Jakobud]

What is the status of this? Are there instructions for logging in to your blog via OAuth in order to fetch posts?

[nilsborg]

Defo looking forward to this one!

[vickychijwani]

Hi, I'm working on a sweet little native Android app for Ghost. I love the design of the web client and am planning to bring the very same design focus to the Android app. Just wanted to chime in here to support this issue.

Right now I'm hacking around the problem by using the same token-based authentication mechanism used by the web client. I know that's not secure and requires the user to essentially trust me, but with the transparency of open-source and secure client-side credential storage I should be able to make it relatively safe. As soon as the OAuth API is released I'll switch to that, of course.

[jamlfy]

Hey!!! cool @vickychijwani

[sp90]

Can't wait for this update

[ErisDS]

We don't have planned release dates because we're dependent on volunteer contributions. All the information we have about the status of a project is published on the roadmap: https://trello.com/b/EceUgtCL/ghost-roadmap

We could really use a few more hands on deck to get projects like this moved forward, so if you're interested in helping out let us know.

[maxbook]

Hi @ErisDS, what is the status of this ? How i can help you ?

[maxbook]

@vickychijwani if you work on android app it's so cool ! And If you want we can work together , I was thinking of doing a iOS app.

[Huang-Libo]

什么时候能支持发布文章接口啊，我等的心好累。

[SophieDeBenedetto]

Hi,
Is there a time line for the release of the web and installed application registration? I would love to be able to programmatically access the API as I'm building out a Ruby gem to backup your ghost blog to a local postgres database.

[SophieDeBenedetto]

Thanks @Huang-Libo. Are you suggesting that b/c GH pages + Jekyll allows for version control and lots of backups? I'm not necessarily looking to switch away from Ghost--I really enjoy using the blogging platform. I'm just looking to build a quick and easy way to backup my Ghost blog. Currently when you export your blog you get a super long string of JSON so I was going to parse that and store database records.

[nuclearpengy]

@SophieDeBenedetto just set up a cronjob to export the MySQL DB and the contents of your images directory. Maybe include the theme if you're not already tracking the theme through Git or Mercurial.

[SophieDeBenedetto]

thanks @nuclearpengy. I should have been more clear--i'm using Ghost(Pro) so I don't think the db/file structure is accessible to me outside the Admin interface.

[nuclearpengy]

@SophieDeBenedetto if you're using Ghost(Pro) then backups are provided as part of the managed service.

[SophieDeBenedetto]

@nuclearpengy it's my understanding that the backup offered is a JSON download? I'm planning to parse and save to a pg database. was hoping to programmatically access my blogs posts, without having to visit admin panel and click "export".

[ErisDS]

I'm closing all OAuth and most API issues temporarily with the later label.

RE: OAuth, for the next 2-3 months we'll be implementing an official Ghost OAuth login system, providing global access to all Ghost blogs with a single login. We'll be opening issues around this system soon, and I don't want to cause confusion with OAuth for the API.

JSON API Overhaul & OAuth access are currently scheduled next on the roadmap

[aligajani]

@ErisDS So I can't POST to /posts to publish a new blog post using the API yet?