search

hypothesis / vision

Envisioning the future of the Hypothesis.
https://github.com/hypothesis/vision/issues/
40 stars 8 forks source link

As a developer, I want to build annotation apps that can publish into hypothes.is storage #182

Open BigBlueHat opened 9 years ago

BigBlueHat commented 9 years ago

@tilgovi what do I need to do that? :smile:

Relates a bit to #181.

dwhly commented 9 years ago

Love this.

judell commented 9 years ago

https://hypothes.is/api offers CRUD services. If that's not what you're looking for, can you redo this to clarify? Thanks!

dwhly commented 9 years ago

Perhaps its how do I approve my app so that it can publish like this?

BigBlueHat commented 9 years ago

@judell yeah, currently it's essentially read-only (afaik) to any app but our own. @tilgovi and I have discussed doing this in the past--and the related token / security setup needs to make it a Real Thing. This is mostly just to track that.

@dwhly not sure what you mean by "how do I approve my app" unless it's related to authentication / authorization flow.

Ideally, it feels a bit like OAuth 2.0 flow of "Do you authorize Awesomesauce Annotator to publish to Hypothes.is on your behalf?" with "Agree" / "Deny" buttons--like how you do it with the GitHubz. :wink:

Long term I'd love to see us support some other flows for doing this (remoteStorage.js, LDP + WebIDAuth), but let's start small. :smile_cat:

tilgovi commented 9 years ago

From a code perspective, a lot of this is "close". What would be needed is storage and lookup for access tokens and a bit of glue for the un-implemented flows of OAuthLib.

Technically, though, our current authorization of client to API server is OAuth using a JWT Bearer Token as an authorization grant. We should be able to implement other flows with relative ease thanks to OAuthLib and the pyramid-oauthlib glue I wrote.

BigBlueHat commented 9 years ago

@tilgovi could you drop some tasks here to explain some next steps? We can turn them into cards after that.

Might help us get this from your head into ours. :grinning:

tilgovi commented 9 years ago

This issue should be clarified to discuss one of the following two use cases:

I'm going to speak only about the first for now. I will refer to our API Server (/api) and our Account Server (/login, /register, etc).

Right now our API Server and our Account Server share one set of client credentials provided by an .ini file. We're still using a bit of legacy code here, but as of last week our API Server supports JWT Bearer Tokens as authorization grants, for which there's a reasonable spec. Our client-side application obtains a JWT from the Account Server and then exchanges it for an access token with the API Server. (Aside: right now both tokens are JWTs, but there's no reason that has to be the case and switching to smaller, opaque access tokens would reduce the payload on API requests.)

Our API Server knows nothing about accounts. It accepts an identity token signed by a valid issuer (currently only one, from the .ini file) and provides an access token in response, associated with a tuple of (user, issuer). Our database searches are segmented on issuer, so we can in theory have multiple sandboxes for annotations belonging to the users of different services (the use case I'm leaving out for now).

I have a feeling that the API Server should, at its core, stay pretty stupid. Right now, since its access tokens are JWTs, it can validate these with the known credentials in an otherwise stateless fashion. It would be wise for us to stop assuming this and start storing bearer tokens.

However, I'd like to keep client credentials out of the API Server as much as possible. For the 3rd-party application consuming Hypothesis users scenario, our Account Server is still the only valid issuer. No credential storage required. In order to authorize third party applications, though, our Account Server does need to be able to issue and store client credentials.

Here's what I think we need for the API Server:

Here's what I think we need for the Account Server:

I have more thoughts about the use case of BYO-users, but let's clarify this issue to be only about the other and discuss that separately.

BigBlueHat commented 9 years ago

:+1: to keeping this focused on the Hypothes.is user + "other" application use-case.

I'm making issues for each of those bullet points (on h), and connecting them here. Hope that's helpful.

judell commented 9 years ago

A lot of moving parts, all needed in the long run. Shorter-term, can we provide early-adopters/tirekickers with long-lived tokens they can pass on the URL-line, to make experimentation frictionless?

tilgovi commented 9 years ago

I don't think any part of this is actually that complicated and the groundwork is there. If we want to do it let's just talk next week about the cost.

judell commented 9 years ago

OK. To be clear I'm looking for a way to simplify experimentation with the API. Even just name+pw over https as a starter. It's early days and we need a low activation threshold to ensure interested devs can tirekick and give feedback.

BigBlueHat commented 9 years ago

:+1: for HTTP Basic Auth over https...for now.

In the past we've run up against the "but we're gonna change the API...so don't tell people to use it." Let's just declare it as "experimental" / "highly subject to change" (in a blog post, etc), and work harder (/me volunteers) to craft a more dependable API deliverable (alongside our W3C work) to get this ready for production consumption.

Sound like a plan? :smiley:

My personal user story:

As a developer advocate, I want stuff to give to developers, so that they can develop.

:smile_cat: