Create documentation / samples for OAuth2

[stablekernel]

Create documentation / samples for OAuth2

[joeconwaystk]

Will have some docs soon. In the meantime, creating a new project from the template (aqueduct create -n ...) will hook up auth endpoints and can serve as an example. You can view the template code in examples/default.

[wstrange]

Thanks - looking forward to the docs!

I have the sample project setup, and I can see the auth endpoints. It is just not clear how they work.

I gather this is meant to integrate with an external OAuth2 provider? How would that work? Is there any way of providing authz based on OAuth2 scopes?

[joeconwaystk]

The endpoints work with an AuthServer instance (not a remote server, a Dart object). AuthServer instance does the logic of creating and validating tokens and such, but has a AuthServerDelegate to carry out any persistence. In the template code, that delegate is implemented to use the built-in ORM (utilities/auth_delegate.dart). So, tokens are stored in PostgreSQL is the tl;dr.

Authorizers are RequestControllers that validate an HTTP request with an AuthServer.

[wstrange]

OK - if I grok this correctly, the client has to get an access token by posting credentials to /auth/token, or to /auth/code and then exchanging the code for a token.

The sample app looks like it needs to be "bootstrapped" with some credentials in the database in order to be able to create users by invoking /register (which is itself protected with OAuth 2)

[joeconwaystk]

This is correct; the OAuth 2.0 flows for resource owner, application and authorization code are supported. You'll need to insert AuthClients (Client ID/Secret) in a database - this isn't in the sample code because the secret shouldn't be in version control, but does need to be better documented. The secret is hashed with a salt before it is stored in the DB. The method AuthServer.generateAPICredentialPair will generate a salt and hash in the same way the AuthServer will, so I typically create a script that takes an ID/secret and calls that method.

The test harness in the example project will create a dummy ID/secret for the purposes of running the test. I believe it is com.stablekernel.test/kilimanjaro - but it doesn't really matter, because the TestClient already has that value stored as its default API credentials.

[joeconwaystk]

Moving this into a more consolidated issue #114