Add jwt secret documentation

Author: George Ciltaru

_plugins/docs.rb

@@ -99,8 +99,9 @@ def form(form_name)
   def scenario(scenario_name, endpoint)
     method = endpoint&.fetch('methods')&.first
 
-    scenario_select_by_endpoint_method(endpoint, method) ||
-      scenario_select_by_name(scenario_name)
+    scenario_select_by_name(scenario_name) ||
+      scenario_select_by_endpoint_method(endpoint, method)
+
   end
 
   def scenario_select_by_endpoint_method(endpoint, method)

api/guides/secrets.md

@@ -4,7 +4,7 @@ title: Secrets
 
 # Exchanging Secret credentials
 
-There are 4 types of secrets, `oauth2-client_credentials`, `oauth2-google`, `simple-http`, and `token`. The `credentials` object for each type has different required attributes.
+There are 5 types of secrets, `oauth2-client_credentials`, `oauth2-jwt`, `oauth2-google`, `simple-http`, and `token`. The `credentials` object for each type has different required attributes.
 
 ## `oauth2-client_credentials` credentials
 
@@ -32,6 +32,33 @@ If the exchange is successful, the `Secret` status attribute is set to `succeeed
 
 In case of failure, the information is available in the `status_details` attribute from the `meta` object.
 
+## `oauth2-jwt` credentials
+
+### Credential attributes
+- `iss` - Text - Required - The JWT issuer.
+- `aud` - Text - Required - The JWT audience.
+- `sub` - Text - Optional - The JWT subject.
+- `ttl` - Integer - Required - The JWT ttl. The `exp` claim is computed using this value.
+- `alg` - Text - Required - The algorithm used to sign the JWT. Currently, only `RS256` is supported.
+- `custom_claims` - Object - Optional - Key/Value pairs of JWT custom claims.
+- `token_url` - Text - Optional - The token url of the oauth2 integration. If this value is not included, the JWT will ve used as `access_token`.
+- `private_key_id` - Text - Optional - The private key id. This value will be added to the `kid` JWT header.
+- `private_key` - Text - Required - The private key used to sign to JWT.
+- `refresh_offset` - Integer - Optional - The value, in seconds, used to offset the refresh operation. If not set, an implicit `1800` (30 minutes) will be used.
+- `options` - Object - Optional - Key/Value pairs of options for the oauth2 integration.
+
+When an `oauth2-jwt` Secret is created or updated, a JWT is created and signed using the private_key. If `token_url` is present, a `POST` is made to the `token_url` with the assertion parameter and JWT value (and possibly options), according to the `rfc7523` standard.
+If the authorization service responds with `200 OK` and a JSON response body, the body is parsed and `access_token` and `expires_in` are used.
+It is expected that the authorization service response body is compatible with the `oauth2` protocol.
+
+If `token_url` is not present, the generated JWT is used as `access_token` and the `ttl` as `expires_in`.
+
+If the exchange is successful, the `Secret` status attribute is set to `succeeeded` and `expires_at` and `refresh_at` are set.
+- `expires_at` is the current UTC time + `expires_in`.
+- `refresh_at` is the current UTC time + `expires_in` - `refresh_offset`
+
+In case of failure, the information is available in the `status_details` attribute from the `meta` object.
+
 ## `oauth2-google` credentials
 
 ### Credential attributes

api/reference/1.0/extension_packages/discontinue.md

@@ -12,4 +12,4 @@ Discontinue an ExtensionPackage.
 
 {% form extension_package.patch %}
 
-{% scenario extension_packages.update extension_packages.discontinue_an_extension_package 1 %}
+{% scenario extension_packages.update extension_packages.discontinue_an_extension_package %}