[bash] OAuth2 authentication method documentation

[col-panic]

Description

The documentation concerning oauth2 documentation is not clear.

Swagger-codegen version

2.2.3

Suggest a fix/enhancement

Running swagger-codegen and the resulting tool leaves an output like

Authentication methods

  - Api-key - add 'api_key:<api-key>' after <operation>
              or export PETSTORE_API_KEY='<api-key>'
  - OAuth2 (flow: implicit)
      Authorization URL:
        * http://petstore.swagger.io/oauth/dialog
      Scopes:
        * write:pets - modify pets in your account
        * read:pets - read your pets

which does not help me understand on how to use the OAuth2 authentication method in order to call the resp. operations. I do still not know wether its possible or not, and if how, to configure and use the OAuth2 authentication with the bash client.

Please enhance documentation, even by (if applicable) saying that there is no intrinsic generated way to handle it or something like this!

[col-panic]

Sorry, I did not mean this ticket! This ticket is still not fixed! I was referring to another error, but I could not delete the comment, so please re-open this ticket!

[wing328]

cc @frol (2017/07) @bkryza (2017/08) @kenjones-cisco (2017/09)

[frol]

Implicit OAuth2 Flow is designed for Web browsers (RFC 6279 section 4.2):

The implicit grant type is used to obtain access tokens (it does not support the issuance of refresh tokens) and is optimized for public clients known to operate a particular redirection URI. These clients are typically implemented in a browser using a scripting language such as JavaScript.

Since this is a redirection-based flow, the client must be capable of interacting with the resource owner's user-agent (typically a web browser) and capable of receiving incoming requests (via redirection) from the authorization server.

Thus, while it is possible to hook a console-based browsers here, it is not the most straightforward way.

[bkryza]

@col-panic

You're right - OAuth2 is not supported at the moment in Bash automatically (the documentation just prints out the service OAuth2 endpoint)

I don't have much experience with OAuth2 but I thinkg you could try this:

curl -X POST -d "<OAUTH2_TOKEN_REQUEST_PARAMS>" http://petstore.swagger.io/oauth/dialog

which should return a JSON including a bearer token, then you should be able to call any endpoint in such service by adding the authorization header using cURL:

petstore-rest-cli -H "Authorization: Bearer $TOKEN" ...

I will try to add an option for that but I will need to find or setup some actual OAuth2 service to test it...

If you have already such setup and you could test the steps above that would definitely help.

[col-panic]

I have such a setup, I will try to fix some curl scripts! :)

[col-panic]

Client Authentication Flow

Let's first fix an example for the most basic flow - client authentication flow.

We only need the tokenUrl, a clientId, a clientSecret and a (set of) scope(s)

Executing the following request for example

curl -H "Content-Type: application/x-www-form-urlencoded" -X POST "https://localhost:8480/login/oauth/token?
grant_type=client_credentials&client_secret=d284c410-d3a7-3861-baad-
b27a327e2ed3&client_id=Unit-Test-Client-AdminScope&scope=esadmin"

returns (in case of success) the following JSON object

{"access_token":"18fd81dc-df54-306e-b890-c0f1776e7b15","expires_in":3600}

This access_token out of this JSON result has to be passed in subsequent requests as a header Bearer token.

I was unsuccessfull in embedding this token with the generated bash script, although there seems to be support for it, but a call e.g. doing

./client.sh --host http://localhost:8380 getStatusPlaintext Authentication:"Bearer be4810dd-8c43-371b-93ba-2c467e7c3968"

does not work out, the header does not seem to be set. (I verified by using http://httpbin/anything as a destination inspecting the generated echo)

The following example works:

./client.sh -H "Authorization: Bearer 18fd81dc-df54-306e-b890-c0f1776e7b15" --host http://localhost:8380 getStatusPlaintext

[bkryza]

@col-panic

Ok thanks for this test - my proposition would be to assume for now that the user has the bearer token obtained outside of the generated Bash client and can simply provide it using a special option allowing to pass just the bearer token e.g. --oauth2-token <TOKEN> which will add the appropriate header automatically...

[col-panic]

I find this a very good first step - at least it will be documented and users will know how to use it!
Probably the option could be more generalized calling it --bearer-token? What is the respective syntax used for apikey?

I would also target support for easy authentication using the client resource and resource owner password flow. E.g. by providing a resp. login function that will then automagically add the returned access_token to the subsequent function calls.