Help needed for API endpoints

[ovidius72]

Can you please help me to clarify what is the corresponding API endpoint of the following hydra command:

$ docker exec -it `docker ps -f name=hydra_hydra_1 -q` \
    hydra token client \
    --endpoint http://localhost:4444 \
    --client-id my-client \
    --client-secret secret

I'm following the 5 minutes tutorial but instead of using the cli I'm trying to create a client using postman, just to understand what are the corresponding endpoints and how to use them.
Hydra is running in the docker container.
Did a POST to /clients and the client was register correctly.
Then I want to perform the client credentials grant as stated in that tutorial.
I've tried using a POST to /oauth2/token with no luck.
With this payload:

{
	"client-id": "one",
	"client-secret": "secret",
	"grant-type": "authorization_code"
}

I get this responde:

{
    "error": "invalid_request",
    "error_description": "The request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed",
    "error_hint": "The POST body can not be empty.",
    "status_code": 400
}

I apologize if I'm doing things wrong, I'm trying to learn how oAuth2 works and eventually use hydra in the future.
thanks

[aeneasr]

API endpoints are documented here: https://www.ory.sh/docs/hydra/sdk/api

[ovidius72]

Well, obviously I already read the API documentation page. I was looking for help because the response in not what one expects. The documentation about the /oauth2/token endpoint doesn't provide much information about that.

[aeneasr]

/oauth2/token is not an endpoint where you create clients. If you want to interact with OAuth2 I suggest to use a library like simple-oauth2 (or similar for other languages). You can also find more debug info in the hydra logs. If the error says The POST body can not be empty. you're probably sending some unsupported payload (e.g. xml, json) which indicates that you're not using an appropriate library.

[jredville]

I just spent an hour debugging this because I'm trying to put Hydra behind a proxy that is converting form parameters to json, would it be possible to update the api docs to point out that this endpoint only accepts form params? I understand that a client library should do this automatically, but it would be helpful to have that documented for people trying to debug like myself

[aeneasr]

That's unfortunate! I also just noticed that the documentation is only showing the Accept/response header but not the request type. Reopening to track and fix this.

However, a proxy that's doing such a conversion should probably not do that per default. I don't think that any documentation on this can help you debug such a network chain when one thing isn't doing what it's supposed to be doing. That doesn't imply that the docs shouldn't be improved though here!

[jredville]

Thanks for the reply. I do agree that the proxy shouldn't be doing that and I'm going to open an issue on them as well (fastify-reply-from). In the meantime finding this issue finally helped me figure it out so I could override the proxy.

The headers on that page would have definitely helped, so I appreciate that.

[aeneasr]

Hm, I just checked, the swagger definition properly defines the consume/produce part:

// swagger:route POST /oauth2/token public oauthToken
//
// The OAuth 2.0 token endpoint
//
// This endpoint is not documented here because you should never use your own implementation to perform OAuth2 flows.
// OAuth2 is a very popular protocol and a library for your programming language will exists.
//
// To learn more about this flow please refer to the specification: https://tools.ietf.org/html/rfc6749
//
//     Consumes:
//     - application/x-www-form-urlencoded
//
//     Produces:
//     - application/json
//
//     Schemes: http, https
//
//     Security:
//       basic:
//       oauth2:
//
//     Responses:
//       200: oauthTokenResponse
//       401: genericError
//       500: genericError

Which is being translated to (swagger json):

    "/oauth2/token": {
      "post": {
        "security": [
          {
            "basic": []
          },
          {
            "oauth2": []
          }
        ],
        "description": "This endpoint is not documented here because you should never use your own implementation to perform OAuth2 flows.\nOAuth2 is a very popular protocol and a library for your programming language will exists.\n\nTo learn more about this flow please refer to the specification: https://tools.ietf.org/html/rfc6749",
        "consumes": [
          "application/x-www-form-urlencoded"
        ],
        "produces": [
          "application/json"
        ],
        "schemes": [
          "http",
          "https"
        ],
        "tags": [
          "public"
        ],

So this might be an issue with the documentation template.

[aeneasr]

This seems to be an upstream bug: Mermade/widdershins#216

[githugt]

Just want to add that, I faced the same issue, and for me, the problem was that I was sending the request with application/json as the request body type. It is not that. It has to be application/x-www-form-urlencoded

Here's a curl request which worked for me.

curl --location --request POST 'http://127.0.0.1:9000/oauth2/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_id=someconsumer' \
--data-urlencode 'client_secret=somesecret' \
--data-urlencode 'scope=offline_access offline openid additional_example_scope

The client for this was set as

curl --location --request POST 'http://127.0.0.1:9001/clients' \
--header 'Content-Type: application/json' \
--data-raw '{
  "client_id": "someconsumer",
  "client_name": "consumerName",
  "client_secret": "somesecret",
  "client_uri":"example.com",
  "owner":"example.com",
  "grant_types": [
    "client_credentials"
  ],
  "scope":"additional_example_scope offline_access offline openid",
  "redirect_uris": [
    "http://example.com"
  ],
  "response_types": [
    "token",
    "code"
  ],
  "token_endpoint_auth_method":"client_secret_post"
}'

Note that you can set the credentials as basic auth header as well by setting "token_endpoint_auth_method":"client_secret_basic".

For more info: refer to this page.

[devshrm]

Thanks @githugt , this is working. But where in docs is request params are mentioned of /oauth/token

https://www.ory.sh/docs/hydra/reference/api#tag/oAuth2/operation/oauth2TokenExchange looks like this is not correct.