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)