New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

OAuth continued - Open the JSON API via OAuth #4004

Closed
sebgie opened this Issue Sep 10, 2014 · 21 comments

Comments

Projects
None yet
@sebgie
Copy link
Contributor

sebgie commented Sep 10, 2014

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

Bonus:

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

@sebgie sebgie added the epic label Sep 10, 2014

@sebgie sebgie added this to the Future Backlog milestone Sep 10, 2014

@novaugust

This comment has been minimized.

Copy link
Member

novaugust commented Sep 10, 2014

Sa-weeeeet!

@sebgie

This comment has been minimized.

Copy link
Contributor

sebgie commented Sep 26, 2014

Updated with references to implementation issues.

@alejonext

This comment has been minimized.

Copy link

alejonext commented Dec 5, 2014

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

@sebgie sebgie referenced this issue Dec 6, 2014

Closed

Ghost API Bug #4593

@Jakobud

This comment has been minimized.

Copy link

Jakobud commented Feb 3, 2015

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

@vickychijwani vickychijwani referenced this issue Feb 16, 2015

Closed

Login workflow #1

5 of 5 tasks complete
@nilsborg

This comment has been minimized.

Copy link

nilsborg commented Mar 11, 2015

Defo looking forward to this one!

@vickychijwani

This comment has been minimized.

Copy link
Member

vickychijwani commented Apr 1, 2015

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.

@alejonext

This comment has been minimized.

Copy link

alejonext commented Apr 2, 2015

Hey!!! cool @vickychijwani

@sp90

This comment has been minimized.

Copy link

sp90 commented Apr 16, 2015

Can't wait for this update

@awrelll

This comment has been minimized.

Copy link

awrelll commented Apr 24, 2015

Is there a timelapse for this release ? At least is it going to be released in the near future ?
Thanks to all the devs that are putting this together! 👍

@ErisDS

This comment has been minimized.

Copy link
Member

ErisDS commented Apr 27, 2015

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.

ErisDS added a commit to ErisDS/Ghost that referenced this issue Jun 28, 2015

Add public API endpoint handling
refs TryGhost#4004

- added new public permission handling functions to permissions
- updated posts, tags and users endpoints to handle public permissions or normal permissions
- added test coverage for the new code

ErisDS added a commit to ErisDS/Ghost that referenced this issue Jun 29, 2015

Add public API permission handling
refs TryGhost#4004

- added new public permission handling functions to permissions
- updated posts, tags and users endpoints to handle public permissions or normal permissions
- added test coverage for the new code

@ErisDS ErisDS referenced this issue Jun 30, 2015

Closed

Ghost 0.7 Overview #5503

13 of 31 tasks complete

ErisDS added a commit to ErisDS/Ghost that referenced this issue Jul 28, 2015

Add public API permission handling
refs TryGhost#4004

- added new public permission handling functions to permissions
- updated posts, tags and users endpoints to handle public permissions or normal permissions
- added test coverage for the new code

ErisDS added a commit to ErisDS/Ghost that referenced this issue Jul 28, 2015

Add public API permission handling
refs TryGhost#4004

- added new public permission handling functions to permissions
- updated posts, tags and users endpoints to handle public permissions or normal permissions
- added test coverage for the new code

ErisDS added a commit to ErisDS/Ghost that referenced this issue Jul 29, 2015

Add public API permission handling
refs TryGhost#4004

- added new public permission handling functions to permissions
- updated posts, tags and users endpoints to handle public permissions or normal permissions
- added test coverage for the new code

ErisDS added a commit that referenced this issue Jul 29, 2015

Add public API permission handling
refs #4004, #5614

- added new public permission handling functions to permissions
- updated posts, tags and users endpoints to handle public permissions or normal permissions
- added test coverage for the new code

ErisDS added a commit to ErisDS/Ghost that referenced this issue Aug 3, 2015

Add public API permission handling
refs TryGhost#4004, TryGhost#5614

- added new public permission handling functions to permissions
- added a new util to handle either public permissions or normal permissions
- updated posts, tags and users endpoints to use the new util
- added test coverage for the new code

@ErisDS ErisDS modified the milestone: Future Backlog Oct 9, 2015

@maxbook

This comment has been minimized.

Copy link

maxbook commented Oct 16, 2015

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

@maxbook

This comment has been minimized.

Copy link

maxbook commented Oct 16, 2015

@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.

@ErisDS ErisDS referenced this issue Oct 20, 2015

Closed

Public API v1 Sprint Epic #5976

24 of 24 tasks complete
@Huang-Libo

This comment has been minimized.

Copy link

Huang-Libo commented Feb 14, 2016

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

@SophieDeBenedetto

This comment has been minimized.

Copy link

SophieDeBenedetto commented Sep 16, 2016

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

This comment has been minimized.

Copy link

SophieDeBenedetto commented Sep 16, 2016

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

This comment has been minimized.

Copy link

nuclearpengy commented Sep 16, 2016

@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

This comment has been minimized.

Copy link

SophieDeBenedetto commented Sep 16, 2016

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

This comment has been minimized.

Copy link

nuclearpengy commented Sep 16, 2016

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

@SophieDeBenedetto

This comment has been minimized.

Copy link

SophieDeBenedetto commented Sep 17, 2016

@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 ErisDS added the later label Sep 20, 2016

@ErisDS

This comment has been minimized.

Copy link
Member

ErisDS commented Sep 20, 2016

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

@ErisDS ErisDS closed this Sep 20, 2016

@aligajani

This comment has been minimized.

Copy link

aligajani commented Feb 14, 2017

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment