ESA and torii GitHub guide #1142

Merged
merged 13 commits into from Dec 21, 2016

Projects

None yet

2 participants

@srvance
Contributor
srvance commented Dec 18, 2016

I've written a guide that takes you step by step through the process of authorizing your app to use the GitHub APIs. This is a complete first draft.

I plan to add a diagram of the OAuth2 explicit grant flow, but the guide is large enough that I wanted to give you reading time.

Note that the "Useful Links" section at the end contains a link to a repo on my account with the source that follows the guide. If you want to move that under the project or into a simplabs repo, I'm open for that.

@srvance srvance referenced this pull request in hawkup/github-stars Dec 18, 2016
Open

[emberjs, angularjs] Starred query not authenticated #6

@marcoow

This is awesome! Thanks for the effort - guides like this will certainly help making Ember Simple Auth more approachable. I left some comments on a few minor things but overall this is pretty great!

guides/auth-torii-with-github.md
+
+Once you register your application, you will have a chance to add an application logo.
+Most importantly, you will be given a client ID and a client secret. _The client secret is
+a password and should be protected as such!_ You will use the client ID in your web
@marcoow
marcoow Dec 19, 2016 Member

Not sure whether the term "password" might cause confusion here. Maybe we can say something like "The client secret must be kept secret and must never be included e.g. in the Ember application's source" or so?

@srvance
srvance Dec 19, 2016 Contributor

Done

guides/auth-torii-with-github.md
+{{outlet}}
+```
+
+The `session` service is automatically injected, so there's no code for that. We'll add the `config` entry for now to
@marcoow
marcoow Dec 19, 2016 Member

Auto-injection might actually be removed with ESA 2.0. We should show how to inject the service in the application controller here.

@srvance
srvance Dec 19, 2016 Contributor

Should we change it now or when that change takes place? Why remove injection?

@marcoow
marcoow Dec 20, 2016 Member

I would change it now already so that people get used to explicitly inject the service instead of relying on the auto-injection. The advantage of explicit injection (session: Ember.inject.service) is simply that it's easier to follow and less magic.

@srvance
srvance Dec 20, 2016 Contributor

Makes sense. I had some confusion about where it was auto-injected and where it wasn't. I've gone back to the initializers a couple of times to refresh that memory.

guides/auth-torii-with-github.md
+
+If you're still running the app when you save this, you will see it redirect to the `login` route.
+
+We'll also designate the `login` route as available for unauthenticated access by applying the
@marcoow
marcoow Dec 19, 2016 Member

This should maybe read "for unauthenticated access only" as that's really the point of the mixin - making sure authenticated users can not access it.

@srvance
srvance Dec 19, 2016 Contributor

Do you want the emphasis on "only" in the guide or did you include it to point the difference out to me?

guides/auth-torii-with-github.md
+```handlebars
+{{!-- app/templates/login.hbs --}}
+
+<button {{action "login"}}>Log in to GitHub</button>
@marcoow
marcoow Dec 19, 2016 Member

We should use modern action in this guide, helping make people familiar with modern/idiomatic Ember concepts, so this would be:

<button onclick={{action "login"}}>Log in to GitHub</button>

and the above implementation of the action would go to the controller.

@srvance
srvance Dec 19, 2016 Contributor

Done.

@srvance
srvance Dec 19, 2016 Contributor

I'll have to redo the history in the demo app if we want to include it.

guides/auth-torii-with-github.md
+```handlebars
+{{!-- add to app/templates/application.hbs --}}
+
+ <button {{action "logout"}}>Log Out</button>
@marcoow
marcoow Dec 19, 2016 Member

See above - we should be using modern closure actions:

<button onclick={{action "logout"}}>Log Out</button>
@srvance
srvance Dec 19, 2016 Contributor

Done.

guides/auth-torii-with-github.md
+### Obtaining an Access Token
+
+The final step in the process is to exchange your authorization code for an API access token. This can only be done
+securely through a back end service because it needs to know your application password. Right now, our app looks like
@marcoow
marcoow Dec 19, 2016 Member

I think we should use the correct term "Client Secret" here instead of "application password".

@srvance
srvance Dec 19, 2016 Contributor

Agreed.

guides/auth-torii-with-github.md
+ req.write(data);
+ req.end();
+};
+```
@marcoow
marcoow Dec 19, 2016 Member

It might make sense to show how to do this with Ember CLI's mock server for the development environment as well.

@srvance
srvance Dec 19, 2016 Contributor

Done. The changes are committed to the demo app, but we should re-create the history if we want to officially use it. I structured the app so each commit corresponds to the section of the guide.

@marcoow

Awesome! Left some comments on minor things and I think this should be good to merge once those things are solved.

+GitHub application, an unauthenticated login route, an authenticated content route, a
+token exchange service, and use of an authorizer to inject the token into
+requests. We'll use the [ember-data-github](https://github.com/elwayman02/ember-data-github)
+addon so we don't need to create our own GitHub models, serializers, and adapters.
@marcoow
marcoow Dec 20, 2016 Member

I think it would be good to briefly explain that the general concepts are the same for any other OAuth 2.0 provider (Facebook, Google etc.). Otherwise people who try to use one of those providers might feel that this wouldn't help them while it actually would. Maybe we could even rename the whole guide to "Implementing the OAuth 2.0 Authorization Code Grant Type with Ember Simple Auth and torii" or so and simply explain in the guide that github is only used as an example.

@srvance
srvance Dec 20, 2016 Contributor

Done.

guides/auth-torii-with-github.md
+While most of the pieces are documented in the `ember-simple-auth` and `torii`
+documentation, putting them together properly for the particular scenario has not been
+fully documented to date. Additionally, many of the sources on the general internet are
+helpful but dated or incomplete.
@marcoow
marcoow Dec 20, 2016 Member

I'm not sure it's necessary to explain the motivation for this guide here as with the release of this the problem that's being described doesn't exist anymore so the paragraph isn't actually relevant anymore ;)

@srvance
srvance Dec 20, 2016 Contributor

Removed.

guides/auth-torii-with-github.md
+ CLIENT_ID: '<YOUR CLIENT ID>',
+ CLIENT_SECRET: '<YOUR CLIENT SECRET>',
+ USER_AGENT: '<YOUR APPLICATION NAME>'
+};
@marcoow
marcoow Dec 20, 2016 Member

Couldn't these be read from the .env file as well? With this you end up duplicating these settings.

@srvance
srvance Dec 20, 2016 Contributor

They could, but I see the server as a separate application and wanted to keep them in that scope. The only duplicated setting is the CLIENT_ID. The Ember app should NOT have access to the CLIENT_SECRET as a security precaution.

@marcoow
marcoow Dec 21, 2016 Member

Hm, I see what you mean but you would actually want to keep these settings in env vars also when running the server in production (think of when you're running it in a container) so the general concept of env vars makes a lot of sense for the server part in particular. Maybe it would work to use 2 separate env vars?

guides/auth-torii-with-github.md
+ENV.torii.providers['github-oauth2'].tokenExchangeUri = process.env.DEV_TOKEN_EXCHANGE_URL;
+```
+
+Now that we've set up a token exchange service, let's use it. Replace your `torii` adapter with
@marcoow
marcoow Dec 20, 2016 Member

Replace your torii adapter

This should be "Replace your torii authenticator"

@srvance
srvance Dec 20, 2016 Contributor

Done.

guides/auth-torii-with-github.md
+});
+```
+
+This makes a `POST` request to your service and gives the response back to Torii. Notice that it returns the `access_token`
@marcoow
marcoow Dec 20, 2016 Member

gives the response back to Torii

That's not really what happens. Instead it gets the authorization code from torii (via _super) and exchanges that for an access token via the API service. torii is actually done and never called again when the promise returned from _super resolves.

@srvance
srvance Dec 20, 2016 Contributor

Changed "Torii" to "Ember Simple Auth"

@srvance
Contributor
srvance commented Dec 21, 2016
@marcoow marcoow added this to the 1.2 milestone Dec 21, 2016
@srvance
Contributor
srvance commented Dec 21, 2016

The server only uses the .env from the project root. You can't add your own at the server root with the current functionality of ember-cli-dotenv. I can leave settings as is or move them to .env with additional explanation about what a production configuration should look like. Do you have a preference or another option you like better?

@marcoow
Member
marcoow commented Dec 21, 2016

I'd prefer keeping everything in .env actually as that's going to result in more production-like code for the server where you'd get these values from env vars as well.

@srvance
Contributor
srvance commented Dec 21, 2016

Done!

@marcoow
Member
marcoow commented Dec 21, 2016

awsome! 🎉

@marcoow marcoow merged commit 7935e2a into simplabs:master Dec 21, 2016

1 check passed

continuous-integration/travis-ci/pr The Travis CI build passed
Details
@srvance
Contributor
srvance commented Dec 21, 2016

🎉
What are your thoughts about the demo app?

@marcoow
Member
marcoow commented Dec 22, 2016

I'm fine with the demo app staying under your account - credit where credit is due!

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