Documentation improvements and bundle configuration about oauth2-server-bundle HOT 7 CLOSED

@tgalopin we do have documentation here on many of the questions you've asked. The main way would be to build a new class implementing OAuth2\Storage\UserCredentialsInterface. You can then overload the checkUserCredentials method to call the external service. No password necessary!

Does this answer your question?

from oauth2-server-bundle.

Thanks for your answer!

I succeed to set it up, however I had some problems with the documentation (the one you provided), so I had to learn by reading the code :) .

I didn't do it well I suppose, I will try using this interface.

The documentation is great but not complete IMHO. It's great for typical use case, but not so well for specific cases such as mine.

from oauth2-server-bundle.

I feel that documentation is very important to any successful library. Where do you think the areas of improvement need to be? Would you like to see better code-examples and maybe more fully-fleshed out cookbook articles (like this one) ?

from oauth2-server-bundle.

I agree with you, a good documentation is required for any successful project.

IMHO, this cookbook is typically the one I don't want to read. It explains steps by steps how to install a classic version of an OAuth server, by giving SQL requests and code pretty much directly. Explainations and concepts are why a documentation is important. A bunch of code is not really a doc.

What I wanted to see in such a doc is some explainations about concepts from the library : which class is used for what, why do we do this thing. In that case, I could adapt the explainations to my specific case and have a really good use of it.

I'm not saying the doc is bad, not at all. Just that it could be improved by adding more text and remove some code.

I solved my problem so now I know a bit the library. I know how hard it is to write good doc as a developper. If you want, I can review it a bit, to help you to improve it.

from oauth2-server-bundle.

This is great feedback, thank you. Yes, please continue to provide feedback!

from oauth2-server-bundle.

Okay, let's explain a bit more my thoughts then :) .

The main idea of the bundle is to provide a simple way to implement an OAuth server in a Symfony project. IMO, in a documentation for such a bundle you should explain things in this order:

Overview

How the bundle works, in a very theorical way. No code, no examples, just text and images. A really great way to explain things theorically are schemas: a well designed schema is much easier to understand than a big block of text.

Personnally, I would explain concepts like:

• Storages
• Server
• Request
• Grant types
• Token
• Scopes

It's very important for developpers to understand your library more than to know how to use it.

The demo application here is not interesting: as a developper, I don't want an example, I want an understanding.

Get started

The Get started zone have to be after the explainations of the concepts. It uses these concepts to implement a very simple sample application of your library. IMO, the best way to implement such a sample is to use the client_credentials grant type, as you used it in your doc.

That's where you explain line by line what you do: you only have few lines of code, let's explain them a lot!

Authorization code

A complete chapter for authorization code is IMO important as it's the most used grant_type and why OAuth is famous.

Scopes

Explain how to introduce scopes to your sample app.

I know your already explain these things in your doc. The main problem about the way it's currently done is the organization. You have to search for things after in the documentation when reading to understand all.

IMO, you should cut your documentation in three parts, a bit like the symfony doc. Currently, these parts are mixed and that introduce confusion.

1. The book (the main documentation) ;
2. The cookbooks (you already did them and it's a good idea) ;
3. The reference (the list of storages, grant types, ...) ;

from oauth2-server-bundle.

Hi @bshaffer,

I completely agree with @tgalopin. No offence, but the documentation is not on the very best level. In one of your posts above a link was provided to the docs of the OAuth2 php library, however the configuration is quite different for the OAuth2 Server bundle for Symfony.

The configuration steps of oauth2-server-bundle (Symfony) were followed as described in the documentation and failed. The token endpoint for example fails. Was the documentation tested after it was written ?

Could you provide examples how to test endpoints immediately at the end of the configuration steps ? Some of the devs have servers on the intrAnet, the servers are not exposed outside. Therefore it is not possible to use Google Playground.

I think it would be great if you could provide an example of configuration which works out of the box. Afterwards for all the customizations there should be a note on how to do it.

Where optional parameters are specified in the commands e.g. php app/console OAuth2:CreateClient client_id redirect_uri (grant_types) (scope) the values for the optional arguments such as grant_types and scope should be provided or at least info where these predefined values can be found.

What I find missing is the explanation of scope. Is it mandatory, which values can it have, for which use case those values should be used, ...

What could also be a further improvement is documenting how the OAuth client e.g. HWIOAuthBundle could be configured to interact with the OAuth2 Server.

from oauth2-server-bundle.