rodauth-oauth 0.0.3 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ec27cf0fcac2e93b6ba08d76a4fa3e165c55722864d87fb78e4f0fc70a15c759
-  data.tar.gz: 535f0b61b987f38179de2d7011b55d8b9b6e12bdf1293c9da7534c063277c2f3
+  metadata.gz: 02d69464053b6809900da774b4c9957d642b003d0a0de7aa076e57a5eb8895bc
+  data.tar.gz: e1dd94b69aa4bdf051b1c28d684a0ec2a1435da9f99ca6bf77da9d537474f9a6
 SHA512:
-  metadata.gz: d1179a1e5db37dbfdc9932a6ec74fb3fba37c7c863c0ec643f9b1c11fee8ef8b8bf71d0705bb9629135f517dbb3d49dd5e7609014ddc3aae28ad4bd0f45981a1
-  data.tar.gz: ebc711bc991746fbfa780f81a91c92508c55eca65e3e316a1fc4b23b6e9141f0d97a8871ce12527fdeaf71234d97ddfa0c712aca870c65f73ab89a11fe40839e
+  metadata.gz: cfe325a2e8daa96a72b4577566ae84772dcf114411ebbd9d0115f0f33f5b104f7c138a1b1ef7813d46f0fd2226c6560db5d974e51ec92b33ce7e393726005b2d
+  data.tar.gz: df5866c1cd089c0d361a00d1ffd1db02df9b6551940dbf70e7390657fa8558ae0fb3c8eb2fcff6ec6fb9fd52406a99615574305d5a3bacdbd20f5fc22bacd63f

data/CHANGELOG.md

@@ -2,7 +2,204 @@
 
 ## master
 
-## 0.0.3 (5/6/2020)
+### 0.2.0
+
+#### Features
+
+##### SAML Assertion Grant Type
+
+`rodauth-auth` now supports using a SAML Assertion to request for an Access token.In order to enable, you have to:
+
+```ruby
+plugin :rodauth do
+  enable :oauth_saml
+end
+```
+
+For more info about integrating it, [check the wiki](https://gitlab.com/honeyryderchuck/rodauth-oauth/-/wikis/SAML-Assertion-Access-Tokens).
+
+##### Supporting rotating keys
+
+At some point, you'll want to replace the pkeys and algorithm used to generate and verify the JWT access tokens, but you want to keep validating previously-distributed JWT tokens, at least until they expire. Now you can, via two new options, `oauth_jwt_legacy_public_key` and `oauth_jwt_legacy_algorithm`, which will be declared in the JWKs URI and used to verify access tokens.
+
+
+##### Reuse access tokens
+
+If the `oauth_reuse_access_token` is set, if there's already an existing valid access token, any new grant for the same application / account / scope will keep the same access token. This can be helpful in scenarios where one wants the same access token distributed across devices.
+
+##### require_authorizable_account
+
+The method used to verify access to the authorize flow is called `require_authorizable_account`. By default, it checks if a user is logged in by using rodauth's own `require_account`. This is the method you'd want to redefine in order to augment these requirements, i.e. request 2fa authentication.
+
+#### Improvements
+
+Expired and revoked access tokens end up generating a lot of garbage, which will have to be periodically cleaned up. You can mitigate this now by setting a uniqueness index for a group of columns, i.e. if you set a uniqueness index for the `oauth_application_id/account_id/scopes` column, `rodauth-oauth` will transparently reuse the same db entry to store the new access token. If setting some other type of uniqueness index, make sure to update the option `oauth_tokens_unique_columns` (the array of columns from the uniqueness index).
+
+#### Bugfixes
+
+Calling `before_*_route` callbacks appropriately.
+
+Fixed some mishandling of HTTP headers when in in resource-server mode.
+
+#### Chore
+
+* 97.7% test coverage;
+* `rodauth-oauth` CI tests run against sqlite, postgresql and mysql.
+
+### 0.1.0
+
+(31/7/2020)
+
+#### Features
+
+##### OpenID
+
+`rodauth-oauth` now ships with support for [OpenID Connect](https://openid.net/connect/). In order to enable, you have to:
+
+```ruby
+plugin :rodauth do
+  enable :oidc
+end
+```
+
+For more info about integrating it, [check the wiki](https://gitlab.com/honeyryderchuck/rodauth-oauth/-/wikis/home#openid-connect-since-v01).
+
+It supports omniauth openID integrations out-of-the-box, [check the OpenID example, which integrates with omniauth_openid_connect](https://gitlab.com/honeyryderchuck/rodauth-oauth/-/tree/master/examples).
+
+#### Improvements
+
+* JWT: `sub` claim now also handles "pairwise" subjects. For that, you have to set the `oauth_jwt_subject_type` option (`"public"` or `"pairwise"`) and `oauth_jwt_subject_secret` (will be used for salting the `sub` when the type is `"pairwise"`).
+* JWT: `auth_time` claim is now supported; if your application uses the `rodauth` feature `:account_expiration`, it'll use the `last_account_login_at` method, otherwise you can set the `last_account_login_at` option:
+
+```ruby
+last_account_login_at do
+  convert_timestamp(db[accounts_table].where(account_id_column => account_id).get(:that_column_where_you_keep_the_data))
+end
+```
+* JWT: `iss` claim now defaults to `authorization_server_url` when not defined;
+* JWT: `aud` claim now defaults to the token application's client ID (`client_id` claim was removed as a result);
+
+
+
+#### Breaking Changes
+
+`rodauth-oauth` URLs no longer have the `oauth-` prefix, so make sure you update your integrations accordingly, i.e. where you used to rely on `/oauth-authorize`, you'll have to use `/authorize`.
+
+URI schemes for client applications redirect URIs have to be `https`. In order to override this, set the `oauth_valid_uri_schemes` to an array of your expected URI schemes.
+
+
+#### Bugfixes
+
+* Authorization request submission can receive the `scope` as an array of values now, instead of only dealing with receiving a white-space separated list.
+* fixed trailing "/" in the "issuer" value in server metadata (`https://server.com/` -> `https://server.com`).
+
+
+### 0.0.6
+
+(6/7/2020)
+
+#### Features
+
+The `oauth_jwt` feature now supports JWT Secured Authorization Request (JAR) (see https://tools.ietf.org/html/draft-ietf-oauth-jwsreq-20). This means that client applications can send the authorization parameters inside a signed JWT. The client applications keeps the private key, while the authorization server **must** store a public key for the client application. For encrypted JWTs, the client application should use one of the public encryption keys exposed in the JWKs URI, to encrypt the JWT. Remember, **tokens must be signed then encrypted** (or just signed).
+
+###### Options:
+
+* `:oauth_application_jws_jwk_column`: db column where the public key is stored; since it's stored in the JWS format, it can be stored either as a String (JSON-encoded), or as an hstore (if you're using postgresql);
+* `:oauth_jwt_jwe_key`: key used to decrypt the request JWT;
+* `:oauth_jwt_jwe_public_key`: key used to encrypt the request JWT, and which will be exposed in the JWKs URI in the JWK format;
+
+
+#### Improvements
+
+* Removing all `_param` options; these defined the URL params, however we're using protocol-defined params, so it's unlikely (and undesired) that these'll change.
+* Hitting the revoke endpoint with a JWT access token returns a 400 error;
+
+#### Chore
+
+Removed React Javascript from example applications.
+
+
+### 0.0.5
+
+(26/6/2020)
+
+#### Features
+
+* new option: `oauth_scope_separator` (default: `" "`), to define how scopes are stored;
+
+##### Resource Server mode
+
+`rodauth-oauth` can now be used in a resource server, i.e. only for authorizing access to resources:
+
+
+```ruby
+plugin :rodauth do
+  enable :oauth
+
+  is_authorization_server? false
+  authorization_server_url "https://auth-server"
+end
+```
+
+It **requires** the authorization to implement the server metadata endpoint (`/.well-known/oauth-authorization-server`), and if using JWS, the JWKs URI endpoint (unless `oauth_jwt_public_key` is defined).
+
+#### Improvements
+
+* Multiple Redirect URIs are now allowed for client applications out-of-the-box. In order to use it in API mode, you can pass the `redirect_uri` with an array of strings (the URLs) as values; in the new client application form, you can add several input fields with name field as `redirect_uri[]`. **ATTENTION!!** When using multiple redirect URIs, passing the desired redirect URI to the authorize form becomes mandatory.
+* store scopes with whitespace instead of comma; set separator as `oauth_scope_separator` option, to keep backwards-compatibility;
+* client application can now store multiple redirect uris; the POST API parameters can accept the redirect_uri param value both as a string or an array of string; internally, they'll be stored in a whitespace-separated string;
+
+#### Bugfixes
+
+* Fixed `RETURNING` support in the databases supporting it (such as postgres).
+
+#### Chore
+
+* option `scopes_param` renamed to `scope_param`;
+*
+
+## 0.0.4
+
+(13/6/2020)
+
+### Features
+
+#### Token introspection
+
+`rodauth-oauth` now ships with an introspection endpoint (`/oauth-introspect`).
+
+#### Authorization Server Metadata
+
+`rodauth-oauth` now allows to define an authorization metadata endpoint, which has to be defined at the route of the router:
+
+```ruby
+route do |r|
+  r.rodauth
+  rodauth.oauth_server_metadata
+  ...
+```
+
+#### JWKs URI
+
+the `oauth_jwt` feature now ships with an endpoint, `/oauth-jwks`, where client applications can retrieve the JWK set to verify generated tokens.
+
+#### JWT access tokens as authorization grants
+
+The `oauth_jwt` feature now allows the usage of access tokens to authorize the generation of new tokens, [as per the RFC](https://tools.ietf.org/html/rfc7523#section-4);
+
+### Improvements
+
+* using `client_secret_basic` authorization where client id/secret params were allowed (i.e. in the token and revoke endpoints, for example);
+* improved JWK usage for both supported jwt libraries;
+* marked `fetch_access_token` as auth_value_method, thereby allowing users to fetch the access token from other sources than the "Authorization" header (i.e. form body, query params, etc...)
+
+### Bugfixes
+
+* Fixed scope claim of JWT ("scopes" -> "scope");
+
+## 0.0.3
+
+(5/6/2020)
 
 ### Features
 
@@ -34,7 +231,9 @@ end
 * renamed the existing `use_oauth_implicit_grant_type` to `use_oauth_implicit_grant_type?`;
 * It's now usable as JSON API (small caveat: POST authorize will still redirect on success...);
 
-## 0.0.2 (29/5/2020)
+## 0.0.2
+
+(29/5/2020)
 
 ### Features
 
@@ -50,6 +249,8 @@ end
 
 * usage of client secret for authorizing the generation of tokens, as the spec mandates (and refraining from them when doing PKCE).
 
-## 0.0.1 (14/5/2020)
+## 0.0.1
+
+(14/5/2020)
 
 Initial implementation of the Oauth 2.0 framework, with an example app done using roda.

data/README.md

@@ -1,13 +1,13 @@
 # Rodauth::Oauth
 
-[![pipeline status](https://gitlab.com/honeyryderchuck/rodauth-oauth/badges/master/pipeline.svg)](https://gitlab.com/honeyryderchuck/rodauth-oauth/-/commits/master)
-[![coverage report](https://gitlab.com/honeyryderchuck/rodauth-oauth/badges/master/coverage.svg)](https://gitlab.com/honeyryderchuck/rodauth-oauth/-/commits/master)
+[![pipeline status](https://gitlab.com/honeyryderchuck/rodauth-oauth/badges/master/pipeline.svg)](https://gitlab.com/honeyryderchuck/rodauth-oauth/-/pipelines?page=1&ref=master)
+[![coverage report](https://gitlab.com/honeyryderchuck/rodauth-oauth/badges/master/coverage.svg)](https://honeyryderchuck.gitlab.io/rodauth-oauth/coverage/#_AllFiles)
 
 This is an extension to the `rodauth` gem which implements the [OAuth 2.0 framework](https://tools.ietf.org/html/rfc6749) for an authorization server.
 
 ## Features
 
-This gem implements:
+This gem implements the following RFCs and features of OAuth:
 
 * [The OAuth 2.0 protocol framework](https://tools.ietf.org/html/rfc6749):
   * [Authorization grant flow](https://tools.ietf.org/html/rfc6749#section-1.3);
@@ -15,12 +15,18 @@ This gem implements:
   * [Access Token refresh](https://tools.ietf.org/html/rfc6749#section-1.5);
   * [Implicit grant (off by default)[https://tools.ietf.org/html/rfc6749#section-4.2];
 * [Token revocation](https://tools.ietf.org/html/rfc7009);
+* [Token introspection](https://tools.ietf.org/html/rfc7662);
+* [Authorization Server Metadata](https://tools.ietf.org/html/rfc8414);
 * [PKCE](https://tools.ietf.org/html/rfc7636);
 * Access Type (Token refresh online and offline);
 * [MAC Authentication Scheme](https://tools.ietf.org/html/draft-hammer-oauth-v2-mac-token-02);
 * [JWT Acess Tokens](https://tools.ietf.org/html/draft-ietf-oauth-access-token-jwt-07);
+* [SAML 2.0 Assertion Access Tokens](https://tools.ietf.org/html/draft-ietf-oauth-saml2-bearer-03);
+* [JWT Secured Authorization Requests](https://tools.ietf.org/html/draft-ietf-oauth-jwsreq-20);
 * OAuth application and token management dashboards;
 
+It also implements the [OpenID Connect layer](https://openid.net/connect/) on top of the OAuth features it provides.
+
 This gem supports also rails (through [rodauth-rails]((https://github.com/janko/rodauth-rails))).
 
 
@@ -40,6 +46,15 @@ Or install it yourself as:
 
     $ gem install rodauth-oauth
 
+
+## Resources
+|               |                                                             |
+| ------------- | ----------------------------------------------------------- |
+| Website       | https://honeyryderchuck.gitlab.io/rodauth-oauth/            |
+| Documentation | https://honeyryderchuck.gitlab.io/rodauth-oauth/rdoc/       |
+| Wiki          | https://gitlab.com/honeyryderchuck/rodauth-oauth/wikis/home |
+| CI            | https://gitlab.com/honeyryderchuck/rodauth-oauth/pipelines  |
+
 ## Usage
 
 This tutorial assumes you already read the documentation and know how to set up `rodauth`. After that, integrating `roda-auth` will look like:
@@ -83,11 +98,22 @@ route do |r|
 end
 ```
 
-You'll have to do a bit more boilerplate, so here's the instructions.
+
+For OpenID, it's very similar to the example above:
+
+```ruby
+plugin :rodauth do
+  # enable it in the plugin
+  enable :login, :openid
+  oauth_application_default_scope %w[openid]
+  oauth_application_scopes %w[openid email profile]
+end
+```
+
 
 ### Example (TL;DR)
 
-If you're familiar with the technology and want to skip the next paragraphs, just [check our roda example](https://gitlab.com/honeyryderchuck/rodauth-oauth/-/tree/master/examples/roda).
+If you're familiar with the technology and want to skip the next paragraphs, just [check our example applications](https://gitlab.com/honeyryderchuck/rodauth-oauth/-/tree/master/examples/).
 
 
 Generating tokens happens mostly server-to-server, so here's an example using:
@@ -98,7 +124,7 @@ Generating tokens happens mostly server-to-server, so here's an example using:
 
 ```ruby
 require "httpx"
-response = HTTPX.post("https://auth_server/oauth-token",json: {
+response = HTTPX.post("https://auth_server/token",json: {
                   client_id: ENV["OAUTH_CLIENT_ID"],
                   client_secret: ENV["OAUTH_CLIENT_SECRET"],
                   grant_type: "authorization_code",
@@ -112,7 +138,7 @@ puts payload #=> {"access_token" => "awr23f3h8f9d2h89...", "refresh_token" => "2
 ##### cURL
 
 ```
-> curl --data '{"client_id":"$OAUTH_CLIENT_ID","client_secret":"$OAUTH_CLIENT_SECRET","grant_type":"authorization_code","code":"oiweicnewdh32fhoi3hf3ihfo2ih3f2o3as"}' https://auth_server/oauth-token
+> curl --data '{"client_id":"$OAUTH_CLIENT_ID","client_secret":"$OAUTH_CLIENT_SECRET","grant_type":"authorization_code","code":"oiweicnewdh32fhoi3hf3ihfo2ih3f2o3as"}' https://auth_server/token
 ```
 
 #### Refresh Token
@@ -123,7 +149,7 @@ Refreshing expired tokens also happens mostly server-to-server, here's an exampl
 
 ```ruby
 require "httpx"
-response = HTTPX.post("https://auth_server/oauth-token",json: {
+response = HTTPX.post("https://auth_server/token",json: {
                   client_id: ENV["OAUTH_CLIENT_ID"],
                   client_secret: ENV["OAUTH_CLIENT_SECRET"],
                   grant_type: "refresh_token",
@@ -137,7 +163,7 @@ puts payload #=> {"access_token" => "awr23f3h8f9d2h89...", "token_type" => "Bear
 ##### cURL
 
 ```
-> curl -H "X-your-auth-scheme: $SERVER_KEY" --data '{"client_id":"$OAUTH_CLIENT_ID","client_secret":"$OAUTH_CLIENT_SECRET","grant_type":"token","token":"2r89hfef4j9f90d2j2390jf390g"}' https://auth_server/oauth-token
+> curl -H "X-your-auth-scheme: $SERVER_KEY" --data '{"client_id":"$OAUTH_CLIENT_ID","client_secret":"$OAUTH_CLIENT_SECRET","grant_type":"token","token":"2r89hfef4j9f90d2j2390jf390g"}' https://auth_server/token
 ```
 
 #### Revoking tokens
@@ -146,10 +172,9 @@ Token revocation can be done both by the idenntity owner or the application owne
 
 ```ruby
 require "httpx"
-httpx = HTTPX.plugin(:authorization)
-response = httpx.with(headers: { "X-your-auth-scheme" => ENV["SERVER_KEY"] })
-                .post("https://auth_server/oauth-revoke",json: {
-                  client_id: ENV["OAUTH_CLIENT_ID"],
+httpx = HTTPX.plugin(:basic_authorization)
+response = httpx.basic_authentication(ENV["CLIENT_ID"], ENV["CLIENT_SECRET"])
+                .post("https://auth_server/revoke",json: {
                   token_type_hint: "access_token", # can also be "refresh:tokn"
                   token: "2r89hfef4j9f90d2j2390jf390g"
                 })
@@ -161,7 +186,56 @@ puts payload #=> {"access_token" => "awr23f3h8f9d2h89...", "token_type" => "Bear
 ##### cURL
 
 ```
-> curl -H "X-your-auth-scheme: $SERVER_KEY" --data '{"client_id":"$OAUTH_CLIENT_ID","token_type_hint":"access_token","token":"2r89hfef4j9f90d2j2390jf390g"}' https://auth_server/oauth-revoke
+> curl -H "X-your-auth-scheme: $SERVER_KEY" --data '{"client_id":"$OAUTH_CLIENT_ID","token_type_hint":"access_token","token":"2r89hfef4j9f90d2j2390jf390g"}' https://auth_server/revoke
+```
+
+#### Token introspection
+
+Token revocation can be used to determine the state of a token (whether active, what's the scope...) . Here's an example using server-to-server:
+
+```ruby
+require "httpx"
+httpx = HTTPX.plugin(:basic_authorization)
+response = httpx.basic_authentication(ENV["CLIENT_ID"], ENV["CLIENT_SECRET"])
+                .post("https://auth_server/introspect",json: {
+                  token_type_hint: "access_token", # can also be "refresh:tokn"
+                  token: "2r89hfef4j9f90d2j2390jf390g"
+                })
+response.raise_for_status
+payload = JSON.parse(response.to_s)
+puts payload #=> {"active" => true, "scope" => "read write" ....
+```
+
+##### cURL
+
+```
+> curl -H "X-your-auth-scheme: $SERVER_KEY" --data '{"client_id":"$OAUTH_CLIENT_ID","token_type_hint":"access_token","token":"2r89hfef4j9f90d2j2390jf390g"}' https://auth_server/revoke
+```
+
+### Authorization Server Metadata
+
+The Authorization Server Metadata endpoint can be used by clients to obtain the information needed to interact with an
+   OAuth 2.0 authorization server, i.e. know which endpoint is used to authorize clients.
+
+Because this endpoint **must be https://AUTHSERVER/.well-known/oauth-authorization-server**, you'll have to define it at the root-level of your app:
+
+```ruby
+plugin :rodauth do
+  # enable it in the plugin
+  enable :login, :oauth
+  oauth_application_default_scope %w[profile.read]
+  oauth_application_scopes %w[profile.read profile.write]
+end
+
+# then, inside roda
+
+route do |r|
+  r.rodauth
+  # server metadata endpoint
+  rodauth.oauth_server_metadata
+
+  # now, your oauth and app code...
+
 ```
 
 ### Database migrations
@@ -192,10 +266,10 @@ The rodauth default setup expects the roda `render` plugin to be activated; by d
 
 Once you set it up, by default, the following endpoints will be available:
 
-* `GET /oauth-authorize`: Loads the OAuth authorization HTML form;
-* `POST /oauth-authorize`: Responds to an OAuth authorization request, as [per the spec](https://tools.ietf.org/html/rfc6749#section-4);
-* `POST /oauth-token`: Generates OAuth tokens as [per the spec](https://tools.ietf.org/html/rfc6749#section-4.4.2);
-* `POST /oauth-revoke`: Revokes OAuth tokens as [per the spec](https://tools.ietf.org/html/rfc7009);
+* `GET /authorize`: Loads the OAuth authorization HTML form;
+* `POST /authorize`: Responds to an OAuth authorization request, as [per the spec](https://tools.ietf.org/html/rfc6749#section-4);
+* `POST /token`: Generates OAuth tokens as [per the spec](https://tools.ietf.org/html/rfc6749#section-4.4.2);
+* `POST /revoke`: Revokes OAuth tokens as [per the spec](https://tools.ietf.org/html/rfc7009);
 
 ### OAuth applications
 
@@ -375,7 +449,7 @@ The "Proof Key for Code Exchange by OAuth Public Clients" (aka PKCE) flow, which
 ```ruby
 # with httpx
 require "httpx"
-response = HTTPX.post("https://auth_server/oauth-token",json: {
+response = HTTPX.post("https://auth_server/token",json: {
                   client_id: ENV["OAUTH_CLIENT_ID"],
                   grant_type: "authorization_code",
                   code: "oiweicnewdh32fhoi3hf3ihfo2ih3f2o3as",
@@ -426,14 +500,14 @@ Generating an access token will deliver the following fields:
 ```ruby
 # with httpx
 require "httpx"
-response = httpx.post("https://auth_server/oauth-token",json: {
-                  client_id: ENV["OAUTH_CLIENT_ID"],
-                  client_secret: ENV["OAUTH_CLIENT_SECRET"],
+response = httpx.post("https://auth_server/token",json: {
+                  client_id: env["oauth_client_id"],
+                  client_secret: env["oauth_client_secret"],
                   grant_type: "authorization_code",
                   code: "oiweicnewdh32fhoi3hf3ihfo2ih3f2o3as"
                 })
 response.raise_for_status
-payload = JSON.parse(response.to_s)
+payload = json.parse(response.to_s)
 puts payload #=> {
 # "access_token" => ....
 # "mac_key" => ....
@@ -469,7 +543,6 @@ This will, by default, use the OAuth application as HMAC signature and "HS256" a
 ```ruby
 enable :oauth_jwt
 oauth_jwt_secret "SECRET"
-# or oauth_jwt_secret_path "path/to/file"
 oauth_jwt_algorithm "HS512"
 ```
 
@@ -486,7 +559,7 @@ rsa_public = rsa_private.public_key
 plugin :rodauth do
   enable :oauth_jwt
   oauth_jwt_key rsa_private
-  oauth_jwt_decoding_secret rsa_public
+  oauth_jwt_public_key rsa_public
   oauth_jwt_algorithm "RS256" 
 end
 ```
@@ -496,10 +569,14 @@ end
 One can further encode the JWT token using JSON Web Keys. Here's how you could enable the feature:
 
 ```ruby
+rsa_private = OpenSSL::PKey::RSA.generate 2048
+rsa_public = rsa_private.public_key
+
 plugin :rodauth do
   enable :oauth_jwt
-  oauth_jwt_jwk_key 2048 # can be key size or the encoded RSA key, which is the only one supported now.
-  # oauth_jwt_jwk_key "path/to/rsa.pem" if you prefer
+  oauth_jwt_jwk_key rsa_private
+  oauth_jwt_jwk_public_key rsa_public
+  oauth_jwt_jwk_algorithm "RS256" 
 end
 ```
 
@@ -520,6 +597,26 @@ end
 
 which adds an extra layer of protection.
 
+#### JWKS URI
+
+A route is defined for getting the JWK Set in a JSON format; this is typically used by client applications, who need the JWK set to decode the JWT token. This URL is typically `https://oauth-server/jwks`.
+
+#### JWT Bearer as authorization grant
+
+One can emit a new access token by using the bearer access token as grant. This can be done emitting a request similar to this:
+
+```ruby
+# with httpx
+require "httpx"
+response = httpx.post("https://auth_server/token",json: {
+                  grant_type: "urn:ietf:params:oauth:grant-type:jwt-bearer",
+                  assertion: "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOjEsImlzcyI6IkV4YW1wbGUiLCJpYXQiOjE1OTIwMDk1MDEsImNsaWVudF9pZCI6IkNMSUVOVF9JRCIsImV4cCI6MTU5MjAxMzEwMSwiYXVkIjpudWxsLCJzY29wZSI6InVzZXIucmVhZCB1c2VyLndyaXRlIiwianRpIjoiOGM1NTVjMjdiOWRjNDdmOTcyNWRkYzBhMjk0NzA1ZTA4NzFkY2JlN2Q5ZTNlMmVkNGE1ZTBiOGZlNTZlYzcxMSJ9.AlxKRtE3ec0mtyBSDx4VseND4eC6cH5ubtv8gfYxxsc"
+                })
+response.raise_for_status
+payload = json.parse(response.to_s)
+puts payload #=> {
+# "access_token" => "ey....
+```
 
 #### DB Schema