Home Wiki

Access Token

Access token generation is provided via the OAuth token endpoint. Usage of this endpoint is documented in the OAuth 2.0 RFCs, and each grant flow will have different expectations from payload.

Who is it for

Everyone implementing an authorization server.

How to enable it

It’s enabled, as soon as you enable any feature, except the oauth_resource_serverfeature.

plugin :rodauth do
  enable :oauth_authorization_code_grant # for example
end

URL

POST /token

By default, /token is the token endpoint.

Authentication

The token endpoint requires client authentication. The following authentication methods are supported:

client_secret_basic: client id and secret used as user/pass in HTTP Basic Auth;
client_secret_post: client id and client secret sent as URL-encoded parameters in the request POST body;
none: only client id is sent in the POST body;

(rodauth-oauth also supports client_secret_jwt and private_key_jwt when the oauth_jwt_bearer_grant is enabled.)

You can limit the authentication methods either by tweaking the oauth_token_endpoint_auth_methods_supported option, while client applications can define their own subset of authentication methods via the database column defined by oauth_applications_token_endpoint_auth_method_column.

Request Parameters

The request body contains:

grant_type: the type of grant used (i.e. authorization_code, client_credentials);
code: a grant code, when the response type is “code” (authorization code grant flow);
redirect_uri: the redirect URI, must be the same as the one included in the authorization request (if there was one submitted);

Response Parameters

A successful access token generation will send back the following parameters in the response JSON body:

access_token: the access token;
token_type: the type of token (i.e. "Bearer");
refresh_token: the refresh token, used to generate a new access token after the access token expires;
expires_in: number of seconds after which the access token expires;

A failed request will get the following parameters in the response JSON body:

error_code: the code error, as per RFC;
error_description: the description of the error;

Examples

require "httpx"
response = HTTPX.post("https://oauth-server.com/token",json: {
                  client_id: ENV["CLIENT_ID"],
                  client_secret: ENV["CLIENT_SECRET"],
                  grant_type: "authorization_code",
                  code: "oiweicnewdh32fhoi3hf3ihfo2ih3f2o3as"
                })
response.raise_for_status
payload = JSON.parse(response.to_s)
puts payload #=> {"access_token" => "awr23f3h8f9d2h89...", "refresh_token" => "23fkop3kr290kc..." ....

# using cURL
> curl --data '{"client_id":"$OAUTH_CLIENT_ID","client_secret":"$OAUTH_CLIENT_SECRET","grant_type":"authorization_code","code":"oiweicnewdh32fhoi3hf3ihfo2ih3f2o3as"}' https://oauth-server.com/token

How to use it

Once client applications have the access token, they can use it in the “Authorization” header of HTTP requests:

require "httpx"
response = HTTPX.plugin(:authorization)
                .authorization("Bearer #{payload["access_token"]}")
                .post("https://resource-server.com/resource-private")

response.raise_for_status
payload = JSON.parse(response.to_s)
puts payload #=> {"id" => "awr23f3h8f9d2h89...", "refresh_token" => "23fkop3kr290kc..." ....

# using cURL
> curl -H "Authorization: Bearer $access_token" https://resource-server.com/resource-private

Rodauth Options

oauth_token_type (default: “Bearer”): the type of the access token;
oauth_token_expires_in (default: 3600): the timespan in seconds the access type will be valid for;
json_response_content_type (default: “application/json”): the mime-type sent in the Content-Type header of JSON responses; * Home

honeyryder