Fix minor docs issues (typos, markdown style and rephrasing)

README.md

@@ -3,13 +3,13 @@
 Cloud-native AuthN/AuthZ enforcer for Zero Trust API protection.
 
 - **User authentication/identity verification**<br/>
-  API key, OAuth2, OIDC, mTLS, HMAC, K8s-auth
-- **Ad-hoc authorization metadata**<br/>
-  OIDC UserInfo, UMA-protected resource data, HTTP GET-by-POST
+  API key, OAuth2, OIDC, K8s-authN, mTLS, HMAC
+- **Ad hoc authorization metadata**<br/>
+  OIDC UserInfo, UMA-protected resource data, HTTP GET and GET-by-POST
 - **Authorization policy enforcement**<br/>
   OPA/Rego policies, JSON/JWT pattern matching policies
 - **Token normalization**<br/>
-  Built-in OIDC "Festival Wristband" tokens
+  OIDC-compliant "Festival Wristband" ID tokens (signed JWTs)
 
 Authorino enables hybrid API security layer, with usually no code changes required, tailor-made for your combination of authentication standards and protocols and authorization policies of choice.
 
@@ -22,7 +22,7 @@ Authorino builds on top of [Envoy Proxy](https://www.envoyproxy.io) [external au
 1. An application client (_API consumer_) obtains credentials to consume resources of the _Upstream API_, and sends a request to the _Envoy_ exposed endpoint
 2. The Envoy proxy establishes fast gRPC connection with _Authorino_ carrying data of the HTTP request (context info)
 3. **Identity verification phase** - Authorino verifies the identity of the the consumer, where at least one authentication method/identity provider must thrive
-4. **Ad-hoc authorization metadata phase** - Authorino integrates external sources of additional metadata (optional)
+4. **Ad hoc authorization metadata phase** - Authorino integrates external sources of additional metadata (optional)
 5. **Policy enforcement phase** - Authorino takes as input a JSON composed of context information, resolved identity and fetched additional metadata from previous phases, and triggers the evaluation of configured authorization policies
 6. **Wristband phase** – Authorino issues the _Festival Wristband_ OIDC token (optional), with standard and custom claims (static and dynamic values supported), to implement token normalization and/or Edge Authentication Architecture (EAA).
 7. Authorino and Envoy settle the authorization protocol with either OK/NOK response (plus extra details available in the `X-Ext-Auth-Reason` and `WWW-Authenticate` headers when NOK)
@@ -45,7 +45,7 @@ The core phases of Authorino [Auth Pipeline](docs/architecture.md#the-auth-pipel
     <tr>
       <td rowspan="7">Identity verification</td>
       <td>API key</td>
-      <td>Represented as Kubernetes `Secret` resources. The secret MUST contain an entry `api_key` that holds the value of the API key. The secret MUST also contain at least one lable `authorino.3scale.net/managed-by` with whatever value, plus any number of optional labels. The labels are used by Authorino to match corresponding API protections that accept the API key as valid credential.</td>
+      <td>Represented as Kubernetes <code>Secret</code> resources. The secret MUST contain an entry <code>api_key</code> that holds the value of the API key. The secret MUST also contain at least one lable <code>authorino.3scale.net/managed-by</code> with whatever value, plus any number of optional labels. The labels are used by Authorino to match corresponding API protections that accept the API key as valid credential.</td>
       <td>Ready</td>
     </tr>
     <tr>
@@ -69,8 +69,8 @@ The core phases of Authorino [Auth Pipeline](docs/architecture.md#the-auth-pipel
       <td>Ready</td>
     </tr>
     <tr>
-      <td>Kubernetes auth</td>
-      <td>Online verification of Kubernetes access tokens through the Kubernetes TokenReview API. The `audiences` of the token MUST include the ones specified in the API protection state, which, when omitted, is assumed to be equal to the host name of the protected API. It can be used to authenticate Kubernetes `Service Account`s (e.g. other pods running in the cluster) and users of the cluster in general.</td>
+      <td>Kubernetes authN</td>
+      <td>Online verification of Kubernetes access tokens through the Kubernetes TokenReview API. The <code>audiences</code> of the token MUST include the ones specified in the API protection state, which, when omitted, is assumed to be equal to the host name of the protected API. It can be used to authenticate Kubernetes <code>Service Account</code>s (e.g. other pods running in the cluster) and users of the cluster in general.</td>
       <td>Ready</td>
     </tr>
     <tr>
@@ -79,7 +79,7 @@ The core phases of Authorino [Auth Pipeline](docs/architecture.md#the-auth-pipel
       <td>In analysis</td>
     </tr>
     <tr>
-      <td rowspan="3">Ad-hoc authorization metadata</td>
+      <td rowspan="3">Ad hoc authorization metadata</td>
       <td>OIDC user info</td>
       <td>Online request to OpenID Connect User Info endpoint. Requires an associated OIDC identity source.</td>
       <td>Ready</td>
@@ -97,7 +97,7 @@ The core phases of Authorino [Auth Pipeline](docs/architecture.md#the-auth-pipel
     <tr>
       <td rowspan="4">Policy enforcement</td>
       <td>JSON pattern matching (e.g. JWT claims)</td>
-      <td>Authorization policies represented as simple JSON pattern-matching rules. Values can be selected from the authorization JSON built along the auth pipeline. Operations include _equals_ (`eq`), _not equal_ (`neq`), _includes_ (`incl`, for arrays), _excludes_ (`excl`, for arrays) and _matches_ (`matches`, for regular expressions). Individuals policies can be optionally skipped based on "conditions" represented with similar data selectors and operators.</td>
+      <td>Authorization policies represented as simple JSON pattern-matching rules. Values can be selected from the authorization JSON built along the auth pipeline. Operations include <i>equals</i> (<code>eq</code>), <i>not equal</i> (<code>neq</code>), <i>includes</i> (<code>incl</code>; for arrays), <i>excludes</i> (<code>excl</code>; for arrays) and <i>matches</i> (<code>matches</code>; for regular expressions). Individuals policies can be optionally skipped based on "conditions" represented with similar data selectors and operators.</td>
       <td>Ready</td>
     </tr>
     <tr>
@@ -146,20 +146,20 @@ The core phases of Authorino [Auth Pipeline](docs/architecture.md#the-auth-pipel
       <td>For consecutive requests performed, within a given period of time, by a same user that request for a same resource, such that the result of the auth pipeline can be proven that would not change.</td>
       <td>In analysis (<a href="https://github.com/kuadrant/authorino/issues/20">#20</a>)</td>
     </tr>
+    <tr>
+      <td colspan="2">External policy registry</td>
+      <td>Fetching of compatible policies from an external registry, in reconciliation-time.</td>
+      <td>Planned (<a href="https://github.com/kuadrant/authorino/issues/115">#115</a>)</td>
+    </tr>
     <tr>
       <td colspan="2">Festival Wristbands</td>
-      <td>JWTs issued by Authorino at the end of the auth pipeline and passed back to the client in the HTTP response header `X-Ext-Auth-Wristband`. Opt-in feature that can be used to enable Edge Authentication and token normalization, as well as to carry data from the external authorization back to the client (with support to static and dynamic custom claims). Authorino also exposes well-known endpoints for OpenID Connect Discovery, so the wristbands can be verified and validated, including by Authorino itself using the OIDC identity verification feature.</td>
+      <td>JWTs issued by Authorino at the end of the auth pipeline and passed back to the client in the HTTP response header <code>X-Ext-Auth-Wristband</code>. Opt-in feature that can be used to enable Edge Authentication and token normalization, as well as to carry data from the external authorization back to the client (with support to static and dynamic custom claims). Authorino also exposes well-known endpoints for OpenID Connect Discovery, so the wristbands can be verified and validated, including by Authorino itself using the OIDC identity verification feature.</td>
       <td>Ready</td>
     </tr>
     <tr>
       <td colspan="2">Multitenancy</td>
       <td>Managed instances of Authorino offered to API providers who create and maintain their own API protection states within their own realms and namespaces.</td>
-      <td>Planned</td>
-    </tr>
-    <tr>
-      <td colspan="2">External policy registry</td>
-      <td>Fetching of compatible policies from an external registry, in reconciliation-time.</td>
-      <td>In analysis</td>
+      <td>Ready</td>
     </tr>
   </tbody>
 </table>

docs/deploy.md

@@ -39,7 +39,7 @@ Some other feature-specific requirements (as opposed to actual requirements of A
 Choose between the options below to continue:
 
 [**Option A:** Local cluster](#option-a-local-cluster)<br/>
-To try Auhtorino out and/or run the examples, based on a fresh image of Authorino built locally.<br/>
+To try Authorino out and/or run the examples, based on a fresh image of Authorino built locally.<br/>
 Setup may take up to 5 minutes.
 
 [**Option B:** Custom deployment](#option-b-custom-deployment)<br/>

docs/tutorials/showcase/README.md

@@ -43,7 +43,7 @@ On top of this platform, the following applications compose the stack for this t
 - **Authorino**<br/>
     The AuthN/AuthZ enforcer that will watch and apply Authorino `Service` custom resources in the Kubernetes/OpenShift server.
 - **Keycloak**<br/>
-    To issue OIDC access tokens and to provide adhoc resource data for the authorization payload. The server is bundled with the following preloaded settings and realm resources:
+    To issue OIDC access tokens and to provide ad hoc resource data for the authorization payload. The server is bundled with the following preloaded settings and realm resources:
     - Admin console: http://localhost:8080/auth/admin (admin/p)
     - Preloaded realm: **kuadrant**
     - Preloaded clients:
@@ -78,7 +78,7 @@ $ git clone git@github.com:kuadrant/authorino.git && cd authorino
 
 ## Setup the trial local environment
 
-Launch the Kubernetes cluster on a Dokcer with [Kind](https://kind.sigs.k8s.io), build the latest Authrorino image from source and deploy the main applications of the stack. This step may take up to a few minutes for the cluster and all the deployments to be ready.
+Launch the Kubernetes cluster on a Docker with [Kind](https://kind.sigs.k8s.io), build the latest Authorino image from source and deploy the main applications of the stack. This step may take up to a few minutes for the cluster and all the deployments to be ready.
 
 ```sh
 $ DEPLOY_IDPS=1 make local-setup

pkg/service/auth_pipeline.go

@@ -52,7 +52,7 @@ func (result *AuthResult) Success() bool {
 }
 
 // AuthPipeline evaluates the context of an auth request upon the auth configs defined for the requested API
-// Throughout the pipeline, user identity, adhoc metadata and authorization policies are evaluated and their
+// Throughout the pipeline, user identity, ad hoc metadata and authorization policies are evaluated and their
 // corresponding resulting objects stored in the respective maps.
 type AuthPipeline struct {
 	ParentContext *context.Context