Skip to content
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
Closed

OAuth continued - Open the JSON API via OAuth #4004

sebgie opened this issue Sep 10, 2014 · 21 comments
Labels

Comments

@sebgie
Copy link
Contributor

@sebgie 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
Copy link
Contributor

@novaugust novaugust commented Sep 10, 2014

Sa-weeeeet!

@sebgie
Copy link
Contributor Author

@sebgie sebgie commented Sep 26, 2014

Updated with references to implementation issues.

@alejonext
Copy link

@alejonext alejonext commented Dec 5, 2014

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

@sebgie sebgie mentioned this issue Dec 6, 2014
@Jakobud
Copy link

@Jakobud 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?

@nilsborg
Copy link

@nilsborg nilsborg commented Mar 11, 2015

Defo looking forward to this one!

@vickychijwani
Copy link
Member

@vickychijwani 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
Copy link

@alejonext alejonext commented Apr 2, 2015

Hey!!! cool @vickychijwani

@sp90
Copy link

@sp90 sp90 commented Apr 16, 2015

Can't wait for this update

@ErisDS
Copy link
Member

@ErisDS 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 ErisDS mentioned this issue Jun 30, 2015
13 of 31 tasks complete
ErisDS added a commit to ErisDS/Ghost that referenced this issue Aug 3, 2015
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
Copy link

@maxbook maxbook commented Oct 16, 2015

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

@maxbook
Copy link

@maxbook 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 mentioned this issue Oct 20, 2015
24 of 24 tasks complete
@Huang-Libo
Copy link

@Huang-Libo Huang-Libo commented Feb 14, 2016

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

@SophieDeBenedetto
Copy link

@SophieDeBenedetto 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
Copy link

@SophieDeBenedetto 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
Copy link

@nuclearpengy 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
Copy link

@SophieDeBenedetto 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
Copy link

@nuclearpengy nuclearpengy commented Sep 16, 2016

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

@SophieDeBenedetto
Copy link

@SophieDeBenedetto 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
Copy link
Member

@ErisDS 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
Copy link

@aligajani aligajani commented Feb 14, 2017

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

@ErisDS ErisDS removed later labels Jan 23, 2019
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Projects
None yet
Linked pull requests

Successfully merging a pull request may close this issue.

None yet