Client management screen

[sebgie]

This belongs to the OAuth Epic: #4004 - please read this for the big picture of what this issue is for :)

---

To allow a user to manage the available clients it is necessary to provide a new screen (probably /settings/clients) that adds the following functionality:

• add a new client
• edit client name
• edit description (optional)
• edit trusted domains
• edit redirect uri
• edit status (development/enabled/disabled)
  • enabled: normal operation mode
  • disabled: client is suspended, can be reactivated
  • development: used to add special restrictions or allowances only used during development. Not needed for first version.
• edit client permissions (scope)
• edit logo
• read and refresh client_id
• read and refresh client_secret
• delete client

The client management interface will need some design guidance from @JohnONolan. Examples can be found here:

• https://my.slack.com/services
• https://twitter.com/settings/applications
• https://github.com/settings/applications

[JohnONolan]

@ErisDS @sebgie Is this the same as, or separate to the previous idea of "accounts" that we've been over. I think it might be different?

Example 1 (account):

I want to be able to auto-tweet when I publish a post. So I click a button and connect my twitter account to Ghost. Ghost now appears on the "apps" screen in twitter, and Ghost is authorised to post to my twitter stream via API.

Example 2 (this issue):

I want to use a desktop editor to publish to my Ghost blog. I click a button in the desktop editor and connect Ghost to my editor. The editor now appears on "this screen" in Ghost, and the editor is authorised to publish to my blog.

These things are the same but different - right? My question is this:

Is this 1 feature with a 2 way auth path? Or are these 2 feautures which live in different places and need different names? I feel like it should be the first, but I'm not sure.

[sebgie]

From my perspective theses are two different features. They both use the same authentication technology but offer different functionality for the user. For the accounts feature Ghost acts as an OAuth client and for the clients feature Ghost is the OAuth server. We could cluster the two features under one topic, but I would prefer having them in separate places with different names to avoid confusion.

OAuth
    Clients
    Accounts

[JohnONolan]

Sketch3 file - http://cl.ly/aY7e

[zinyando]

Hi all, @ErisDS and @taras have been talking over email about me taking on this feature. I am going to start to dig deeper and maybe start working on this feature.

@JohnONolan is the Sketch3 file above the final design?

[ErisDS]

Hi @zinyando, and welcome 😊
The design here is by no means final, it's more of a mockup, but for what we need from this feature it should be possible to use the standard list & form html & css that exists already in the code base, and we can do the final design as a last-pass.

As I mentioned to @taras, this needs a much clearer, slightly paired-back spec for a first version . There's also not an API endpoint to work from as yet so you'll need to work from dummy data. I'll post a new spec here towards the end of this week, hopefully in the meantime there's enough digging around to do looking at things like the labs flag system, as this feature will need to live behind the 'public API' flag for the time being.

[ErisDS]

@zinyando below is the spec for a first version. Probably need to play it a bit fast and loose with the finer details, but the core functionality should be correct.

---

Client management v1

Whenever Public API is enabled in labs, we need to show a new settings screen called 'connections' in the left hand Ghost menu. There is an icon-connections already present.

Client listings

This screen is roughly what's shown in #4177 (comment), but for now, this screen will only list clients, as there are no accounts yet.

The API for clients only has a read endpoint at the moment. The issue #4175 covers adding the endpoints for browsing, editing, adding, etc.

Clients will be fetched from the /client/ endpoint. It will work the same as the read endpoint, returning a {clients: []} object with multiple clients. The two default clients included with all ghost installs are ghost-admin and ghost-frontend and these two have special rules for the UI. In the database, neither of these have a logo or description - these will need to be faked via the UI in the first version, and we'll work on getting them added.

Edit functions

For each client, we need two buttons: one to enable/disable and one to refresh the client secret. Enable/disable will be sending an edit (PUT) request to change the status. Refreshing the client secret will be done, I think, by sending an edit (PUT) request with an empty secret and the server should handle repopulating it.

The ghost-admin client is an exception and cannot be disabled or have its secret refreshed. Need some way to make it clear in the list that this is a special client. ghost-frontend can be enabled/disabled and have it's secret refreshed.

Clicking on a client should take the user to a screen where the general values for that client can be edited. The two ghost-* clients are the exception to this rule - neither has any value which should be edited at this point.

Adding new clients

As with other screens in the admin (tags, team, etc) there should be a green button in the top right corner to add a new client. This should include the ability to set a name, a description, a logo, and one or more trusted domains. The slug/id will be generated from the name and the secret ought also to be auto-generated server-side. The type will default to 'ua' and the status will default to 'enabled'.

Whenever a custom client is edited, the same fields should be editable, including the ability to add/remove trusted domains.

I think, the adding and removing of multiple trusted domains will be the trickiest part from an ember perspective. I think the UI should, for now, borrow heavily from the navigation screen. A trusted domain is just a domain, e.g. blog.ghost.org or ghost.org - it doesn't have a protocol.

The api calls for adding/removing a trusted domain is very much up for discussion. I'm not sure what the most natural way to do it is from the ember perspective?

Hopefully this is enough information to get started. Happy to clarify anything 😄

[taras]

@ErisDS as we're preparing to add trusted domains interface, it became apparent that we don't really understand what it does. Can you describe what a trusted domain is? and how it's used?

[ErisDS]

Clients are things which are allowed to access the API. Trusted domains are the domains (urls) from which these clients are allowed to make requests. All clients automatically get granted permission to make requests from the domain set as the url in config.js, but it's quite common to want to make requests from other domains as well.

The most obvious example is that on blog.ghost.org, we have ghost.org as a trusted domain for the ghost-frontend client. That way when you're logged into Ghost.org, we can show you the latest post from our blog because we're allowed to use the ghost-frontend client to make ajax requests from ghost.org to blog.ghost.org.

Trusted domains are linked to clients through the client_trusted_domains table/model/etc. A trusted domain is therefore made up of just a client_id and a domain. A domain in this case is the hostname part of a URL, so "ghost.org" not "http://ghost.org/" etc.

[taras]

Perfect. Thank you

[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