diff --git a/README.md b/README.md index 6446fde0..59735c94 100644 --- a/README.md +++ b/README.md @@ -73,8 +73,8 @@ Under the hood, Authorino is based on Kubernetes [Custom Resource Definitions](h 1. A user or service account (_"Consumer"_) obtains an access token to consume resources of the _Upstream_ service, and sends a request to the _Envoy_ ingress endpoint 2. The Envoy proxy establishes fast gRPC connection with _Authorino_ carrying data of the HTTP request (context info), which causes Authorino to lookup for an `AuthConfig` Custom Resource to enforce (pre-cached) -3. **Identity verification (authentication) phase** - Authorino verifies the identity of the the consumer, where at least one authentication method/identity provider must go through -4. **External metadata phase** - Authorino fetches aditional metadata for the authorization from external sources (optional) +3. **Identity verification (authentication) phase** - Authorino verifies the identity of the consumer, where at least one authentication method/identity provider must go through +4. **External metadata phase** - Authorino fetches additional metadata for the authorization from external sources (optional) 5. **Policy enforcement (authorization) phase** - Authorino takes as input a JSON composed out of context data, resolved identity object and fetched additional metadata from previous phases, and triggers the evaluation of user-defined authorization policies 6. **Response (metadata-out) phase** – Authorino builds user-defined custom responses (dynamic JSON objects and/or _Festival Wristband_ OIDC tokens), to be supplied back to the client and/or upstream service within added HTTP headers or as Envoy Dynamic Metadata (optional) 7. **Callbacks phase** – Authorino sends callbacks to specified HTTP endpoints (optional) @@ -287,7 +287,7 @@ For a detailed description of the features above, refer to the [Features](./docs
Can't I just use Envoy JWT Authentication and RBAC filters? - Envoy's [JWT Authentication](https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/http/jwt_authn/v3/config.proto.html) works pretty much similar to Authorino's [JOSE/JWT verification and validation for OpenID Connect](#openid-connect-oidc-jwtjose-verification-and-validation-identityoidc). In both cases, the JSON Web Key Sets (JWKS) to verify the JWTs are auto-loaded and cached to be used in request-time. Moreover, you can configure for details such as where to extract the JWT from the HTTP request (header, param or cookie) and do some cool tricks regarding how dynamic metadata based on JWT claims can be injected to consecutive filters in the chain. + Envoy's [JWT Authentication](https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/http/jwt_authn/v3/config.proto.html) works pretty much similar to Authorino's [JOSE/JWT verification and validation for OpenID Connect](./docs/features.md#openid-connect-oidc-jwtjose-verification-and-validation-identityoidc). In both cases, the JSON Web Key Sets (JWKS) to verify the JWTs are auto-loaded and cached to be used in request-time. Moreover, you can configure for details such as where to extract the JWT from the HTTP request (header, param or cookie) and do some cool tricks regarding how dynamic metadata based on JWT claims can be injected to consecutive filters in the chain. However, in terms of authorization, while Envoy's implementation essentially allows to check for the list of audiences (`aud` JWT claim), Authorino opens up for a lot more options such as pattern-matching rules with operators and conditionals, built-in OPA and other methods of evaluating authorization policies. @@ -325,9 +325,9 @@ For a detailed description of the features above, refer to the [Features](./docs
Do I have to learn OPA/Rego language to use Authorino? - No, you do not. However, if you are comfortable with [Rego](https://www.openpolicyagent.org/docs/latest/policy-language/) from Open Policy Agent (OPA), there are some quite interresting things you can do in Authorino, just as you would in any OPA server or OPA plugin, but leveraging Authorino's [built-in OPA module](./docs/architecture.md#open-policy-agent-opa-rego-policies-authorizationopa) instead. Authorino's OPA module is compiled as part of Authorino's code directly from the Golang packages, and imposes no extra latency to the evaluation of your authorization policies. Even the policies themselves are pre-compiled in reconciliation-time, for fast evaluation afterwards, in request-time. + No, you do not. However, if you are comfortable with [Rego](https://www.openpolicyagent.org/docs/latest/policy-language/) from Open Policy Agent (OPA), there are some quite interesting things you can do in Authorino, just as you would in any OPA server or OPA plugin, but leveraging Authorino's [built-in OPA module](./docs/features.md#open-policy-agent-opa-rego-policies-authorizationopa) instead. Authorino's OPA module is compiled as part of Authorino's code directly from the Golang packages, and imposes no extra latency to the evaluation of your authorization policies. Even the policies themselves are pre-compiled in reconciliation-time, for fast evaluation afterwards, in request-time. - On the other hand, if you do not want to learn Rego or in any case would like to combine it with declarative and Kubernetes-native authN/authZ spec for your services, Authorino does complement OPA with at least two other methods for expressing authorization policies – i.e. [JSON pattern-matching authorization rules](./docs/architecture.md#json-pattern-matching-authorization-rules-authorizationjson) and [Kubernetes SubjectAccessReview](./docs/architecture.md#kubernetes-subjectaccessreview-authorizationkubernetes), the latter allowing to rely completely on the Kubernetes RBAC. + On the other hand, if you do not want to learn Rego or in any case would like to combine it with declarative and Kubernetes-native authN/authZ spec for your services, Authorino does complement OPA with at least two other methods for expressing authorization policies – i.e. [JSON pattern-matching authorization rules](./docs/features.md#json-pattern-matching-authorization-rules-authorizationjson) and [Kubernetes SubjectAccessReview](./docs/features.md#kubernetes-subjectaccessreview-authorizationkubernetes), the latter allowing to rely completely on the Kubernetes RBAC. You break down, mix and combine these methods and technolgies in as many authorization policies as you want, potentially applying them according to specific conditions. Authorino will trigger the evaluation of concurrent policies in parallel, aborting the context if any of the processes denies access. @@ -350,7 +350,7 @@ For a detailed description of the features above, refer to the [Features](./docs Additionally, when enabling the request body passed in the payload to Authorino, parsing of the content should be of concern as well. Authorino provides easy access to attributes of the HTTP request, parsed as part of the [Authorization JSON](./docs/architecture.md#the-authorization-json), however the body of the request is passed as string and should be parsed by the user according to each case. - Check out Authorino [OPA authorization](./docs/features.md#open-policy-agent-opa-rego-policies-authorizationopa) and the Rego [Encoding](https://www.openpolicyagent.org/docs/latest/policy-reference/#encoding) functions for options to parse serialized JSON, YAML and URL-encoded params. For XML transformation, an external parsing service connected via Authorino's [HTTP GET/GET-by-POST external metadata](#http-getget-by-post-metadatahttp) might be required. + Check out Authorino [OPA authorization](./docs/features.md#open-policy-agent-opa-rego-policies-authorizationopa) and the Rego [Encoding](https://www.openpolicyagent.org/docs/latest/policy-reference/#encoding) functions for options to parse serialized JSON, YAML and URL-encoded params. For XML transformation, an external parsing service connected via Authorino's [HTTP GET/GET-by-POST external metadata](./docs/features.md#http-getget-by-post-metadatahttp) might be required.
@@ -384,7 +384,7 @@ For a detailed description of the features above, refer to the [Features](./docs
Can I use Authorino for rate limiting? - You can, but you shouldn't. Check out instead [Limitador](https://github.com/kuadrant/limitador), for simple and efficient global rate limiting. Combine it with Authorino and Authorino's support for [Envoy Dynamic Metadata](./docs/architecture.md#envoy-dynamic-metadata) for authenticated rate limiting. + You can, but you shouldn't. Check out instead [Limitador](https://github.com/kuadrant/limitador), for simple and efficient global rate limiting. Combine it with Authorino and Authorino's support for [Envoy Dynamic Metadata](./docs/features.md#envoy-dynamic-metadata) for authenticated rate limiting.
## Benchmarks diff --git a/docs/architecture.md b/docs/architecture.md index 963e3a7c..a27d2e2e 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -27,7 +27,7 @@ ![Architecture](./architecture.gif) -There are a few concepts to understand Authorino's architecture. The main components are: **Authorino**, **Envoy** and the **Upstream** service to be protected. Envoy proxies requests to the the configured **virtual host** upstream service, first contacting with Authorino to decide on authN/authZ. +There are a few concepts to understand Authorino's architecture. The main components are: **Authorino**, **Envoy** and the **Upstream** service to be protected. Envoy proxies requests to the configured **virtual host** upstream service, first contacting with Authorino to decide on authN/authZ. The topology can vary from centralized proxy and centralized authorization service, to dedicated sidecars, with the nuances in between. Read more about the topologies in the [Topologies](#topologies) section below. @@ -76,7 +76,7 @@ Apart from that, protected service should only listen on `localhost` and all tra ## Cluster-wide vs. Namespaced instances -Auhorino instances can run in either **cluster-wide** or **namespaced** mode. +Authorino instances can run in either **cluster-wide** or **namespaced** mode. Namespace-scoped instances only watch resources (`AuthConfig`s and `Secret`s) created in a given namespace. This deployment mode does not require admin privileges over the Kubernetes cluster to deploy the instance of the service (given Authorino's CRDs have been installed beforehand, such as when Authorino is installed using the [Authorino Operator](https://github.com/kuadrant-authorino-operator)). @@ -192,7 +192,7 @@ Alternatively to `Attributes.Http.Host`, a `host` entry can be supplied in the ` The `host` context extension is useful to support use cases such as of **path prefix-based lookup** and **wildcard subdomains lookup** with lookup strongly dictated by the external authorization client (e.g. Envoy), which often knows about routing and the expected `AuthConfig` to enforce beyond what Authorino can infer strictly based on the host name. -Wildcards can also be used in the host names specified in the `AuthConfig`, resolved by Authorino. E.g. if `*.pets.com` is in `spec.hosts`, Authorino will match the concrete host names `dogs.pets.com`, `cats.pets.com`, etc. In case, of multiple possible matches, Authorino will try the longest match first (in terms of host name labels) and fall back to closest wildcard upwards in the domain tree (if any). +Wildcards can also be used in the host names specified in the `AuthConfig`, resolved by Authorino. E.g. if `*.pets.com` is in `spec.hosts`, Authorino will match the concrete host names `dogs.pets.com`, `cats.pets.com`, etc. In case, of multiple possible matches, Authorino will try the longest match first (in terms of host name labels) and fall back to the closest wildcard upwards in the domain tree (if any). When more than one host name is specified in the `AuthConfig`, all of them can be used as key, i.e. all of them can be requested in the authorization request and will be mapped to the same config. @@ -210,11 +210,11 @@ The domain tree above induces the following relation:
-The host can include the port number (i.e. `hostname:port`) or it can be just the name of the host name. Authorino will first try finding in the index a config associated to `hostname:port`, as supplied in the authorization request; if the index misses an entry for `hostname:port`, Authorino will then remove the `:port` suffix and repeate the lookup using just `hostname` as key. This provides implicit support for multiple port numbers for a same host without having to list all combinations in the `AuthConfig`. +The host can include the port number (i.e. `hostname:port`) or it can be just the name of the host name. Authorino will first try finding in the index a config associated to `hostname:port`, as supplied in the authorization request; if the index misses an entry for `hostname:port`, Authorino will then remove the `:port` suffix and repeat the lookup using just `hostname` as key. This provides implicit support for multiple port numbers for a same host without having to list all combinations in the `AuthConfig`. ### Avoiding host name collision -Authorino tries to prevent host name collision between `AuthConfig`s by rejecting to link in the index any `AuthConfig` and host name if the host name is already linked to a different `AuthConfig` in the index. This was intentionally designed to prevent users from surperseding each others' `AuthConfig`s, partially or fully, by just picking the same host names or overlapping host names as others. +Authorino tries to prevent host name collision between `AuthConfig`s by rejecting to link in the index any `AuthConfig` and host name if the host name is already linked to a different `AuthConfig` in the index. This was intentionally designed to prevent users from superseding each other's `AuthConfig`s, partially or fully, by just picking the same host names or overlapping host names as others. When wildcards are involved, a host name that matches a host wildcard already linked in the index to another `AuthConfig` will be considered taken, and therefore the newest `AuthConfig` will be rejected to be linked to that host. @@ -222,7 +222,7 @@ When wildcards are involved, a host name that matches a host wildcard already li On every Auth Pipeline, Authorino builds the **Authorization JSON**, a "working-memory" data structure composed of `context` (information about the request, as supplied by the Envoy proxy to Authorino) and `auth` (objects resolved in phases (i) to (v) of the pipeline). The evaluators of each phase can read from the Authorization JSON and implement dynamic properties and decisions based on its values. -At phase (iii), the authorization evaluators count on an Auhtorization JSON payload that looks like the following: +At phase (iii), the authorization evaluators count on an Authorization JSON payload that looks like the following: ```jsonc // The authorization JSON combined along Authorino's auth pipeline for each request @@ -283,7 +283,7 @@ After phase (iii), Authorino appends to the authorization JSON the results of th } ``` -[Festival Wristbands](#festival-wristbands) and [Dynamic JSON](#dynamic-json-response) responses can include dynamic values (custom claims/properties) fetched from the authorization JSON. These can be returned to the external authorization client in added HTTP headers or as Envoy [Well Known Dynamic Metadata](https://www.envoyproxy.io/docs/envoy/latest/configuration/advanced/well_known_dynamic_metadata). Check out [Dynamic response features](./features.md#dynamic-response-features-response) for details. +[Festival Wristbands](./features.md#festival-wristband-tokens-responsewristband) and [Dynamic JSON](./features.md#json-injection-responsejson) responses can include dynamic values (custom claims/properties) fetched from the authorization JSON. These can be returned to the external authorization client in added HTTP headers or as Envoy [Well Known Dynamic Metadata](https://www.envoyproxy.io/docs/envoy/latest/configuration/advanced/well_known_dynamic_metadata). Check out [Dynamic response features](./features.md#dynamic-response-features-response) for details. For information about reading and fetching data from the Authorization JSON (syntax, functions, etc), check out [JSON paths](./features.md#common-feature-json-paths-valuefromauthjson). @@ -370,15 +370,15 @@ The following are all valid examples of `AuthConfig` label selector filters: The table below describes the roles and role bindings defined by the Authorino service: -| Role | Kind | Scope(*) | Description | Permissions | -| ---------------------------------- | ------------- |:--------:| --------------------------------------- | ------------------------------------------------------------------------------------------------ | -| `authorino-manager-role` | `ClusterRole` | C/N | Role of the Authorino manager service | Watch and reconcile `AuthConfig`s and `Secret`s | -| `authorino-manager-k8s-auth-role` | `ClusterRole` | C/N | Role for the Kubernetes auth features | Create `TokenReview`s and `SubjectAccessReview`s (Kubernetes auth) | -| `authorino-leader-election-role` | `Role` | N | Leader election role | Create/update the `ConfigMap` used to coordinate which replica of Authorino is the leader | -| `authorino-authconfig-editor-role` | `ClusterRole` | - | `AuthConfig` editor | R/W `AuthConfig`s; Read `AuthConfig/status` | -| `authorino-authconfig-viewer-role` | `ClusterRole` | - | `AuthConfig` viewer | Read `AuthConfig`s and `AuthConfig/status` | -| `authorino-proxy-role` | `ClusterRole` | C/N | Kube-rbac-proxy-role (sidecar)'s role | Create `TokenReview`s and `SubjectAccessReview`s to check permissions to the `/metrics` endpoint | -| `authorino-metrics-reader` | `ClusterRole` | - | Metrics reader | `GET /metrics` | +| Role | Kind | Scope(*) | Description | Permissions | +|------------------------------------|---------------|:--------:|---------------------------------------|--------------------------------------------------------------------------------------------------| +| `authorino-manager-role` | `ClusterRole` | C/N | Role of the Authorino manager service | Watch and reconcile `AuthConfig`s and `Secret`s | +| `authorino-manager-k8s-auth-role` | `ClusterRole` | C/N | Role for the Kubernetes auth features | Create `TokenReview`s and `SubjectAccessReview`s (Kubernetes auth) | +| `authorino-leader-election-role` | `Role` | N | Leader election role | Create/update the `ConfigMap` used to coordinate which replica of Authorino is the leader | +| `authorino-authconfig-editor-role` | `ClusterRole` | - | `AuthConfig` editor | R/W `AuthConfig`s; Read `AuthConfig/status` | +| `authorino-authconfig-viewer-role` | `ClusterRole` | - | `AuthConfig` viewer | Read `AuthConfig`s and `AuthConfig/status` | +| `authorino-proxy-role` | `ClusterRole` | C/N | Kube-rbac-proxy-role (sidecar)'s role | Create `TokenReview`s and `SubjectAccessReview`s to check permissions to the `/metrics` endpoint | +| `authorino-metrics-reader` | `ClusterRole` | - | Metrics reader | `GET /metrics` | (*) C - Cluster-wide | N - Authorino namespace | C/N - Cluster-wide or Authorino namespace (depending on the deployment mode). diff --git a/docs/code_of_conduct.md b/docs/code_of_conduct.md index 152f112b..4b83f006 100644 --- a/docs/code_of_conduct.md +++ b/docs/code_of_conduct.md @@ -7,4 +7,4 @@ This document provides community guidelines for a safe, respectful, productive, - When interpreting the words and actions of others, participants should always assume good intentions. - Behaviour which can be reasonably considered harassment will not be tolerated. -This Code of Conduct is adapted from the [The Ruby Community Conduct Guideline](https://www.ruby-lang.org/en/conduct/) +This Code of Conduct is adapted from [The Ruby Community Conduct Guideline](https://www.ruby-lang.org/en/conduct/) diff --git a/docs/contributing.md b/docs/contributing.md index 2b717e2a..248319f1 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -147,7 +147,7 @@ kubectl port-forward deployment/envoy 8000:8000 & - **talker-api**: used by Authorino to fetch UMA-protected resource data associated with the Talker API - Preloaded resources: - `/hello` - - `/greetings/1` (owned by user jonh) + - `/greetings/1` (owned by user john) - `/greetings/2` (owned by user jane) - `/goodbye` - Realm roles: diff --git a/docs/features.md b/docs/features.md index 28440a05..0dea8075 100644 --- a/docs/features.md +++ b/docs/features.md @@ -47,9 +47,9 @@ We call _features_ of Authorino the different things one can do to enforce identity verification & authentication and authorization on requests against protected services. These can be a specific identity verification method based on a supported authentication protocol, or a method to fetch additional auth metadata in request-time, etc. -Most features of Authorino relate to the different phases of the [Auth Pipeline](./architecture.md#the-auth-pipeline) and therefore are configured in the Authorino [`AuthConfig`](./architecture.md#the-authorino-authconfig-custom-resource-definition-crd). An _identity verification feature_ usually refers to a functionality of Authorino such as the [API key-based authentication](#api-key-identityapikey) implemented by Authorino, the [validation of JWTs/OIDC ID tokens](#openid-connect-oidc-jwtjose-verification-and-validation-identityoidc), and authentication based on [Kubernetes TokenReviews](#kubernetes-tokenreview-identitykubernetes). Analogously, [OPA](#open-policy-agent-opa-rego-policies-authorizationopa), [JSON pattern-matching](#json-pattern-matching-authorization-rules-authorizationjson) and [Kuberentes SubjectAccessReview](#kubernetes-subjectaccessreview-authorizationkubernetes) are examples of _authorization features_ of Authorino. +Most features of Authorino relate to the different phases of the [Auth Pipeline](./architecture.md#the-auth-pipeline-aka-enforcing-protection-in-request-time) and therefore are configured in the Authorino [`AuthConfig`](./architecture.md#the-authorino-authconfig-custom-resource-definition-crd). An _identity verification feature_ usually refers to a functionality of Authorino such as the [API key-based authentication](#api-key-identityapikey) implemented by Authorino, the [validation of JWTs/OIDC ID tokens](#openid-connect-oidc-jwtjose-verification-and-validation-identityoidc), and authentication based on [Kubernetes TokenReviews](#kubernetes-tokenreview-identitykubernetes). Analogously, [OPA](#open-policy-agent-opa-rego-policies-authorizationopa), [JSON pattern-matching](#json-pattern-matching-authorization-rules-authorizationjson) and [Kubernetes SubjectAccessReview](#kubernetes-subjectaccessreview-authorizationkubernetes) are examples of _authorization features_ of Authorino. -At a deeper level, a _feature_ can also be an additional funcionality within a bigger feature, usually applicable to the whole class the bigger feature belongs to. For instance, the configuration of the location and key selector of [auth credentials](#extra-auth-credentials-credentials), available for all identity verification-related features. Other examples would be [_Identity extension_](#extra-identity-extension-extendedproperties) and [_Response wrappers_](#extra-response-wrappers-wrapper-and-wrapperkey). +At a deeper level, a _feature_ can also be an additional functionality within a bigger feature, usually applicable to the whole class the bigger feature belongs to. For instance, the configuration of the location and key selector of [auth credentials](#extra-auth-credentials-credentials), available for all identity verification-related features. Other examples would be [_Identity extension_](#extra-identity-extension-extendedproperties) and [_Response wrappers_](#extra-response-wrappers-wrapper-and-wrapperkey). A full specification of all features of Authorino that can be configured in an `AuthConfig` can be found in the official [spec](../install/crd/authorino.kuadrant.io_authconfigs.yaml) of the custom resource definition. @@ -95,7 +95,7 @@ Examples below provided for the following Authorization JSON: ``` **`@strip`**
-Strips out any non printable characters such as carrige return. E.g. `auth.identity.email.@strip` → `"jane@petcorp.com"`. +Strips out any non-printable characters such as carriage return. E.g. `auth.identity.email.@strip` → `"jane@petcorp.com"`. **`@case:upper|lower`**
Changes the case of a string. E.g. `auth.identity.username.@case:upper` → `"JANE"`. @@ -144,7 +144,7 @@ spec: - name: api-key-users apiKey: selector: - matchLabels: # the key-value set used to select the matching `Secret`s; resources including these labels will be acepted as valid API keys to authenticate to this service + matchLabels: # the key-value set used to select the matching `Secret`s; resources including these labels will be accepted as valid API keys to authenticate to this service group: friends # some custom label allNamespaces: true # only works with cluster-wide Authorino instances; otherwise, create the API key secrets in the same namespace of the AuthConfig ``` @@ -236,7 +236,7 @@ Developers must set the token introspection endpoint in the `AuthConfig`, as wel ![OAuth 2.0 Token Introspect](http://www.plantuml.com/plantuml/png/NP1DJiD038NtSmehQuQgsr4R5TZ0gXLaHwHgD779g8aTF1xAZv0u3GVZ9BHH18YbttkodxzLKY-Q-ywaVQJ1Y--XP-BG2lS8AXcDkRSbN6HjMIAnWrjyp9ZK_4Xmz8lrQOI4yeHIW8CRKk4qO51GtYCPOaMG-D2gWytwhe9P_8rSLzLcDZ-VrtJ5f4XggvS17VXXw6Bm6fbcp_PmEDWTIs-pT4Y16sngccgyZY47b-W51HQJRqCNJ-k2O9FAcceQsomNsgBr8M1ATbJAoTdgyV2sZQJBHKueji5T96nAy-z5-vSAE7Y38gbNBDo8xGo-FZxXtQoGcYFVRm00) -The response returned by the OAuth2 server to the token introspection request is the the resolved identity appended to the authorization JSON. +The response returned by the OAuth2 server to the token introspection request is the resolved identity appended to the authorization JSON. ### OpenShift OAuth (user-echo endpoint) (`identity.openshift`) @@ -254,9 +254,9 @@ Authorino can verify x509 certificates presented by clients for authentication o Trusted root Certificate Authorities (CA) are stored in Kubernetes Secrets labeled according to selectors specified in the AuthConfig, watched and indexed by Authorino. Make sure to create proper `kubernetes.io/tls`-typed Kubernetes Secrets, containing the public certificates of the CA stored in either a `tls.crt` or `ca.crt` entry inside the secret. -Truested root CA secrets must be created in the same namespace of the `AuthConfig` (default) or `spec.identity.mtls.allNamespaces` must be set to `true` (only works with [cluster-wide Authorino instances](./architecture.md#cluster-wide-vs-namespaced-instances)). +Trusted root CA secrets must be created in the same namespace of the `AuthConfig` (default) or `spec.identity.mtls.allNamespaces` must be set to `true` (only works with [cluster-wide Authorino instances](./architecture.md#cluster-wide-vs-namespaced-instances)). -The identitiy object resolved out of a client x509 certificate is equal to the subject field of the certificate, and it serializes as JSON within the Authorization JSON usually as follows: +The identity object resolved out of a client x509 certificate is equal to the subject field of the certificate, and it serializes as JSON within the Authorization JSON usually as follows: ```jsonc { @@ -332,7 +332,7 @@ spec: - name: jwt oidc: { endpoint: ... } - name: anonymous - priority: 1 # expired oidc token, missing creds, etc default to anonymous access + priority: 1 # expired oidc token, missing creds, etc. default to anonymous access anonymous: {} authorization: - name: read-only-access-if-authn-fails @@ -359,20 +359,20 @@ All the identity verification methods supported by Authorino can be configured r By default, authentication secrets are expected to be supplied in the `Authorization` HTTP header, with the `Bearer` prefix and plain authentication secret, separated by space. The full list of supported options for the location of authentication secrets and selector is specified in the table below: -| Location (`credentials.in`) | Description | Selector (`credentials.keySelector`) | -| --------------------------- | ---------------------------- | ------------------------------------------------ | -| `authorization_header` | `Authorization` HTTP header | Prefix (default: `Bearer`) | -| `custom_header` | Custom HTTP header | Name of the header. Value should have no prefix. | -| `query` | Query string parameter | Name of the parameter | -| `cookie` | Cookie header | ID of the cookie entry | +| Location (`credentials.in`) | Description | Selector (`credentials.keySelector`) | +|-----------------------------|-----------------------------|--------------------------------------------------| +| `authorization_header` | `Authorization` HTTP header | Prefix (default: `Bearer`) | +| `custom_header` | Custom HTTP header | Name of the header. Value should have no prefix. | +| `query` | Query string parameter | Name of the parameter | +| `cookie` | Cookie header | ID of the cookie entry | ### _Extra:_ Identity extension ([`extendedProperties`](https://pkg.go.dev/github.com/kuadrant/authorino/api/v1beta1?utm_source=gopls#Identity)) Resolved identity objects can be extended with user-defined JSON properties. Values can be static or fetched from the Authorization JSON. -A typical use-case for this feature is token normalization. Say you have more than one identity source listed in the your `AuthConfig` but each source issues an access token with a different JSON structure – e.g. two OIDC issuers that use different names for custom JWT claims of similar meaning; when two different identity verification/authentication methods are combined, such as API keys (whose identity objects are the corresponding Kubernetes `Secret`s) and Kubernetes tokens (whose identity objects are Kubernetes UserInfo data). +A typical use-case for this feature is token normalization. Say you have more than one identity source listed in your `AuthConfig` but each source issues an access token with a different JSON structure – e.g. two OIDC issuers that use different names for custom JWT claims of similar meaning; when two different identity verification/authentication methods are combined, such as API keys (whose identity objects are the corresponding Kubernetes `Secret`s) and Kubernetes tokens (whose identity objects are Kubernetes UserInfo data). -In such cases, identity extension can be used to normalize the token so it always includes the same set of JSON properties of interest, regardless of the source of identity that issued the original token verified by Authorino. This simplifies the writing of authorization policies and configuration of dynamic responses. +In such cases, identity extension can be used to normalize the token to always include the same set of JSON properties of interest, regardless of the source of identity that issued the original token verified by Authorino. This simplifies the writing of authorization policies and configuration of dynamic responses. In case of extending an existing property of the identity object (replacing), the API allows to control whether to overwrite the value or not. This is particularly useful for normalizing tokens of a same identity source that nonetheless may occasionally differ in structure, such as in the case of JWT claims that sometimes may not be present but can be safely replaced with another (e.g. `username` or `sub`). @@ -380,7 +380,7 @@ In case of extending an existing property of the identity object (replacing), th ### HTTP GET/GET-by-POST ([`metadata.http`](https://pkg.go.dev/github.com/kuadrant/authorino/api/v1beta1?utm_source=gopls#Metadata_GenericHTTP)) -Generic HTTP adapter that sends a request to an external service. It can be used to fetch external metadata for the authorization policies (phase ii of the Authorino [Auth Pipeline](./architecture.md#the-auth-pipeline)), or as a web hook. +Generic HTTP adapter that sends a request to an external service. It can be used to fetch external metadata for the authorization policies (phase ii of the Authorino [Auth Pipeline](./architecture.md#the-auth-pipeline-aka-enforcing-protection-in-request-time)), or as a web hook. The adapter allows issuing requests either by GET or POST methods; in both cases with URL and parameters defined by the user in the spec. Dynamic values fetched from the Authorization JSON can be used. @@ -394,7 +394,7 @@ Custom headers can be set with the `headers` field. Nevertheless, headers such a ### OIDC UserInfo ([`metadata.userInfo`](https://pkg.go.dev/github.com/kuadrant/authorino/api/v1beta1?utm_source=gopls#Metadata_UserInfo)) -Online fetching of OpenID Connect (OIDC) UserInfo data (phase ii of the Authorino [Auth Pipeline](./architecture.md#the-auth-pipeline)), associated with an OIDC identity source configured and resolved in phase (i). +Online fetching of OpenID Connect (OIDC) UserInfo data (phase ii of the Authorino [Auth Pipeline](./architecture.md#the-auth-pipeline-aka-enforcing-protection-in-request-time)), associated with an OIDC identity source configured and resolved in phase (i). Apart from possibly complementing information of the JWT, fetching OpenID Connect UserInfo in request-time can be particularly useful for remote checking the state of the session, as opposed to only verifying the JWT/JWS offline. @@ -412,9 +412,9 @@ A UMA-compliant server is an external authorization server (e.g., Keycloak) wher ![UMA](http://www.plantuml.com/plantuml/png/ZOx1IWCn48RlUOgX9pri7w0GxOBYGGGj5G_Y8QHJTp2PgPE9qhStmhBW9NWSvll__ziM2ser9rS-Y4z1GuOiB75IoGYc5Ptp7dOOXICb2aR2Wr5xUk_6QfCeiS1m1QldXn4AwXVg2ZRmUzrGYTBki_lp71gzH1lwWYaDzopV357uIE-EnH0I7cq3CSG9dLklrxF9PyLY_rAOMNWSzts11dIBdYhg6HIBL8rOuEAwAlbJiEcoN_pQj9VOMtVZxdQ_BFHBTpC5Xs31RP4FDQSV) -It's important to notice that Authorino does NOT manage resources in the UMA-compliant server. As shown in the flow above, Authorino's UMA client is only to fetch data about the requested resources. Authorino exchanges client credentials for a Protected API Token (PAT), then queries for resources whose URI match the path of the HTTP request (as passed to Authorino by the Envoy proxy) and fetches data of each macthing resource. +It's important to notice that Authorino does NOT manage resources in the UMA-compliant server. As shown in the flow above, Authorino's UMA client is only to fetch data about the requested resources. Authorino exchanges client credentials for a Protected API Token (PAT), then queries for resources whose URI match the path of the HTTP request (as passed to Authorino by the Envoy proxy) and fetches data of each matching resource. -The resources data is added as metadata of the authorization payload and passed as input for the configured authorization policies. All resources returned by the UMA-compliant server in the query by URI are passed along. They are available in the PDPs (authorization payload) as `input.auth.metadata.custom-name => Array`. (See [The "Auth Pipeline"](./architecture.md#the-auth-pipeline) for details.) +The resources data is added as metadata of the authorization payload and passed as input for the configured authorization policies. All resources returned by the UMA-compliant server in the query by URI are passed along. They are available in the PDPs (authorization payload) as `input.auth.metadata.custom-name => Array`. (See [The "Auth Pipeline"](./architecture.md#the-auth-pipeline-aka-enforcing-protection-in-request-time) for details.) ## Authorization features ([`authorization`](https://pkg.go.dev/github.com/kuadrant/authorino/api/v1beta1?utm_source=gopls#Authorization)) @@ -440,7 +440,7 @@ spec: value: "true" - patternRef: admin - pattterns: + patterns: admin: # a named pattern that can be reused in other sets of rules or conditions - selector: auth.identity.roles operator: incl @@ -465,7 +465,7 @@ An optional field `allValues: boolean` makes the values of all rules declared in Access control enforcement based on rules defined in the Kubernetes authorization system, i.e. `Role`, `ClusterRole`, `RoleBinding` and `ClusterRoleBinding` resources of Kubernetes RBAC. -Authorino issues a [SubjectAccessReview](https://kubernetes.io/docs/reference/kubernetes-api/authorization-resources/subject-access-review-v1) (SAR) inquiry that checks with the underlying Kubernetes server whether the user can access a particular resource, resurce kind or generic URL. +Authorino issues a [SubjectAccessReview](https://kubernetes.io/docs/reference/kubernetes-api/authorization-resources/subject-access-review-v1) (SAR) inquiry that checks with the underlying Kubernetes server whether the user can access a particular resource, resource kind or generic URL. It supports **resource attributes authorization check** (parameters defined in the `AuthConfig`) and **non-resource attributes authorization check** (HTTP endpoint inferred from the original request). - Resource attributes: adequate for permissions set at namespace level, defined in terms of common attributes of operations on Kubernetes resources (namespace, API group, kind, name, subresource, verb) @@ -496,20 +496,20 @@ rules: verbs: ["put", "delete"] ``` -Kubernetes authorization policy configs look like the following in an Authorino `AuthConfig`: +Kubernetes' authorization policy configs look like the following in an Authorino `AuthConfig`: ```yaml authorization: - name: kubernetes-rbac kubernetes: user: - valueFrom: # values of the parameter can be fixed (`value`) or fetched from the Auhtorization JSON (`valueFrom.authJSON`) + valueFrom: # values of the parameter can be fixed (`value`) or fetched from the Authorization JSON (`valueFrom.authJSON`) authJSON: auth.identity.metadata.annotations.userid groups: [] # user groups to test for. # for resource attributes permission checks; omit it to perform a non-resource attributes SubjectAccessReview with path and method/verb assumed from the original request - # if included, use the resource attributes, where the values for each parameter can be fixed (`value`) or fetched from the Auhtorization JSON (`valueFrom.authJSON`) + # if included, use the resource attributes, where the values for each parameter can be fixed (`value`) or fetched from the Authorization JSON (`valueFrom.authJSON`) resourceAttributes: namespace: value: default @@ -738,7 +738,7 @@ rate_limits: ### _Extra:_ Custom denial status ([`denyWith`](https://pkg.go.dev/github.com/kuadrant/authorino/api/v1beta1?utm_source=gopls#DenyWith)) -By default, Authorino will inform Envoy to respond with `401 Unauthorized` or `403 Forbidden` respectively when the identity verification (phase i of the [Auth Pipeline](./architecture.md#the-auth-pipeline)) or authorization (phase ii) fail. These can be customized by specifying `spec.denyWith` in the `AuthConfig`. +By default, Authorino will inform Envoy to respond with `401 Unauthorized` or `403 Forbidden` respectively when the identity verification (phase i of the [Auth Pipeline](./architecture.md#the-auth-pipeline-aka-enforcing-protection-in-request-time)) or authorization (phase ii) fail. These can be customized by specifying `spec.denyWith` in the `AuthConfig`. ## Callbacks (`callbacks`) @@ -872,15 +872,15 @@ spec: For the `AuthConfig` above, -- Identity configs `tier-2` and `tier-3` (priority 1) will only trigger (concurrently) in case `tier-1` (priority 0) fails to validate the authentication token first. (This behavior happens without perjudice of context canceling between concurrent evaluators – i.e. evaluators that _are_ triggered concurrently to another, such as `tier-2` and `tier-3`, continue to cancel the context of each other if any of them succeeds validating the token first.) +- Identity configs `tier-2` and `tier-3` (priority 1) will only trigger (concurrently) in case `tier-1` (priority 0) fails to validate the authentication token first. (This behavior happens without prejudice of context canceling between concurrent evaluators – i.e. evaluators that _are_ triggered concurrently to another, such as `tier-2` and `tier-3`, continue to cancel the context of each other if any of them succeeds validating the token first.) - Metadata source `second` (priority 1) uses the response of the request issued by metadata source `first` (priority 0), so it will wait for `first` to finish by triggering only in the second block. -- Authorization policy `allowed-endpoints` (piority 0) is considered to be a lot less expensive than `more-expensive-policy` (priority 1) and has a high chance of denying access to the protected service (if the path is not one of the allowed endpoints). By setting different priorities to these policies we ensure the more expensive policy if triggered in sequence of the less expensive one, instead of concurrently. +- Authorization policy `allowed-endpoints` (priority 0) is considered to be a lot less expensive than `more-expensive-policy` (priority 1) and has a high chance of denying access to the protected service (if the path is not one of the allowed endpoints). By setting different priorities to these policies we ensure the more expensive policy if triggered in sequence of the less expensive one, instead of concurrently. ## Common feature: Conditions (`when`) -_Conditions_, named `when` in the AUthCOnfig API, are sets of expressions (JSON patterns) that, whenever included, must evaluate to true against the [Authorization JSON](./architecture.md#the-authorization-json), so the scope where the expressions are defined is enforced. If any of the expressions in the set of conditions for a given scope does not match, Authorino will skip that scope in the [Auth Pipeline](./architecture.md#the-auth-pipeline). +_Conditions_, named `when` in the AuthConfig API, are sets of expressions (JSON patterns) that, whenever included, must evaluate to true against the [Authorization JSON](./architecture.md#the-authorization-json), so the scope where the expressions are defined is enforced. If any of the expressions in the set of conditions for a given scope does not match, Authorino will skip that scope in the [Auth Pipeline](./architecture.md#the-auth-pipeline-aka-enforcing-protection-in-request-time). The scope for a set of `when` conditions can be the entire `AuthConfig` ("top-level conditions") or a particular evaluator of any phase of the auth pipeline. @@ -911,7 +911,7 @@ spec: - name: metadata-source http: endpoint: https://my-metadata-source.io - when: # only fetch the external metadata if the context is HTTP method different than OPTIONS + when: # only fetch the external metadata if the context is HTTP method other than OPTIONS - selector: context.request.http.method operator: neq value: OPTIONS @@ -992,7 +992,7 @@ spec: identity: - name: jwt when: - - selector: selector: context.request.http.headers.authorization + - selector: context.request.http.headers.authorization operator: matches value: JWT .+ oidc: {...} @@ -1009,7 +1009,7 @@ spec: Objects resolved at runtime in an [Auth Pipeline](./architecture.md#the-auth-pipeline-aka-enforcing-protection-in-request-time) can be cached "in-memory", and avoided being evaluated again at a subsequent request, until it expires. A lookup cache key and a TTL can be set individually for any evaluator config in an AuthConfig. -Each cache config induces a completely independent cache table (or "cache namespace"). Consequently, different evaluator configs can use the same cache key and there will be no colision between entries from different evaluators. +Each cache config induces a completely independent cache table (or "cache namespace"). Consequently, different evaluator configs can use the same cache key and there will be no collision between entries from different evaluators. E.g.: @@ -1043,7 +1043,7 @@ spec: The example above sets caching for the 'external-metadata' metadata config and for the 'complex-policy' authorization policy. In the case of 'external-metadata', the cache key is the path of the original HTTP request being authorized by Authorino (fetched dynamically from the [Authorization JSON](./architecture.md#the-authorization-json)); i.e., after obtaining a metadata object from the external source for a given contextual HTTP path one first time, whenever that same HTTP path repeats in a subsequent request, Authorino will use the cached object instead of sending a request again to the external source of metadata. After 5 minutes (300 seconds), the cache entry will expire and Authorino will fetch again from the source if requested. -As for the 'complex-policy' authorization policy, the cache key is a string composed the 'group' the identity belongs to, the methodd of the HTTP request and the path of the HTTP request. Whenever these repeat, Authorino will use the result of the policy that was evaluated and cached priorly. Cache entries in this namespace expire after 60 seconds. +As for the 'complex-policy' authorization policy, the cache key is a string composed the 'group' the identity belongs to, the method of the HTTP request and the path of the HTTP request. Whenever these repeat, Authorino will use the result of the policy that was evaluated and cached priorly. Cache entries in this namespace expire after 60 seconds. **Notes on evaluator caching** @@ -1062,7 +1062,7 @@ apiVersion: authorino.kuadrant.io/v1beta1 kind: AuthConfig metadata: name: my-authconfig - namespame: my-ns + namespace: my-ns spec: metadata: - name: my-external-metadata diff --git a/docs/getting-started.md b/docs/getting-started.md index 22e8ef2e..2acffc18 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -1,6 +1,6 @@ # Getting started -This page covers requirements and instructions to deploy Authorino on a Kubernetes cluster, as well as the steps to declare, apply and try out a protection layer of authentication and authorization over your service, clean-up and complete uninstall. +This page covers requirements and instructions to deploy Authorino on a Kubernetes cluster, as well as the steps to declare, apply and try out a protection layer of authentication and authorization over your service, clean-up and complete uninstallation. If you prefer learning with an example, check out our [Hello World](./user-guides/hello-world.md). @@ -14,14 +14,14 @@ If you prefer learning with an example, check out our [Hello World](./user-guide ### Platform requirements -These are the plarform requirements to use Authorino: +These are the platform requirements to use Authorino: - [**Kubernetes**](https://kubernetes.io) server (recommended v1.20 or later), with permission to create Kubernetes Custom Resource Definitions (CRDs) (for bootstrapping Authorino and Authorino Operator)
Alternative: K8s distros and platforms - Alternatively to upstream Kubernetes, you should be able use any other Kubernetes distribution or Kubernetes Management Platform (KMP) with support for Kubernetes Custom Resources Definitions (CRD) and custom controllers, such as Red Hat OpenShift, IBM Cloud Kubernetes Service (IKS), Google Kubernetes Engine (GKE), Amazon Elastic Kubernetes Service (EKS) and Azure Kubernetes Service (AKS). + Alternatively to upstream Kubernetes, you should be able to use any other Kubernetes distribution or Kubernetes Management Platform (KMP) with support for Kubernetes Custom Resources Definitions (CRD) and custom controllers, such as Red Hat OpenShift, IBM Cloud Kubernetes Service (IKS), Google Kubernetes Engine (GKE), Amazon Elastic Kubernetes Service (EKS) and Azure Kubernetes Service (AKS).
- [**Envoy**](https://www.envoyproxy.io) proxy (recommended v1.19 or later), to wire up Upstream services (i.e. the services to be protected with Authorino) and external authorization filter (Authorino) for integrations based on the reverse-proxy architecture - [example](https://github.com/kuadrant/authorino-examples#envoy) @@ -29,7 +29,7 @@ These are the plarform requirements to use Authorino:
Alternative: Non-reverse-proxy integration - Technically, any client that implements Envoy's external authorization gRPC protocol should be compatible with Authorino. For integrations based on the reverse-proxy architecture nevertheless, we strongly recommended that you leverage Envoy along side Authorino. + Technically, any client that implements Envoy's external authorization gRPC protocol should be compatible with Authorino. For integrations based on the reverse-proxy architecture nevertheless, we strongly recommended that you leverage Envoy alongside Authorino.
### Feature-specific requirements @@ -40,7 +40,7 @@ A few examples are: - For **Kubernetes authentication** tokens, platform support for the TokenReview and SubjectAccessReview APIs of Kubernetes shall be required. In case you want to be able to requests access tokens for clients running outside the custer, you may also want to check out the requisites for using Kubernetes [TokenRequest API](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.20/#tokenrequest-v1-storage-k8s-io) (GA in v1.20). -- For **User-Managed Access (UMA)** resource data, you will need a UMA-compliant server running as well. This can be an implementation of the UMA protocol by each upstream API itself or (more tipically) an external server that knows about the resources. Again, Keycloak can be a good fit here as well. Just keep in mind that, whatever resource server you choose, changing-state actions commanded in the upstream APIs or other parties will have to be reflected in the resource server. Authorino will not do that for you. +- For **User-Managed Access (UMA)** resource data, you will need a UMA-compliant server running as well. This can be an implementation of the UMA protocol by each upstream API itself or (more typically) an external server that knows about the resources. Again, Keycloak can be a good fit here as well. Just keep in mind that, whatever resource server you choose, changing-state actions commanded in the upstream APIs or other parties will have to be reflected in the resource server. Authorino will not do that for you. Check out the [Feature specification](./features.md) page for more feature-specific requirements. @@ -296,7 +296,7 @@ spec: - --component-log-level filter:trace,http:debug,router:debug ports: - name: web - containerPort: 8000 # matches the adddress of the listener in the envoy config + containerPort: 8000 # matches the address of the listener in the envoy config volumeMounts: - name: config mountPath: /usr/local/etc/envoy @@ -344,7 +344,7 @@ For examples based on specific use-cases, check out the [User guides](./user-gui For authentication based on OpenID Connect (OIDC) JSON Web Tokens (JWT), plus one simple JWT claim authorization check, a typical `AuthConfig` custom resource looks like the following: -```yaml +```sh kubectl -n myapp apply -f -< -Exchange satellite (outer-layer) authentication tokens for "Festival Wristbands" accepted ubiquitously at the inside of your network. Normalize from multiple and varied sources of identity and authentication methods in the edge of your architecture; filter privacy data, limit the scope of permissions, and simplify authorization rules to your internal micro-services. +Exchange satellite (outer-layer) authentication tokens for "Festival Wristbands" accepted ubiquitously at the inside of your network. Normalize from multiple and varied sources of identity and authentication methods in the edge of your architecture; filter privacy data, limit the scope of permissions, and simplify authorization rules to your internal microservices. - **[Fetching auth metadata from external sources](./user-guides/external-metadata.md)**
Get online data from remote HTTP services to enhance authorization rules. diff --git a/docs/user-guides/anonymous-access.md b/docs/user-guides/anonymous-access.md index 13d1dd2c..208d8f5e 100644 --- a/docs/user-guides/anonymous-access.md +++ b/docs/user-guides/anonymous-access.md @@ -57,13 +57,13 @@ spec: EOF ``` -The command above will deploy Authorino as a separate service (as oposed to a sidecar of the protected API and other architectures), in `namespaced` reconciliation mode, and with TLS termination disabled. For other variants and deployment options, check out the [Getting Started](./../getting-started.md#2-deploy-an-authorino-instance) section of the docs, the [Architecture](./../architecture.md#topologies) page, and the spec for the [`Authorino`](https://github.com/Kuadrant/authorino-operator/blob/main/config/crd/bases/operator.authorino.kuadrant.io_authorinos.yaml) CRD in the Authorino Operator repo. +The command above will deploy Authorino as a separate service (as opposed to a sidecar of the protected API and other architectures), in `namespaced` reconciliation mode, and with TLS termination disabled. For other variants and deployment options, check out the [Getting Started](./../getting-started.md#step-request-an-authorino-instance) section of the docs, the [Architecture](./../architecture.md#topologies) page, and the spec for the [`Authorino`](https://github.com/Kuadrant/authorino-operator/blob/main/config/crd/bases/operator.authorino.kuadrant.io_authorinos.yaml) CRD in the Authorino Operator repo. ## 4. Setup Envoy The following bundle from the Authorino examples (manifest referred in the command below) is to apply Envoy configuration and deploy Envoy proxy, that wire up the Talker API behind the reverse-proxy and external authorization with the Authorino instance. -For details and instructions to setup Envoy manually, see _Protect a service > Setup Envoy_ in the [Getting Started](./../getting-started.md#1-setup-envoy) page. For a simpler and straighforward way to manage an API, without having to manually install or configure Envoy and Authorino, check out [Kuadrant](https://github.com/kuadrant). +For details and instructions to setup Envoy manually, see _Protect a service > Setup Envoy_ in the [Getting Started](./../getting-started.md#step-setup-envoy) page. For a simpler and straightforward way to manage an API, without having to manually install or configure Envoy and Authorino, check out [Kuadrant](https://github.com/kuadrant). ```sh kubectl apply -f https://raw.githubusercontent.com/kuadrant/authorino-examples/main/envoy/envoy-notls-deploy.yaml diff --git a/docs/user-guides/api-key-authentication.md b/docs/user-guides/api-key-authentication.md index 988f0810..9947409d 100644 --- a/docs/user-guides/api-key-authentication.md +++ b/docs/user-guides/api-key-authentication.md @@ -61,13 +61,13 @@ spec: EOF ``` -The command above will deploy Authorino as a separate service (as oposed to a sidecar of the protected API and other architectures), in `namespaced` reconciliation mode, and with TLS termination disabled. For other variants and deployment options, check out the [Getting Started](./../getting-started.md#2-deploy-an-authorino-instance) section of the docs, the [Architecture](./../architecture.md#topologies) page, and the spec for the [`Authorino`](https://github.com/Kuadrant/authorino-operator/blob/main/config/crd/bases/operator.authorino.kuadrant.io_authorinos.yaml) CRD in the Authorino Operator repo. +The command above will deploy Authorino as a separate service (as opposed to a sidecar of the protected API and other architectures), in `namespaced` reconciliation mode, and with TLS termination disabled. For other variants and deployment options, check out the [Getting Started](./../getting-started.md#step-request-an-authorino-instance) section of the docs, the [Architecture](./../architecture.md#topologies) page, and the spec for the [`Authorino`](https://github.com/Kuadrant/authorino-operator/blob/main/config/crd/bases/operator.authorino.kuadrant.io_authorinos.yaml) CRD in the Authorino Operator repo. ## 4. Setup Envoy The following bundle from the Authorino examples (manifest referred in the command below) is to apply Envoy configuration and deploy Envoy proxy, that wire up the Talker API behind the reverse-proxy and external authorization with the Authorino instance. -For details and instructions to setup Envoy manually, see _Protect a service > Setup Envoy_ in the [Getting Started](./../getting-started.md#1-setup-envoy) page. For a simpler and straighforward way to manage an API, without having to manually install or configure Envoy and Authorino, check out [Kuadrant](https://github.com/kuadrant). +For details and instructions to setup Envoy manually, see _Protect a service > Setup Envoy_ in the [Getting Started](./../getting-started.md#step-setup-envoy) page. For a simpler and straightforward way to manage an API, without having to manually install or configure Envoy and Authorino, check out [Kuadrant](https://github.com/kuadrant). ```sh kubectl apply -f https://raw.githubusercontent.com/kuadrant/authorino-examples/main/envoy/envoy-notls-deploy.yaml diff --git a/docs/user-guides/authenticated-rate-limiting-envoy-dynamic-metadata.md b/docs/user-guides/authenticated-rate-limiting-envoy-dynamic-metadata.md index 0d16cb65..e5fd6168 100644 --- a/docs/user-guides/authenticated-rate-limiting-envoy-dynamic-metadata.md +++ b/docs/user-guides/authenticated-rate-limiting-envoy-dynamic-metadata.md @@ -63,7 +63,7 @@ spec: EOF ``` -The command above will deploy Authorino as a separate service (as oposed to a sidecar of the protected API and other architectures), in `namespaced` reconciliation mode, and with TLS termination disabled. For other variants and deployment options, check out the [Getting Started](./../getting-started.md#2-deploy-an-authorino-instance) section of the docs, the [Architecture](./../architecture.md#topologies) page, and the spec for the [`Authorino`](https://github.com/Kuadrant/authorino-operator/blob/main/config/crd/bases/operator.authorino.kuadrant.io_authorinos.yaml) CRD in the Authorino Operator repo. +The command above will deploy Authorino as a separate service (as opposed to a sidecar of the protected API and other architectures), in `namespaced` reconciliation mode, and with TLS termination disabled. For other variants and deployment options, check out the [Getting Started](./../getting-started.md#step-request-an-authorino-instance) section of the docs, the [Architecture](./../architecture.md#topologies) page, and the spec for the [`Authorino`](https://github.com/Kuadrant/authorino-operator/blob/main/config/crd/bases/operator.authorino.kuadrant.io_authorinos.yaml) CRD in the Authorino Operator repo. ## 4. Deploy Limitador @@ -79,7 +79,7 @@ kubectl apply -f https://raw.githubusercontent.com/kuadrant/authorino-examples/m The following bundle from the Authorino examples (manifest referred in the command below) is to apply Envoy configuration and deploy Envoy proxy, that wire up the Talker API behind the reverse-proxy and external authorization with the Authorino instance. -For details and instructions to setup Envoy manually, see _Protect a service > Setup Envoy_ in the [Getting Started](./../getting-started.md#1-setup-envoy) page. For a simpler and straighforward way to manage an API, without having to manually install or configure Envoy and Authorino, check out [Kuadrant](https://github.com/kuadrant). +For details and instructions to setup Envoy manually, see _Protect a service > Setup Envoy_ in the [Getting Started](./../getting-started.md#step-setup-envoy) page. For a simpler and straightforward way to manage an API, without having to manually install or configure Envoy and Authorino, check out [Kuadrant](https://github.com/kuadrant). ```sh kubectl apply -f https://raw.githubusercontent.com/kuadrant/authorino-examples/main/envoy/envoy-notls-deploy.yaml diff --git a/docs/user-guides/authzed.md b/docs/user-guides/authzed.md index eb663028..9f985490 100644 --- a/docs/user-guides/authzed.md +++ b/docs/user-guides/authzed.md @@ -56,13 +56,13 @@ spec: EOF ``` -The command above will deploy Authorino as a separate service (as oposed to a sidecar of the protected API and other architectures), in `namespaced` reconciliation mode, and with TLS termination disabled. For other variants and deployment options, check out the [Getting Started](./../getting-started.md#2-deploy-an-authorino-instance) section of the docs, the [Architecture](./../architecture.md#topologies) page, and the spec for the [`Authorino`](https://github.com/Kuadrant/authorino-operator/blob/main/config/crd/bases/operator.authorino.kuadrant.io_authorinos.yaml) CRD in the Authorino Operator repo. +The command above will deploy Authorino as a separate service (as opposed to a sidecar of the protected API and other architectures), in `namespaced` reconciliation mode, and with TLS termination disabled. For other variants and deployment options, check out the [Getting Started](./../getting-started.md#step-request-an-authorino-instance) section of the docs, the [Architecture](./../architecture.md#topologies) page, and the spec for the [`Authorino`](https://github.com/Kuadrant/authorino-operator/blob/main/config/crd/bases/operator.authorino.kuadrant.io_authorinos.yaml) CRD in the Authorino Operator repo. ## 4. Setup Envoy The following bundle from the Authorino examples (manifest referred in the command below) is to apply Envoy configuration and deploy Envoy proxy, that wire up the Talker API behind the reverse-proxy and external authorization with the Authorino instance. -For details and instructions to setup Envoy manually, see _Protect a service > Setup Envoy_ in the [Getting Started](./../getting-started.md#1-setup-envoy) page. For a simpler and straighforward way to manage an API, without having to manually install or configure Envoy and Authorino, check out [Kuadrant](https://github.com/kuadrant). +For details and instructions to setup Envoy manually, see _Protect a service > Setup Envoy_ in the [Getting Started](./../getting-started.md#step-setup-envoy) page. For a simpler and straightforward way to manage an API, without having to manually install or configure Envoy and Authorino, check out [Kuadrant](https://github.com/kuadrant). ```sh kubectl apply -f https://raw.githubusercontent.com/kuadrant/authorino-examples/main/envoy/envoy-notls-deploy.yaml @@ -74,7 +74,7 @@ The bundle also creates an `Ingress` with host name `talker-api-authorino.127.0. kubectl port-forward deployment/envoy 8000:8000 & ``` -## 5. Create the permission data base +## 5. Create the permission database Create the namespace: diff --git a/docs/user-guides/caching.md b/docs/user-guides/caching.md index 0d42739a..f9dae05d 100644 --- a/docs/user-guides/caching.md +++ b/docs/user-guides/caching.md @@ -74,13 +74,13 @@ spec: EOF ``` -The command above will deploy Authorino as a separate service (as oposed to a sidecar of the protected API and other architectures), in `namespaced` reconciliation mode, and with TLS termination disabled. For other variants and deployment options, check out the [Getting Started](./../getting-started.md#2-deploy-an-authorino-instance) section of the docs, the [Architecture](./../architecture.md#topologies) page, and the spec for the [`Authorino`](https://github.com/Kuadrant/authorino-operator/blob/main/config/crd/bases/operator.authorino.kuadrant.io_authorinos.yaml) CRD in the Authorino Operator repo. +The command above will deploy Authorino as a separate service (as opposed to a sidecar of the protected API and other architectures), in `namespaced` reconciliation mode, and with TLS termination disabled. For other variants and deployment options, check out the [Getting Started](./../getting-started.md#step-request-an-authorino-instance) section of the docs, the [Architecture](./../architecture.md#topologies) page, and the spec for the [`Authorino`](https://github.com/Kuadrant/authorino-operator/blob/main/config/crd/bases/operator.authorino.kuadrant.io_authorinos.yaml) CRD in the Authorino Operator repo. ## 4. Setup Envoy The following bundle from the Authorino examples (manifest referred in the command below) is to apply Envoy configuration and deploy Envoy proxy, that wire up the Talker API behind the reverse-proxy and external authorization with the Authorino instance. -For details and instructions to setup Envoy manually, see _Protect a service > Setup Envoy_ in the [Getting Started](./../getting-started.md#1-setup-envoy) page. For a simpler and straighforward way to manage an API, without having to manually install or configure Envoy and Authorino, check out [Kuadrant](https://github.com/kuadrant). +For details and instructions to setup Envoy manually, see _Protect a service > Setup Envoy_ in the [Getting Started](./../getting-started.md#step-setup-envoy) page. For a simpler and straightforward way to manage an API, without having to manually install or configure Envoy and Authorino, check out [Kuadrant](https://github.com/kuadrant). ```sh kubectl apply -f https://raw.githubusercontent.com/kuadrant/authorino-examples/main/envoy/envoy-notls-deploy.yaml @@ -137,13 +137,13 @@ spec: EOF ``` -The example above enables caching for the external source of metadata, which in this case, for convinience, is the same upstream API protected by Authorino (i.e. the Talker API), though consumed directly by Authorino, without passing through the proxy. This API generates a `uuid` random hash that it injects in the JSON response. This value is different in every request processed by ythe API. +The example above enables caching for the external source of metadata, which in this case, for convenience, is the same upstream API protected by Authorino (i.e. the Talker API), though consumed directly by Authorino, without passing through the proxy. This API generates a `uuid` random hash that it injects in the JSON response. This value is different in every request processed by the API. The example also enables caching of returned OPA virtual documents. `cached-authz` is a trivial Rego policy that always grants access, but generates a timestamp, which Authorino will cache. In both cases, the path of the HTTP request is used as cache key. I.e., whenever the path repeats, Authorino reuse the values stored previously in each cache table (`cached-metadata` and `cached-authz`), respectively saving a request to the external source of metadata and the evaluation of the OPA policy. Cache entries will expire in both cases after 60 seconds they were stored in the cache. -The cached values will be visible in the response returned by the Talker API in `x-authz-data` header injected by Authorino. Thiis way, we can tell when an existing value in the cache was used and when a new one was generated and stored. +The cached values will be visible in the response returned by the Talker API in `x-authz-data` header injected by Authorino. This way, we can tell when an existing value in the cache was used and when a new one was generated and stored. ## 6. Consume the API diff --git a/docs/user-guides/deny-with-redirect-to-login.md b/docs/user-guides/deny-with-redirect-to-login.md index 5fad3f81..ab58220c 100644 --- a/docs/user-guides/deny-with-redirect-to-login.md +++ b/docs/user-guides/deny-with-redirect-to-login.md @@ -63,13 +63,13 @@ spec: EOF ``` -The command above will deploy Authorino as a separate service (as oposed to a sidecar of the protected API and other architectures), in `namespaced` reconciliation mode, and with TLS termination disabled. For other variants and deployment options, check out the [Getting Started](./../getting-started.md#2-deploy-an-authorino-instance) section of the docs, the [Architecture](./../architecture.md#topologies) page, and the spec for the [`Authorino`](https://github.com/Kuadrant/authorino-operator/blob/main/config/crd/bases/operator.authorino.kuadrant.io_authorinos.yaml) CRD in the Authorino Operator repo. +The command above will deploy Authorino as a separate service (as opposed to a sidecar of the protected API and other architectures), in `namespaced` reconciliation mode, and with TLS termination disabled. For other variants and deployment options, check out the [Getting Started](./../getting-started.md#step-request-an-authorino-instance) section of the docs, the [Architecture](./../architecture.md#topologies) page, and the spec for the [`Authorino`](https://github.com/Kuadrant/authorino-operator/blob/main/config/crd/bases/operator.authorino.kuadrant.io_authorinos.yaml) CRD in the Authorino Operator repo. ## 4. Setup Envoy The following bundle from the Authorino examples (manifest referred in the command below) is to apply Envoy configuration and deploy Envoy proxy, that wire up the Matrix Quotes webapp behind the reverse-proxy and external authorization with the Authorino instance. -For details and instructions to setup Envoy manually, see _Protect a service > Setup Envoy_ in the [Getting Started](./../getting-started.md#1-setup-envoy) page. For a simpler and straighforward way to manage an API, without having to manually install or configure Envoy and Authorino, check out [Kuadrant](https://github.com/kuadrant). +For details and instructions to setup Envoy manually, see _Protect a service > Setup Envoy_ in the [Getting Started](./../getting-started.md#step-setup-envoy) page. For a simpler and straightforward way to manage an API, without having to manually install or configure Envoy and Authorino, check out [Kuadrant](https://github.com/kuadrant). ```sh kubectl apply -f https://raw.githubusercontent.com/kuadrant/authorino-examples/main/matrix-quotes/envoy-deploy.yaml diff --git a/docs/user-guides/edge-authentication-architecture-festival-wristbands.md b/docs/user-guides/edge-authentication-architecture-festival-wristbands.md index a7bf4f5f..2c3a3c96 100644 --- a/docs/user-guides/edge-authentication-architecture-festival-wristbands.md +++ b/docs/user-guides/edge-authentication-architecture-festival-wristbands.md @@ -2,13 +2,13 @@ Edge Authentication Architecture (EAA) is a pattern where more than extracting authentication logics and specifics from the application codebase to a proper authN/authZ layer, this is pushed to the edge of your cloud network, without violating the Zero Trust principle nevertheless. -The very definition of "edge" is subject to discussion, but the underlying idea is that clients (e.g. API clients, IoT devices, etc) authenticate with a layer that, before moving traffic to inside the network: +The very definition of "edge" is subject to discussion, but the underlying idea is that clients (e.g. API clients, IoT devices, etc.) authenticate with a layer that, before moving traffic to inside the network: - understands the complexity of all the different methods of authentication supported; - sometimes some token normalization is involved; - eventually enforces some preliminary authorization policies; and - possibly filters data bits that are sensitive to privacy concerns (e.g. to comply with local legislation such as GRPD, CCPA, etc) -As a minimum, EAA allows to simplify authentication between applications and micro-services inside the network, as well as to reduce authorization to domain-specific rules and policies, rather than having to deal all the complexity to support all types of clients in every node. +As a minimum, EAA allows to simplify authentication between applications and microservices inside the network, as well as to reduce authorization to domain-specific rules and policies, rather than having to deal all the complexity to support all types of clients in every node.
@@ -18,7 +18,7 @@ As a minimum, EAA allows to simplify authentication between applications and mic
  • Identity verification & authentication → Identity extension
  • Identity verification & authentication → API key
  • Identity verification & authentication → OpenID Connect (OIDC) JWT/JOSE verification and validation
    • -
      +
    Festival Wristbands are OpenID Connect ID tokens (signed JWTs) issued by Authorino by the end of the Auth Pipeline, for authorized requests. It can be configured to include claims based on static values and values fetched from the [Authorization JSON](./../architecture.md#the-authorization-json). @@ -91,7 +91,7 @@ spec: EOF ``` -The command above will deploy Authorino as a separate service (as oposed to a sidecar of the protected API and other architectures), in `cluster-wide` reconciliation mode, and with TLS termination disabled. For other variants and deployment options, check out the [Getting Started](./../getting-started.md#2-deploy-an-authorino-instance) section of the docs, the [Architecture](./../architecture.md#topologies) page, and the spec for the [`Authorino`](https://github.com/Kuadrant/authorino-operator/blob/main/config/crd/bases/operator.authorino.kuadrant.io_authorinos.yaml) CRD in the Authorino Operator repo. +The command above will deploy Authorino as a separate service (as opposed to a sidecar of the protected API and other architectures), in `cluster-wide` reconciliation mode, and with TLS termination disabled. For other variants and deployment options, check out the [Getting Started](./../getting-started.md#step-request-an-authorino-instance) section of the docs, the [Architecture](./../architecture.md#topologies) page, and the spec for the [`Authorino`](https://github.com/Kuadrant/authorino-operator/blob/main/config/crd/bases/operator.authorino.kuadrant.io_authorinos.yaml) CRD in the Authorino Operator repo. ## 5. Setup the Edge @@ -99,7 +99,7 @@ The command above will deploy Authorino as a separate service (as oposed to a si The following bundle from the Authorino examples (manifest referred in the command below) is to apply Envoy configuration and deploy Envoy proxy, that wire up external authorization with the Authorino instance. -For details and instructions to setup Envoy manually, see _Protect a service > Setup Envoy_ in the [Getting Started](./../getting-started.md#1-setup-envoy) page. For a simpler and straighforward way to manage an API, without having to manually install or configure Envoy and Authorino, check out [Kuadrant](https://github.com/kuadrant). +For details and instructions to setup Envoy manually, see _Protect a service > Setup Envoy_ in the [Getting Started](./../getting-started.md#step-setup-envoy) page. For a simpler and straightforward way to manage an API, without having to manually install or configure Envoy and Authorino, check out [Kuadrant](https://github.com/kuadrant). ```sh kubectl -n edge apply -f https://raw.githubusercontent.com/kuadrant/authorino-examples/main/eaa/envoy-edge-deploy.yaml @@ -194,7 +194,7 @@ kubectl -n internal apply -f https://raw.githubusercontent.com/kuadrant/authorin The following bundle from the Authorino examples (manifest referred in the command below) is to apply Envoy configuration and deploy Envoy proxy, that wire up the Talker API behind the reverse-proxy and external authorization with the Authorino instance. -For details and instructions to setup Envoy manually, see _Protect a service > Setup Envoy_ in the [Getting Started](./../getting-started.md#1-setup-envoy) page. For a simpler and straighforward way to manage an API, without having to manually install or configure Envoy and Authorino, check out [Kuadrant](https://github.com/kuadrant). +For details and instructions to setup Envoy manually, see _Protect a service > Setup Envoy_ in the [Getting Started](./../getting-started.md#step-setup-envoy) page. For a simpler and straightforward way to manage an API, without having to manually install or configure Envoy and Authorino, check out [Kuadrant](https://github.com/kuadrant). ```sh kubectl -n internal apply -f https://raw.githubusercontent.com/kuadrant/authorino-examples/main/eaa/envoy-node-deploy.yaml diff --git a/docs/user-guides/envoy-jwt-authn-and-authorino.md b/docs/user-guides/envoy-jwt-authn-and-authorino.md index 3b98ba73..814c9954 100644 --- a/docs/user-guides/envoy-jwt-authn-and-authorino.md +++ b/docs/user-guides/envoy-jwt-authn-and-authorino.md @@ -75,13 +75,13 @@ spec: EOF ``` -The command above will deploy Authorino as a separate service (as oposed to a sidecar of the protected API and other architectures), in `namespaced` reconciliation mode, and with TLS termination disabled. For other variants and deployment options, check out the [Getting Started](./../getting-started.md#2-deploy-an-authorino-instance) section of the docs, the [Architecture](./../architecture.md#topologies) page, and the spec for the [`Authorino`](https://github.com/Kuadrant/authorino-operator/blob/main/config/crd/bases/operator.authorino.kuadrant.io_authorinos.yaml) CRD in the Authorino Operator repo. +The command above will deploy Authorino as a separate service (as opposed to a sidecar of the protected API and other architectures), in `namespaced` reconciliation mode, and with TLS termination disabled. For other variants and deployment options, check out the [Getting Started](./../getting-started.md#step-request-an-authorino-instance) section of the docs, the [Architecture](./../architecture.md#topologies) page, and the spec for the [`Authorino`](https://github.com/Kuadrant/authorino-operator/blob/main/config/crd/bases/operator.authorino.kuadrant.io_authorinos.yaml) CRD in the Authorino Operator repo. ## 4. Setup Envoy The command below creates the Envoy configuration and deploys the Envoy proxy wire up the Talker API and external authorization with Authorino. -For details and instructions to setup Envoy manually, see _Protect a service > Setup Envoy_ in the [Getting Started](./../getting-started.md#1-setup-envoy) page. For a simpler and straighforward way to manage an API, without having to manually install or configure Envoy and Authorino, check out [Kuadrant](https://github.com/kuadrant). +For details and instructions to setup Envoy manually, see _Protect a service > Setup Envoy_ in the [Getting Started](./../getting-started.md#step-setup-envoy) page. For a simpler and straightforward way to manage an API, without having to manually install or configure Envoy and Authorino, check out [Kuadrant](https://github.com/kuadrant). ```sh kubectl apply -f -< Setup Envoy_ in the [Getting Started](./../getting-started.md#1-setup-envoy) page. For a simpler and straighforward way to manage an API, without having to manually install or configure Envoy and Authorino, check out [Kuadrant](https://github.com/kuadrant). +For details and instructions to setup Envoy manually, see _Protect a service > Setup Envoy_ in the [Getting Started](./../getting-started.md#step-setup-envoy) page. For a simpler and straightforward way to manage an API, without having to manually install or configure Envoy and Authorino, check out [Kuadrant](https://github.com/kuadrant). ```sh kubectl apply -f https://raw.githubusercontent.com/kuadrant/authorino-examples/main/envoy/envoy-notls-deploy.yaml diff --git a/docs/user-guides/hello-world.md b/docs/user-guides/hello-world.md index f681d3f5..ef202083 100644 --- a/docs/user-guides/hello-world.md +++ b/docs/user-guides/hello-world.md @@ -66,7 +66,7 @@ kubectl -n hello-world apply -f https://raw.githubusercontent.com/kuadrant/autho # authorino.operator.authorino.kuadrant.io/authorino created ``` -The command above will deploy Authorino as a separate service (in contrast to as a sidecar of the Talker API and other architectures). For other variants and deployment options, check out the [Getting Started](./../getting-started.md#2-deploy-an-authorino-instance) section of the docs, the [Architecture](./../architecture.md#topologies) page, and the spec for the [`Authorino`](https://github.com/Kuadrant/authorino-operator/blob/main/config/crd/bases/operator.authorino.kuadrant.io_authorinos.yaml) CRD in the Authorino Operator repo. +The command above will deploy Authorino as a separate service (in contrast to as a sidecar of the Talker API and other architectures). For other variants and deployment options, check out the [Getting Started](./../getting-started.md#step-request-an-authorino-instance) section of the docs, the [Architecture](./../architecture.md#topologies) page, and the spec for the [`Authorino`](https://github.com/Kuadrant/authorino-operator/blob/main/config/crd/bases/operator.authorino.kuadrant.io_authorinos.yaml) CRD in the Authorino Operator repo. ## 6. Consume the API behind Envoy and Authorino diff --git a/docs/user-guides/host-override.md b/docs/user-guides/host-override.md index c63f5ccb..8d4b01d5 100644 --- a/docs/user-guides/host-override.md +++ b/docs/user-guides/host-override.md @@ -1,6 +1,6 @@ # Host override via context extension -By default, Authorino uses the host information of the HTTP request ([`Attributes.Http.Host`](https://www.envoyproxy.io/docs/envoy/latest/api-v3/service/auth/v3/attribute_context.proto#service-auth-v3-attributecontext-httprequest)) to lookup for an indexed AuthConfig to be enforced. The host info be overridden by supplying a `host` entry as a (per-route) context entension ([`Attributes.ContextExtensions`](https://www.envoyproxy.io/docs/envoy/latest/api-v3/service/auth/v3/attribute_context.proto#envoy-v3-api-field-service-auth-v3-attributecontext-context-extensions)), which takes precedence whenever present. +By default, Authorino uses the host information of the HTTP request ([`Attributes.Http.Host`](https://www.envoyproxy.io/docs/envoy/latest/api-v3/service/auth/v3/attribute_context.proto#service-auth-v3-attributecontext-httprequest)) to lookup for an indexed AuthConfig to be enforced. The host info be overridden by supplying a `host` entry as a (per-route) context extension ([`Attributes.ContextExtensions`](https://www.envoyproxy.io/docs/envoy/latest/api-v3/service/auth/v3/attribute_context.proto#envoy-v3-api-field-service-auth-v3-attributecontext-context-extensions)), which takes precedence whenever present. Overriding the host attribute of the HTTP request can be useful to support use cases such as of **path prefix-based lookup** and **wildcard subdomains lookup**. diff --git a/docs/user-guides/http-basic-authentication.md b/docs/user-guides/http-basic-authentication.md index 6643cb7c..0dc2dfe0 100644 --- a/docs/user-guides/http-basic-authentication.md +++ b/docs/user-guides/http-basic-authentication.md @@ -64,13 +64,13 @@ spec: EOF ``` -The command above will deploy Authorino as a separate service (as oposed to a sidecar of the protected API and other architectures), in `namespaced` reconciliation mode, and with TLS termination disabled. For other variants and deployment options, check out the [Getting Started](./../getting-started.md#2-deploy-an-authorino-instance) section of the docs, the [Architecture](./../architecture.md#topologies) page, and the spec for the [`Authorino`](https://github.com/Kuadrant/authorino-operator/blob/main/config/crd/bases/operator.authorino.kuadrant.io_authorinos.yaml) CRD in the Authorino Operator repo. +The command above will deploy Authorino as a separate service (as opposed to a sidecar of the protected API and other architectures), in `namespaced` reconciliation mode, and with TLS termination disabled. For other variants and deployment options, check out the [Getting Started](./../getting-started.md#step-request-an-authorino-instance) section of the docs, the [Architecture](./../architecture.md#topologies) page, and the spec for the [`Authorino`](https://github.com/Kuadrant/authorino-operator/blob/main/config/crd/bases/operator.authorino.kuadrant.io_authorinos.yaml) CRD in the Authorino Operator repo. ## 4. Setup Envoy The following bundle from the Authorino examples (manifest referred in the command below) is to apply Envoy configuration and deploy Envoy proxy, that wire up the Talker API behind the reverse-proxy and external authorization with the Authorino instance. -For details and instructions to setup Envoy manually, see _Protect a service > Setup Envoy_ in the [Getting Started](./../getting-started.md#1-setup-envoy) page. For a simpler and straighforward way to manage an API, without having to manually install or configure Envoy and Authorino, check out [Kuadrant](https://github.com/kuadrant). +For details and instructions to setup Envoy manually, see _Protect a service > Setup Envoy_ in the [Getting Started](./../getting-started.md#step-setup-envoy) page. For a simpler and straightforward way to manage an API, without having to manually install or configure Envoy and Authorino, check out [Kuadrant](https://github.com/kuadrant). ```sh kubectl apply -f https://raw.githubusercontent.com/kuadrant/authorino-examples/main/envoy/envoy-notls-deploy.yaml diff --git a/docs/user-guides/injecting-data.md b/docs/user-guides/injecting-data.md index 01b29754..935fdc1d 100644 --- a/docs/user-guides/injecting-data.md +++ b/docs/user-guides/injecting-data.md @@ -62,13 +62,13 @@ spec: EOF ``` -The command above will deploy Authorino as a separate service (as oposed to a sidecar of the protected API and other architectures), in `namespaced` reconciliation mode, and with TLS termination disabled. For other variants and deployment options, check out the [Getting Started](./../getting-started.md#2-deploy-an-authorino-instance) section of the docs, the [Architecture](./../architecture.md#topologies) page, and the spec for the [`Authorino`](https://github.com/Kuadrant/authorino-operator/blob/main/config/crd/bases/operator.authorino.kuadrant.io_authorinos.yaml) CRD in the Authorino Operator repo. +The command above will deploy Authorino as a separate service (as opposed to a sidecar of the protected API and other architectures), in `namespaced` reconciliation mode, and with TLS termination disabled. For other variants and deployment options, check out the [Getting Started](./../getting-started.md#step-request-an-authorino-instance) section of the docs, the [Architecture](./../architecture.md#topologies) page, and the spec for the [`Authorino`](https://github.com/Kuadrant/authorino-operator/blob/main/config/crd/bases/operator.authorino.kuadrant.io_authorinos.yaml) CRD in the Authorino Operator repo. ## 4. Setup Envoy The following bundle from the Authorino examples (manifest referred in the command below) is to apply Envoy configuration and deploy Envoy proxy, that wire up the Talker API behind the reverse-proxy and external authorization with the Authorino instance. -For details and instructions to setup Envoy manually, see _Protect a service > Setup Envoy_ in the [Getting Started](./../getting-started.md#1-setup-envoy) page. For a simpler and straighforward way to manage an API, without having to manually install or configure Envoy and Authorino, check out [Kuadrant](https://github.com/kuadrant). +For details and instructions to setup Envoy manually, see _Protect a service > Setup Envoy_ in the [Getting Started](./../getting-started.md#step-setup-envoy) page. For a simpler and straightforward way to manage an API, without having to manually install or configure Envoy and Authorino, check out [Kuadrant](https://github.com/kuadrant). ```sh kubectl apply -f https://raw.githubusercontent.com/kuadrant/authorino-examples/main/envoy/envoy-notls-deploy.yaml @@ -114,7 +114,7 @@ spec: - name: request-time valueFrom: authJSON: context.request.time.seconds - - name: geeting-message + - name: greeting-message valueFrom: authJSON: Hello, {auth.identity.metadata.annotations.auth-data\/name}! EOF @@ -152,7 +152,7 @@ curl -H 'Authorization: APIKEY ndyBzreUzF4zqDQsqSPMHkRhriEOtcRx' http://talker-a # "body": "", # "headers": { # … -# "X-Ext-Auth-Data": "{\"authorized\":true,\"geeting-message\":\"Hello, Rita!\",\"request-time\":1637954644}", +# "X-Ext-Auth-Data": "{\"authorized\":true,\"greeting-message\":\"Hello, Rita!\",\"request-time\":1637954644}", # }, # … # } diff --git a/docs/user-guides/json-pattern-matching-authorization.md b/docs/user-guides/json-pattern-matching-authorization.md index a3b4e9d3..9d1ef955 100644 --- a/docs/user-guides/json-pattern-matching-authorization.md +++ b/docs/user-guides/json-pattern-matching-authorization.md @@ -77,13 +77,13 @@ spec: EOF ``` -The command above will deploy Authorino as a separate service (as oposed to a sidecar of the protected API and other architectures), in `namespaced` reconciliation mode, and with TLS termination disabled. For other variants and deployment options, check out the [Getting Started](./../getting-started.md#2-deploy-an-authorino-instance) section of the docs, the [Architecture](./../architecture.md#topologies) page, and the spec for the [`Authorino`](https://github.com/Kuadrant/authorino-operator/blob/main/config/crd/bases/operator.authorino.kuadrant.io_authorinos.yaml) CRD in the Authorino Operator repo. +The command above will deploy Authorino as a separate service (as opposed to a sidecar of the protected API and other architectures), in `namespaced` reconciliation mode, and with TLS termination disabled. For other variants and deployment options, check out the [Getting Started](./../getting-started.md#step-request-an-authorino-instance) section of the docs, the [Architecture](./../architecture.md#topologies) page, and the spec for the [`Authorino`](https://github.com/Kuadrant/authorino-operator/blob/main/config/crd/bases/operator.authorino.kuadrant.io_authorinos.yaml) CRD in the Authorino Operator repo. ## 4. Setup Envoy The following bundle from the Authorino examples (manifest referred in the command below) is to apply Envoy configuration and deploy Envoy proxy, that wire up the Talker API behind the reverse-proxy and external authorization with the Authorino instance. -For details and instructions to setup Envoy manually, see _Protect a service > Setup Envoy_ in the [Getting Started](./../getting-started.md#1-setup-envoy) page. For a simpler and straighforward way to manage an API, without having to manually install or configure Envoy and Authorino, check out [Kuadrant](https://github.com/kuadrant). +For details and instructions to setup Envoy manually, see _Protect a service > Setup Envoy_ in the [Getting Started](./../getting-started.md#step-setup-envoy) page. For a simpler and straightforward way to manage an API, without having to manually install or configure Envoy and Authorino, check out [Kuadrant](https://github.com/kuadrant). ```sh kubectl apply -f https://raw.githubusercontent.com/kuadrant/authorino-examples/main/envoy/envoy-notls-deploy.yaml @@ -130,7 +130,7 @@ spec: EOF ``` -Check out the docs for information about semantics and operators supported by the [JSON pattern-matching authorization](./../features.md#json-pattern-matching-authorization-rules-authorizationjson) feature, as well the common feature [JSON paths](./../features.md#common-feature-json-paths-valuefromauthjson) for reading from the [Authorization JSON](./../architecture.md#the-authorization-json), including the description of the string modifier `@extract` used above. Check out as well the common feature [Conditions](./../features.md#common-feature-conditions-when) about skipping parts of an `AuthConfig` in the auth pipeline based on context.. +Check out the docs for information about semantics and operators supported by the [JSON pattern-matching authorization](./../features.md#json-pattern-matching-authorization-rules-authorizationjson) feature, as well the common feature [JSON paths](./../features.md#common-feature-json-paths-valuefromauthjson) for reading from the [Authorization JSON](./../architecture.md#the-authorization-json), including the description of the string modifier `@extract` used above. Check out as well the common feature [Conditions](./../features.md#common-feature-conditions-when) about skipping parts of an `AuthConfig` in the auth pipeline based on context. ## 6. Obtain an access token and consume the API diff --git a/docs/user-guides/keycloak-authorization-services.md b/docs/user-guides/keycloak-authorization-services.md index 0f014081..ca15e1a3 100644 --- a/docs/user-guides/keycloak-authorization-services.md +++ b/docs/user-guides/keycloak-authorization-services.md @@ -1,6 +1,6 @@ # User guide: Authorization with Keycloak Authorization Services -Keycloak provides a powerful set of tools (REST endpoints and administrative UIs), also known as [Keycloak Authorization Services](https://www.keycloak.org/docs/latest/authorization_services/index.html), to manage and enforce authorization, workflows for multiple access control mechanisms, including discritionary user access control and user-managed permissions. +Keycloak provides a powerful set of tools (REST endpoints and administrative UIs), also known as [Keycloak Authorization Services](https://www.keycloak.org/docs/latest/authorization_services/index.html), to manage and enforce authorization, workflows for multiple access control mechanisms, including discretionary user access control and user-managed permissions. This user guide is an example of how to use Authorino as an adapter to Keycloak Authorization Services while still relying on the reverse-proxy integration pattern, thus not involving importing an authorization library nor rebuilding the application's code. @@ -75,13 +75,13 @@ spec: EOF ``` -The command above will deploy Authorino as a separate service (as oposed to a sidecar of the protected API and other architectures), in `namespaced` reconciliation mode, and with TLS termination disabled. For other variants and deployment options, check out the [Getting Started](./../getting-started.md#2-deploy-an-authorino-instance) section of the docs, the [Architecture](./../architecture.md#topologies) page, and the spec for the [`Authorino`](https://github.com/Kuadrant/authorino-operator/blob/main/config/crd/bases/operator.authorino.kuadrant.io_authorinos.yaml) CRD in the Authorino Operator repo. +The command above will deploy Authorino as a separate service (as opposed to a sidecar of the protected API and other architectures), in `namespaced` reconciliation mode, and with TLS termination disabled. For other variants and deployment options, check out the [Getting Started](./../getting-started.md#step-request-an-authorino-instance) section of the docs, the [Architecture](./../architecture.md#topologies) page, and the spec for the [`Authorino`](https://github.com/Kuadrant/authorino-operator/blob/main/config/crd/bases/operator.authorino.kuadrant.io_authorinos.yaml) CRD in the Authorino Operator repo. ## 4. Setup Envoy The following bundle from the Authorino examples (manifest referred in the command below) is to apply Envoy configuration and deploy Envoy proxy, that wire up the Talker API behind the reverse-proxy and external authorization with the Authorino instance. -For details and instructions to setup Envoy manually, see _Protect a service > Setup Envoy_ in the [Getting Started](./../getting-started.md#1-setup-envoy) page. For a simpler and straighforward way to manage an API, without having to manually install or configure Envoy and Authorino, check out [Kuadrant](https://github.com/kuadrant). +For details and instructions to setup Envoy manually, see _Protect a service > Setup Envoy_ in the [Getting Started](./../getting-started.md#step-setup-envoy) page. For a simpler and straightforward way to manage an API, without having to manually install or configure Envoy and Authorino, check out [Kuadrant](https://github.com/kuadrant). ```sh kubectl apply -f https://raw.githubusercontent.com/kuadrant/authorino-examples/main/envoy/envoy-notls-deploy.yaml diff --git a/docs/user-guides/kubernetes-subjectaccessreview.md b/docs/user-guides/kubernetes-subjectaccessreview.md index a9db76da..d801eca5 100644 --- a/docs/user-guides/kubernetes-subjectaccessreview.md +++ b/docs/user-guides/kubernetes-subjectaccessreview.md @@ -23,7 +23,7 @@ Manage permissions in the Kubernetes RBAC and let Authorino to check them in req ## Requirements - Kubernetes server -- Kubernetes user with permission to create `TokenRequest`s (to consume the API from ouside the cluster) +- Kubernetes user with permission to create `TokenRequest`s (to consume the API from outside the cluster) - [yq](https://github.com/mikefarah/yq) (to parse your `~/.kube/config` file to extract user authentication data) Create a containerized Kubernetes server locally using [Kind](https://kind.sigs.k8s.io): @@ -64,13 +64,13 @@ spec: EOF ``` -The command above will deploy Authorino as a separate service (as oposed to a sidecar of the protected API and other architectures), in `namespaced` reconciliation mode, and with TLS termination disabled. For other variants and deployment options, check out the [Getting Started](./../getting-started.md#2-deploy-an-authorino-instance) section of the docs, the [Architecture](./../architecture.md#topologies) page, and the spec for the [`Authorino`](https://github.com/Kuadrant/authorino-operator/blob/main/config/crd/bases/operator.authorino.kuadrant.io_authorinos.yaml) CRD in the Authorino Operator repo. +The command above will deploy Authorino as a separate service (as opposed to a sidecar of the protected API and other architectures), in `namespaced` reconciliation mode, and with TLS termination disabled. For other variants and deployment options, check out the [Getting Started](./../getting-started.md#step-request-an-authorino-instance) section of the docs, the [Architecture](./../architecture.md#topologies) page, and the spec for the [`Authorino`](https://github.com/Kuadrant/authorino-operator/blob/main/config/crd/bases/operator.authorino.kuadrant.io_authorinos.yaml) CRD in the Authorino Operator repo. ## 4. Setup Envoy The following bundle from the Authorino examples (manifest referred in the command below) is to apply Envoy configuration and deploy Envoy proxy, that wire up the Talker API behind the reverse-proxy and external authorization with the Authorino instance. -For details and instructions to setup Envoy manually, see _Protect a service > Setup Envoy_ in the [Getting Started](./../getting-started.md#1-setup-envoy) page. For a simpler and straighforward way to manage an API, without having to manually install or configure Envoy and Authorino, check out [Kuadrant](https://github.com/kuadrant). +For details and instructions to setup Envoy manually, see _Protect a service > Setup Envoy_ in the [Getting Started](./../getting-started.md#step-setup-envoy) page. For a simpler and straightforward way to manage an API, without having to manually install or configure Envoy and Authorino, check out [Kuadrant](https://github.com/kuadrant). ```sh kubectl apply -f https://raw.githubusercontent.com/kuadrant/authorino-examples/main/envoy/envoy-notls-deploy.yaml diff --git a/docs/user-guides/kubernetes-tokenreview.md b/docs/user-guides/kubernetes-tokenreview.md index d7aec815..05935ce2 100644 --- a/docs/user-guides/kubernetes-tokenreview.md +++ b/docs/user-guides/kubernetes-tokenreview.md @@ -65,13 +65,13 @@ spec: EOF ``` -The command above will deploy Authorino as a separate service (as oposed to a sidecar of the protected API and other architectures), in `namespaced` reconciliation mode, and with TLS termination disabled. For other variants and deployment options, check out the [Getting Started](./../getting-started.md#2-deploy-an-authorino-instance) section of the docs, the [Architecture](./../architecture.md#topologies) page, and the spec for the [`Authorino`](https://github.com/Kuadrant/authorino-operator/blob/main/config/crd/bases/operator.authorino.kuadrant.io_authorinos.yaml) CRD in the Authorino Operator repo. +The command above will deploy Authorino as a separate service (as opposed to a sidecar of the protected API and other architectures), in `namespaced` reconciliation mode, and with TLS termination disabled. For other variants and deployment options, check out the [Getting Started](./../getting-started.md#step-request-an-authorino-instance) section of the docs, the [Architecture](./../architecture.md#topologies) page, and the spec for the [`Authorino`](https://github.com/Kuadrant/authorino-operator/blob/main/config/crd/bases/operator.authorino.kuadrant.io_authorinos.yaml) CRD in the Authorino Operator repo. ## 4. Setup Envoy The following bundle from the Authorino examples (manifest referred in the command below) is to apply Envoy configuration and deploy Envoy proxy, that wire up the Talker API behind the reverse-proxy and external authorization with the Authorino instance. -For details and instructions to setup Envoy manually, see _Protect a service > Setup Envoy_ in the [Getting Started](./../getting-started.md#1-setup-envoy) page. For a simpler and straighforward way to manage an API, without having to manually install or configure Envoy and Authorino, check out [Kuadrant](https://github.com/kuadrant). +For details and instructions to setup Envoy manually, see _Protect a service > Setup Envoy_ in the [Getting Started](./../getting-started.md#step-setup-envoy) page. For a simpler and straightforward way to manage an API, without having to manually install or configure Envoy and Authorino, check out [Kuadrant](https://github.com/kuadrant). ```sh kubectl apply -f https://raw.githubusercontent.com/kuadrant/authorino-examples/main/envoy/envoy-notls-deploy.yaml diff --git a/docs/user-guides/mtls-authentication.md b/docs/user-guides/mtls-authentication.md index 2d1043d7..c32da662 100644 --- a/docs/user-guides/mtls-authentication.md +++ b/docs/user-guides/mtls-authentication.md @@ -71,7 +71,7 @@ spec: EOF ``` -The command above will deploy Authorino as a separate service (as oposed to a sidecar of the protected API and other architectures), in `namespaced` reconciliation mode, and with TLS termination enabled. For other variants and deployment options, check out the [Getting Started](./../getting-started.md#2-deploy-an-authorino-instance) section of the docs, the [Architecture](./../architecture.md#topologies) page, and the spec for the [`Authorino`](https://github.com/Kuadrant/authorino-operator/blob/main/config/crd/bases/operator.authorino.kuadrant.io_authorinos.yaml) CRD in the Authorino Operator repo. +The command above will deploy Authorino as a separate service (as opposed to a sidecar of the protected API and other architectures), in `namespaced` reconciliation mode, and with TLS termination enabled. For other variants and deployment options, check out the [Getting Started](./../getting-started.md#step-request-an-authorino-instance) section of the docs, the [Architecture](./../architecture.md#topologies) page, and the spec for the [`Authorino`](https://github.com/Kuadrant/authorino-operator/blob/main/config/crd/bases/operator.authorino.kuadrant.io_authorinos.yaml) CRD in the Authorino Operator repo. ## 3. Deploy the Talker API @@ -355,7 +355,7 @@ curl -k --cert /tmp/aisha.crt --key /tmp/aisha.key -H 'Content-Type: application # HTTP/2 200 ``` -With a TLS certificate signed by a unknown authority: +With a TLS certificate signed by an unknown authority: ```sh openssl req -x509 -sha256 -days 365 -nodes -newkey rsa:2048 -subj "/CN=untrusted" -keyout /tmp/untrusted-ca.key -out /tmp/untrusted-ca.crt diff --git a/docs/user-guides/oauth2-token-introspection.md b/docs/user-guides/oauth2-token-introspection.md index 0276503e..331e2699 100644 --- a/docs/user-guides/oauth2-token-introspection.md +++ b/docs/user-guides/oauth2-token-introspection.md @@ -47,7 +47,7 @@ Forward local requests to the instance of Keycloak running in the cluster: kubectl -n keycloak port-forward deployment/keycloak 8080:8080 & ``` -Deploy a a12n-server server preloaded with all the realm settings required for this guide: +Deploy an a12n-server server preloaded with all the realm settings required for this guide: ```sh kubectl create namespace a12n-server @@ -92,13 +92,13 @@ spec: EOF ``` -The command above will deploy Authorino as a separate service (as oposed to a sidecar of the protected API and other architectures), in `namespaced` reconciliation mode, and with TLS termination disabled. For other variants and deployment options, check out the [Getting Started](./../getting-started.md#2-deploy-an-authorino-instance) section of the docs, the [Architecture](./../architecture.md#topologies) page, and the spec for the [`Authorino`](https://github.com/Kuadrant/authorino-operator/blob/main/config/crd/bases/operator.authorino.kuadrant.io_authorinos.yaml) CRD in the Authorino Operator repo. +The command above will deploy Authorino as a separate service (as opposed to a sidecar of the protected API and other architectures), in `namespaced` reconciliation mode, and with TLS termination disabled. For other variants and deployment options, check out the [Getting Started](./../getting-started.md#step-request-an-authorino-instance) section of the docs, the [Architecture](./../architecture.md#topologies) page, and the spec for the [`Authorino`](https://github.com/Kuadrant/authorino-operator/blob/main/config/crd/bases/operator.authorino.kuadrant.io_authorinos.yaml) CRD in the Authorino Operator repo. ## 4. Setup Envoy The following bundle from the Authorino examples (manifest referred in the command below) is to apply Envoy configuration and deploy Envoy proxy, that wire up the Talker API behind the reverse-proxy and external authorization with the Authorino instance. -For details and instructions to setup Envoy manually, see _Protect a service > Setup Envoy_ in the [Getting Started](./../getting-started.md#1-setup-envoy) page. For a simpler and straighforward way to manage an API, without having to manually install or configure Envoy and Authorino, check out [Kuadrant](https://github.com/kuadrant). +For details and instructions to setup Envoy manually, see _Protect a service > Setup Envoy_ in the [Getting Started](./../getting-started.md#step-setup-envoy) page. For a simpler and straightforward way to manage an API, without having to manually install or configure Envoy and Authorino, check out [Kuadrant](https://github.com/kuadrant). ```sh kubectl apply -f https://raw.githubusercontent.com/kuadrant/authorino-examples/main/envoy/envoy-notls-deploy.yaml diff --git a/docs/user-guides/observability.md b/docs/user-guides/observability.md index 048560a1..77280d3f 100644 --- a/docs/user-guides/observability.md +++ b/docs/user-guides/observability.md @@ -11,7 +11,7 @@ Authorino exports metrics at 2 endpoints: /server-metrics - Metrics of the external authorization gRPC and OIDC/Festival Writband validation built-in HTTP servers + Metrics of the external authorization gRPC and OIDC/Festival Wristband validation built-in HTTP servers @@ -1087,7 +1087,7 @@ The following additional subpath is available and its corresponding check can be - +
    Important!
    The AuthConfig readiness check within the scope of the aggregated readiness probe endpoint is deactivated by default – i.e. this check is an opt-in check. Sending a request to the /readyz endpoint without explicitly opting-in for the AuthConfigs check, by using the include parameter, will result in a response message that disregards the actual status of the watched watched AuthConfigs, possibly an "ok" message. To read the aggregated status of the watched AuthConfigs, either use the specific endpoint /readyz/authconfigs or opt-in for the check in the aggregated endpoint by sending a request to /readyz?include=authconfigs    		Important!
    The AuthConfig readiness check within the scope of the aggregated readiness probe endpoint is deactivated by default – i.e. this check is an opt-in check. Sending a request to the /readyz endpoint without explicitly opting-in for the AuthConfigs check, by using the include parameter, will result in a response message that disregards the actual status of the watched AuthConfigs, possibly an "ok" message. To read the aggregated status of the watched AuthConfigs, either use the specific endpoint /readyz/authconfigs or opt-in for the check in the aggregated endpoint by sending a request to /readyz?include=authconfigs
    @@ -1107,7 +1107,7 @@ Authorino outputs 3 levels of log messages: (from lowest to highest level) 2. `info` (default) 3. `error` -`info` logging is restricted to high-level information of the gRPC and HTTP authorization services, limiting messages to incomming request and respective outgoing response logs, with reduced details about the corresponding objects (request payload and authorization result), and without any further detailed logs of the steps in between, except for errors. +`info` logging is restricted to high-level information of the gRPC and HTTP authorization services, limiting messages to incoming request and respective outgoing response logs, with reduced details about the corresponding objects (request payload and authorization result), and without any further detailed logs of the steps in between, except for errors. Only `debug` logging will include processing details of each [Auth Pipeline](./../architecture.md#the-auth-pipeline-aka-enforcing-protection-in-request-time), such as intermediary requests to validate identities with external auth servers, requests to external sources of auth metadata or authorization policies. @@ -1141,93 +1141,93 @@ spec: Authorino will never output HTTP headers and query string parameters to `info` log messages, as such values usually include sensitive data (e.g. access tokens, API keys and Authorino Festival Wristbands). However, `debug` log messages may include such sensitive information and those are not redacted. -Therefore, **DO NOT USE `debug` LOG LEVEL IN PRODUCTION**! Instead use either `info` or `error`. +Therefore, **DO NOT USE `debug` LOG LEVEL IN PRODUCTION**! Instead, use either `info` or `error`. ### Log messages printed by Authorino Some log messages printed by Authorino and corresponding extra values included: -| logger | level | message | extra values | -|----------------------------------------------------------------------------|-------|---------|--------| -| `authorino` | `info` | "setting instance base logger" | `min level=info\|debug`, `mode=production\|development` | -| `authorino` | `info` | "booting up authorino" | `version` | -| `authorino` | `debug` | "setting up with options" | `auth-config-label-selector`, `deep-metrics-enabled`, `enable-leader-election`, `evaluator-cache-size`, `ext-auth-grpc-port`, `ext-auth-http-port`, `health-probe-addr`, `log-level`, `log-mode`, `max-http-request-body-size`, `metrics-addr`, `oidc-http-port`, `oidc-tls-cert`, `oidc-tls-cert-key`, `secret-label-selector`, `timeout`, `tls-cert`, `tls-cert-key`, `watch-namespace` | -| `authorino` | `info` | "attempting to acquire leader lease <namespace>/cb88a58a.authorino.kuadrant.io...\n" | | -| `authorino` | `info` | "successfully acquired lease <namespace>/cb88a58a.authorino.kuadrant.io\n" | | -| `authorino` | `info` | "disabling grpc auth service" | | -| `authorino` | `info` | "starting grpc auth service" | `port`, `tls` | -| `authorino` | `error` | "failed to obtain port for the grpc auth service" | | -| `authorino` | `error` | "failed to load tls cert for the grpc auth" | | -| `authorino` | `error` | "failed to start grpc auth service" | | -| `authorino` | `info` | "disabling http auth service" | | -| `authorino` | `info` | "starting http auth service" | `port`, `tls` | -| `authorino` | `error` | "failed to obtain port for the http auth service" | | -| `authorino` | `error` | "failed to start http auth service" | | -| `authorino` | `info` | "disabling http oidc service" | | -| `authorino` | `info` | "starting http oidc service" | `port`, `tls` | -| `authorino` | `error` | "failed to obtain port for the http oidc service" | | -| `authorino` | `error` | "failed to start http oidc service" | | -| `authorino` | `info` | "starting manager" | | -| `authorino` | `error` | "unable to start manager" | | -| `authorino` | `error` | "unable to create controller" | `controller=authconfig\|secret\|authconfigstatusupdate` | -| `authorino` | `error` | "problem running manager" | | -| `authorino` | `info` | "starting status update manager" | | -| `authorino` | `error` | "unable to start status update manager" | | -| `authorino` | `error` | "problem running status update manager" | | -| `authorino.controller-runtime.metrics` | `info` | "metrics server is starting to listen" | `addr` | -| `authorino.controller-runtime.manager` | `info` | "starting metrics server" | `path` -| `authorino.controller-runtime.manager.events` | `debug` | "Normal" | `object={kind=ConfigMap, apiVersion=v1}`, `reauthorino.ason=LeaderElection`, `message="authorino-controller-manager-* became leader"` -| `authorino.controller-runtime.manager.events` | `debug` | "Normal" | `object={kind=Lease, apiVersion=coordination.k8s.io/v1}`, `reauthorino.ason=LeaderElection`, `message="authorino-controller-manager-* became leader"` -| `authorino.controller-runtime.manager.controller.authconfig` | `info` | "resource reconciled" | `authconfig` | -| `authorino.controller-runtime.manager.controller.authconfig` | `info` | "host already taken" | `authconfig`, `host` | -| `authorino.controller-runtime.manager.controller.authconfig.statusupdater` | `debug` | "resource status did not change" | `authconfig` | -| `authorino.controller-runtime.manager.controller.authconfig.statusupdater` | `debug` | "resource status changed" | `authconfig`, `authconfig/status` | -| `authorino.controller-runtime.manager.controller.authconfig.statusupdater` | `error` | "failed to update the resource" | `authconfig` | -| `authorino.controller-runtime.manager.controller.authconfig.statusupdater` | `info` | "resource status updated" | `authconfig` | -| `authorino.controller-runtime.manager.controller.secret` | `info` | "resource reconciled" | | -| `authorino.controller-runtime.manager.controller.secret` | `info` | "could not reconcile authconfigs using api key autauthorino.hentication" | | -| `authorino.service.oidc` | `info` | "request received" | `request id`, `url`, `realm`, `config`, `path` | -| `authorino.service.oidc` | `info` | "response sent" | `request id` | -| `authorino.service.oidc` | `error` | "failed to serve oidc request" | | -| `authorino.service.auth` | `info` | "incoming authorization request" | `request id`, `object` | -| `authorino.service.auth` | `debug` | "incoming authorization request" | `request id`, `object` | -| `authorino.service.auth` | `info` | "outgoing authorization response" | `request id`, `authorized`, `response`, `object` | -| `authorino.service.auth` | `debug` | "outgoing authorization response" | `request id`, `authorized`, `response`, `object` | -| `authorino.service.auth` | `error` | "failed to create dynamic metadata" | `request id`, `object` | -| `authorino.service.auth.authpipeline` | `debug` | "skipping config" | `request id`, `config`, `reason` | -| `authorino.service.auth.authpipeline.identity` | `debug` | "identity validated" | `request id`, `config`, `object` | -| `authorino.service.auth.authpipeline.identity` | `debug` | "cannot validate identity" | `request id`, `config`, `reason` | -| `authorino.service.auth.authpipeline.identity` | `error` | "failed to extend identity object" | `request id`, `config`, `object` | -| `authorino.service.auth.authpipeline.identity.oidc` | `error` | "failed to discovery openid connect configuration" | `endpoint` | -| `authorino.service.auth.authpipeline.identity.oidc` | `debug` | "auto-refresh of openid connect configuration disabled" | `endpoint`, `reason` | -| `authorino.service.auth.authpipeline.identity.oidc` | `debug` | "openid connect configuration updated" | `endpoint` | -| `authorino.service.auth.authpipeline.identity.oauth2` | `debug` | "sending token introspection request" | `request id`, `url`, `data` | -| `authorino.service.auth.authpipeline.identity.kubernetesauth` | `debug` | "calling kubernetes token review api" | `request id`, `tokenreview` | -| `authorino.service.auth.authpipeline.identity.apikey` | `error` | "Something went wrong fetching the authorized credentials" | | -| `authorino.service.auth.authpipeline.metadata` | `debug` | "fetched auth metadata" | `request id`, `config`, `object` | -| `authorino.service.auth.authpipeline.metadata` | `debug` | "cannot fetch metadata" | `request id`, `config`, `reason` | -| `authorino.service.auth.authpipeline.metadata.http` | `debug` | "sending request" | `request id`, `method`, `url`, `headers` | -| `authorino.service.auth.authpipeline.metadata.userinfo` | `debug` | "fetching user info" | `request id`, `endpoint` | -| `authorino.service.auth.authpipeline.metadata.uma` | `debug` | "requesting pat" | `request id`, `url`, `data`, `headers` | -| `authorino.service.auth.authpipeline.metadata.uma` | `debug` | "querying resources by uri" | `request id`, `url` | -| `authorino.service.auth.authpipeline.metadata.uma` | `debug` | "getting resource data" | `request id`, `url` | -| `authorino.service.auth.authpipeline.authorization` | `debug` | "evaluating for input" | `request id`, `input` | -| `authorino.service.auth.authpipeline.authorization` | `debug` | "access granted" | `request id`, `config`, `object` | -| `authorino.service.auth.authpipeline.authorization` | `debug` | "access denied" | `request id`, `config`, `reason` | -| `authorino.service.auth.authpipeline.authorization.opa` | `error` | "invalid response from policy evaluation" | `policy` | -| `authorino.service.auth.authpipeline.authorization.opa` | `error` | "failed to precompile policy" | `policy` | -| `authorino.service.auth.authpipeline.authorization.opa` | `error` | "failed to download policy from external registry" | `policy`, `endpoint` | -| `authorino.service.auth.authpipeline.authorization.opa` | `error` | "failed to refresh policy from external registry" | `policy`, `endpoint` | -| `authorino.service.auth.authpipeline.authorization.opa` | `debug` | "external policy unchanged" | `policy`, `endpoint` | -| `authorino.service.auth.authpipeline.authorization.opa` | `debug` | "auto-refresh of external policy disabled" | `policy`, `endpoint`, `reason` | -| `authorino.service.auth.authpipeline.authorization.opa` | `info` | "policy updated from external registry" | `policy`, `endpoint` | -| `authorino.service.auth.authpipeline.authorization.kubernetesauthz` | `debug` | "calling kubernetes subject access review api" | `request id`, `subjectaccessreview` | -| `authorino.service.auth.authpipeline.response` | `debug` | "dynamic response built" | `request id`, `config`, `object` | -| `authorino.service.auth.authpipeline.response` | `debug` | "cannot build dynamic response" | `request id`, `config`, `reason` | -| `authorino.service.auth.http` | `debug` | "bad request" | `request id` | -| `authorino.service.auth.http` | `debug` | "not found" | `request id` | -| `authorino.service.auth.http` | `debug` | "request body too large" | `request id` | -| `authorino.service.auth.http` | `debug` | "service unavailable" | `request id` | +| logger | level | message | extra values | +|----------------------------------------------------------------------------|---------|--------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `authorino` | `info` | "setting instance base logger" | `min level=info\|debug`, `mode=production\|development` | +| `authorino` | `info` | "booting up authorino" | `version` | +| `authorino` | `debug` | "setting up with options" | `auth-config-label-selector`, `deep-metrics-enabled`, `enable-leader-election`, `evaluator-cache-size`, `ext-auth-grpc-port`, `ext-auth-http-port`, `health-probe-addr`, `log-level`, `log-mode`, `max-http-request-body-size`, `metrics-addr`, `oidc-http-port`, `oidc-tls-cert`, `oidc-tls-cert-key`, `secret-label-selector`, `timeout`, `tls-cert`, `tls-cert-key`, `watch-namespace` | +| `authorino` | `info` | "attempting to acquire leader lease <namespace>/cb88a58a.authorino.kuadrant.io...\n" | | +| `authorino` | `info` | "successfully acquired lease <namespace>/cb88a58a.authorino.kuadrant.io\n" | | +| `authorino` | `info` | "disabling grpc auth service" | | +| `authorino` | `info` | "starting grpc auth service" | `port`, `tls` | +| `authorino` | `error` | "failed to obtain port for the grpc auth service" | | +| `authorino` | `error` | "failed to load tls cert for the grpc auth" | | +| `authorino` | `error` | "failed to start grpc auth service" | | +| `authorino` | `info` | "disabling http auth service" | | +| `authorino` | `info` | "starting http auth service" | `port`, `tls` | +| `authorino` | `error` | "failed to obtain port for the http auth service" | | +| `authorino` | `error` | "failed to start http auth service" | | +| `authorino` | `info` | "disabling http oidc service" | | +| `authorino` | `info` | "starting http oidc service" | `port`, `tls` | +| `authorino` | `error` | "failed to obtain port for the http oidc service" | | +| `authorino` | `error` | "failed to start http oidc service" | | +| `authorino` | `info` | "starting manager" | | +| `authorino` | `error` | "unable to start manager" | | +| `authorino` | `error` | "unable to create controller" | `controller=authconfig\|secret\|authconfigstatusupdate` | +| `authorino` | `error` | "problem running manager" | | +| `authorino` | `info` | "starting status update manager" | | +| `authorino` | `error` | "unable to start status update manager" | | +| `authorino` | `error` | "problem running status update manager" | | +| `authorino.controller-runtime.metrics` | `info` | "metrics server is starting to listen" | `addr` | +| `authorino.controller-runtime.manager` | `info` | "starting metrics server" | `path` | +| `authorino.controller-runtime.manager.events` | `debug` | "Normal" | `object={kind=ConfigMap, apiVersion=v1}`, `reauthorino.ason=LeaderElection`, `message="authorino-controller-manager-* became leader"` | +| `authorino.controller-runtime.manager.events` | `debug` | "Normal" | `object={kind=Lease, apiVersion=coordination.k8s.io/v1}`, `reauthorino.ason=LeaderElection`, `message="authorino-controller-manager-* became leader"` | +| `authorino.controller-runtime.manager.controller.authconfig` | `info` | "resource reconciled" | `authconfig` | +| `authorino.controller-runtime.manager.controller.authconfig` | `info` | "host already taken" | `authconfig`, `host` | +| `authorino.controller-runtime.manager.controller.authconfig.statusupdater` | `debug` | "resource status did not change" | `authconfig` | +| `authorino.controller-runtime.manager.controller.authconfig.statusupdater` | `debug` | "resource status changed" | `authconfig`, `authconfig/status` | +| `authorino.controller-runtime.manager.controller.authconfig.statusupdater` | `error` | "failed to update the resource" | `authconfig` | +| `authorino.controller-runtime.manager.controller.authconfig.statusupdater` | `info` | "resource status updated" | `authconfig` | +| `authorino.controller-runtime.manager.controller.secret` | `info` | "resource reconciled" | | +| `authorino.controller-runtime.manager.controller.secret` | `info` | "could not reconcile authconfigs using api key authorino.authentication" | | +| `authorino.service.oidc` | `info` | "request received" | `request id`, `url`, `realm`, `config`, `path` | +| `authorino.service.oidc` | `info` | "response sent" | `request id` | +| `authorino.service.oidc` | `error` | "failed to serve oidc request" | | +| `authorino.service.auth` | `info` | "incoming authorization request" | `request id`, `object` | +| `authorino.service.auth` | `debug` | "incoming authorization request" | `request id`, `object` | +| `authorino.service.auth` | `info` | "outgoing authorization response" | `request id`, `authorized`, `response`, `object` | +| `authorino.service.auth` | `debug` | "outgoing authorization response" | `request id`, `authorized`, `response`, `object` | +| `authorino.service.auth` | `error` | "failed to create dynamic metadata" | `request id`, `object` | +| `authorino.service.auth.authpipeline` | `debug` | "skipping config" | `request id`, `config`, `reason` | +| `authorino.service.auth.authpipeline.identity` | `debug` | "identity validated" | `request id`, `config`, `object` | +| `authorino.service.auth.authpipeline.identity` | `debug` | "cannot validate identity" | `request id`, `config`, `reason` | +| `authorino.service.auth.authpipeline.identity` | `error` | "failed to extend identity object" | `request id`, `config`, `object` | +| `authorino.service.auth.authpipeline.identity.oidc` | `error` | "failed to discovery openid connect configuration" | `endpoint` | +| `authorino.service.auth.authpipeline.identity.oidc` | `debug` | "auto-refresh of openid connect configuration disabled" | `endpoint`, `reason` | +| `authorino.service.auth.authpipeline.identity.oidc` | `debug` | "openid connect configuration updated" | `endpoint` | +| `authorino.service.auth.authpipeline.identity.oauth2` | `debug` | "sending token introspection request" | `request id`, `url`, `data` | +| `authorino.service.auth.authpipeline.identity.kubernetesauth` | `debug` | "calling kubernetes token review api" | `request id`, `tokenreview` | +| `authorino.service.auth.authpipeline.identity.apikey` | `error` | "Something went wrong fetching the authorized credentials" | | +| `authorino.service.auth.authpipeline.metadata` | `debug` | "fetched auth metadata" | `request id`, `config`, `object` | +| `authorino.service.auth.authpipeline.metadata` | `debug` | "cannot fetch metadata" | `request id`, `config`, `reason` | +| `authorino.service.auth.authpipeline.metadata.http` | `debug` | "sending request" | `request id`, `method`, `url`, `headers` | +| `authorino.service.auth.authpipeline.metadata.userinfo` | `debug` | "fetching user info" | `request id`, `endpoint` | +| `authorino.service.auth.authpipeline.metadata.uma` | `debug` | "requesting pat" | `request id`, `url`, `data`, `headers` | +| `authorino.service.auth.authpipeline.metadata.uma` | `debug` | "querying resources by uri" | `request id`, `url` | +| `authorino.service.auth.authpipeline.metadata.uma` | `debug` | "getting resource data" | `request id`, `url` | +| `authorino.service.auth.authpipeline.authorization` | `debug` | "evaluating for input" | `request id`, `input` | +| `authorino.service.auth.authpipeline.authorization` | `debug` | "access granted" | `request id`, `config`, `object` | +| `authorino.service.auth.authpipeline.authorization` | `debug` | "access denied" | `request id`, `config`, `reason` | +| `authorino.service.auth.authpipeline.authorization.opa` | `error` | "invalid response from policy evaluation" | `policy` | +| `authorino.service.auth.authpipeline.authorization.opa` | `error` | "failed to precompile policy" | `policy` | +| `authorino.service.auth.authpipeline.authorization.opa` | `error` | "failed to download policy from external registry" | `policy`, `endpoint` | +| `authorino.service.auth.authpipeline.authorization.opa` | `error` | "failed to refresh policy from external registry" | `policy`, `endpoint` | +| `authorino.service.auth.authpipeline.authorization.opa` | `debug` | "external policy unchanged" | `policy`, `endpoint` | +| `authorino.service.auth.authpipeline.authorization.opa` | `debug` | "auto-refresh of external policy disabled" | `policy`, `endpoint`, `reason` | +| `authorino.service.auth.authpipeline.authorization.opa` | `info` | "policy updated from external registry" | `policy`, `endpoint` | +| `authorino.service.auth.authpipeline.authorization.kubernetesauthz` | `debug` | "calling kubernetes subject access review api" | `request id`, `subjectaccessreview` | +| `authorino.service.auth.authpipeline.response` | `debug` | "dynamic response built" | `request id`, `config`, `object` | +| `authorino.service.auth.authpipeline.response` | `debug` | "cannot build dynamic response" | `request id`, `config`, `reason` | +| `authorino.service.auth.http` | `debug` | "bad request" | `request id` | +| `authorino.service.auth.http` | `debug` | "not found" | `request id` | +| `authorino.service.auth.http` | `debug` | "request body too large" | `request id` | +| `authorino.service.auth.http` | `debug` | "service unavailable" | `request id` | #### Examples @@ -1410,7 +1410,7 @@ The examples below are all with `--log-level=debug` and `--log-mode=production`. ### Request ID Processes related to the authorization request are identified and linked together by a _request ID_. The request ID can be: -* generated outside of Authorino and passed in the authorization request – this is essentially the case of requests via GRPC authorization interface initiated by the Envoy; +* generated outside Authorino and passed in the authorization request – this is essentially the case of requests via GRPC authorization interface initiated by the Envoy; * generated by Authorino – requests via [Raw HTTP Authorization interface](../architecture.md#raw-http-authorization-interface). ### Propagation @@ -1419,7 +1419,7 @@ Authorino propagates trace identifiers compatible with the W3C Trace Context for ### Log tracing -Most log messages associated with an authorization request include the [`request id`](#request-id) value. This value can be used to match incomming request and corresponding outgoing response log messages, including at deep level when more fine-grained log details are enabled ([`debug` level level](#log-levels-and-log-modes)). +Most log messages associated with an authorization request include the [`request id`](#request-id) value. This value can be used to match incoming request and corresponding outgoing response log messages, including at deep level when more fine-grained log details are enabled ([`debug` level level](#log-levels-and-log-modes)). ### OpenTelemetry integration diff --git a/docs/user-guides/oidc-jwt-authentication.md b/docs/user-guides/oidc-jwt-authentication.md index d01bd8f6..45da10a5 100644 --- a/docs/user-guides/oidc-jwt-authentication.md +++ b/docs/user-guides/oidc-jwt-authentication.md @@ -76,13 +76,13 @@ spec: EOF ``` -The command above will deploy Authorino as a separate service (as oposed to a sidecar of the protected API and other architectures), in `namespaced` reconciliation mode, and with TLS termination disabled. For other variants and deployment options, check out the [Getting Started](./../getting-started.md#2-deploy-an-authorino-instance) section of the docs, the [Architecture](./../architecture.md#topologies) page, and the spec for the [`Authorino`](https://github.com/Kuadrant/authorino-operator/blob/main/config/crd/bases/operator.authorino.kuadrant.io_authorinos.yaml) CRD in the Authorino Operator repo. +The command above will deploy Authorino as a separate service (as opposed to a sidecar of the protected API and other architectures), in `namespaced` reconciliation mode, and with TLS termination disabled. For other variants and deployment options, check out the [Getting Started](./../getting-started.md#step-request-an-authorino-instance) section of the docs, the [Architecture](./../architecture.md#topologies) page, and the spec for the [`Authorino`](https://github.com/Kuadrant/authorino-operator/blob/main/config/crd/bases/operator.authorino.kuadrant.io_authorinos.yaml) CRD in the Authorino Operator repo. ## 4. Setup Envoy The following bundle from the Authorino examples (manifest referred in the command below) is to apply Envoy configuration and deploy Envoy proxy, that wire up the Talker API behind the reverse-proxy and external authorization with the Authorino instance. -For details and instructions to setup Envoy manually, see _Protect a service > Setup Envoy_ in the [Getting Started](./../getting-started.md#1-setup-envoy) page. For a simpler and straighforward way to manage an API, without having to manually install or configure Envoy and Authorino, check out [Kuadrant](https://github.com/kuadrant). +For details and instructions to setup Envoy manually, see _Protect a service > Setup Envoy_ in the [Getting Started](./../getting-started.md#step-setup-envoy) page. For a simpler and straightforward way to manage an API, without having to manually install or configure Envoy and Authorino, check out [Kuadrant](https://github.com/kuadrant). ```sh kubectl apply -f https://raw.githubusercontent.com/kuadrant/authorino-examples/main/envoy/envoy-notls-deploy.yaml diff --git a/docs/user-guides/oidc-rbac.md b/docs/user-guides/oidc-rbac.md index 0829708e..2d457030 100644 --- a/docs/user-guides/oidc-rbac.md +++ b/docs/user-guides/oidc-rbac.md @@ -77,13 +77,13 @@ spec: EOF ``` -The command above will deploy Authorino as a separate service (as oposed to a sidecar of the protected API and other architectures), in `namespaced` reconciliation mode, and with TLS termination disabled. For other variants and deployment options, check out the [Getting Started](./../getting-started.md#2-deploy-an-authorino-instance) section of the docs, the [Architecture](./../architecture.md#topologies) page, and the spec for the [`Authorino`](https://github.com/Kuadrant/authorino-operator/blob/main/config/crd/bases/operator.authorino.kuadrant.io_authorinos.yaml) CRD in the Authorino Operator repo. +The command above will deploy Authorino as a separate service (as opposed to a sidecar of the protected API and other architectures), in `namespaced` reconciliation mode, and with TLS termination disabled. For other variants and deployment options, check out the [Getting Started](./../getting-started.md#step-request-an-authorino-instance) section of the docs, the [Architecture](./../architecture.md#topologies) page, and the spec for the [`Authorino`](https://github.com/Kuadrant/authorino-operator/blob/main/config/crd/bases/operator.authorino.kuadrant.io_authorinos.yaml) CRD in the Authorino Operator repo. ## 4. Setup Envoy The following bundle from the Authorino examples (manifest referred in the command below) is to apply Envoy configuration and deploy Envoy proxy, that wire up the Talker API behind the reverse-proxy and external authorization with the Authorino instance. -For details and instructions to setup Envoy manually, see _Protect a service > Setup Envoy_ in the [Getting Started](./../getting-started.md#1-setup-envoy) page. For a simpler and straighforward way to manage an API, without having to manually install or configure Envoy and Authorino, check out [Kuadrant](https://github.com/kuadrant). +For details and instructions to setup Envoy manually, see _Protect a service > Setup Envoy_ in the [Getting Started](./../getting-started.md#step-setup-envoy) page. For a simpler and straightforward way to manage an API, without having to manually install or configure Envoy and Authorino, check out [Kuadrant](https://github.com/kuadrant). ```sh kubectl apply -f https://raw.githubusercontent.com/kuadrant/authorino-examples/main/envoy/envoy-notls-deploy.yaml @@ -99,11 +99,11 @@ kubectl port-forward deployment/envoy 8000:8000 & In this example, the Keycloak realm defines a few users and 2 realm roles: 'member' and 'admin'. When users authenticate to the Keycloak server by any of the supported OAuth2/OIDC flows, Keycloak adds to the access token JWT a claim `"realm_access": { "roles": array }` that holds the list of roles assigned to the user. Authorino will verify the JWT on requests to the API and read from that claim to enforce the following RBAC rules: -| Path | Method | Role | -| --------------- | ---------------- |:------:| +| Path | Method | Role | +|-----------------|------------------|:------:| | /resources[/*] | GET / POST / PUT | member | | /resources/{id} | DELETE | admin | -| /admin[/*] | * | member | +| /admin[/*] | * | admin | Apply the AuthConfig: @@ -176,7 +176,7 @@ Obtain an access token with the Keycloak server for John: The `AuthConfig` deployed in the previous step is suitable for validating access tokens requested inside the cluster. This is because Keycloak's `iss` claim added to the JWTs matches always the host used to request the token and Authorino will later try to match this host to the host that provides the OpenID Connect configuration. -Obtain an access token from within the cluster for the user John, who is asigned to the 'member' role: +Obtain an access token from within the cluster for the user John, who is assigned to the 'member' role: ```sh ACCESS_TOKEN=$(kubectl run token --attach --rm --restart=Never -q --image=curlimages/curl -- http://keycloak.keycloak.svc.cluster.local:8080/auth/realms/kuadrant/protocol/openid-connect/token -s -d 'grant_type=password' -d 'client_id=demo' -d 'username=john' -d 'password=p' | jq -r .access_token) @@ -207,7 +207,7 @@ curl -H "Authorization: Bearer $ACCESS_TOKEN" http://talker-api-authorino.127.0. ### Obtain an access token and consume the API as Jane (member/admin) -Obtain an access token from within the cluster for the user Jane, who is asigned to the 'member' and 'admin' roles: +Obtain an access token from within the cluster for the user Jane, who is assigned to the 'member' and 'admin' roles: ```sh ACCESS_TOKEN=$(kubectl run token --attach --rm --restart=Never -q --image=curlimages/curl -- http://keycloak.keycloak.svc.cluster.local:8080/auth/realms/kuadrant/protocol/openid-connect/token -s -d 'grant_type=password' -d 'client_id=demo' -d 'username=jane' -d 'password=p' | jq -r .access_token) diff --git a/docs/user-guides/oidc-user-info.md b/docs/user-guides/oidc-user-info.md index 77764f2a..42b2eed2 100644 --- a/docs/user-guides/oidc-user-info.md +++ b/docs/user-guides/oidc-user-info.md @@ -78,13 +78,13 @@ spec: EOF ``` -The command above will deploy Authorino as a separate service (as oposed to a sidecar of the protected API and other architectures), in `namespaced` reconciliation mode, and with TLS termination disabled. For other variants and deployment options, check out the [Getting Started](./../getting-started.md#2-deploy-an-authorino-instance) section of the docs, the [Architecture](./../architecture.md#topologies) page, and the spec for the [`Authorino`](https://github.com/Kuadrant/authorino-operator/blob/main/config/crd/bases/operator.authorino.kuadrant.io_authorinos.yaml) CRD in the Authorino Operator repo. +The command above will deploy Authorino as a separate service (as opposed to a sidecar of the protected API and other architectures), in `namespaced` reconciliation mode, and with TLS termination disabled. For other variants and deployment options, check out the [Getting Started](./../getting-started.md#step-request-an-authorino-instance) section of the docs, the [Architecture](./../architecture.md#topologies) page, and the spec for the [`Authorino`](https://github.com/Kuadrant/authorino-operator/blob/main/config/crd/bases/operator.authorino.kuadrant.io_authorinos.yaml) CRD in the Authorino Operator repo. ## 4. Setup Envoy The following bundle from the Authorino examples (manifest referred in the command below) is to apply Envoy configuration and deploy Envoy proxy, that wire up the Talker API behind the reverse-proxy and external authorization with the Authorino instance. -For details and instructions to setup Envoy manually, see _Protect a service > Setup Envoy_ in the [Getting Started](./../getting-started.md#1-setup-envoy) page. For a simpler and straighforward way to manage an API, without having to manually install or configure Envoy and Authorino, check out [Kuadrant](https://github.com/kuadrant). +For details and instructions to setup Envoy manually, see _Protect a service > Setup Envoy_ in the [Getting Started](./../getting-started.md#step-setup-envoy) page. For a simpler and straightforward way to manage an API, without having to manually install or configure Envoy and Authorino, check out [Kuadrant](https://github.com/kuadrant). ```sh kubectl apply -f https://raw.githubusercontent.com/kuadrant/authorino-examples/main/envoy/envoy-notls-deploy.yaml diff --git a/docs/user-guides/opa-authorization.md b/docs/user-guides/opa-authorization.md index 49f67e84..64e738aa 100644 --- a/docs/user-guides/opa-authorization.md +++ b/docs/user-guides/opa-authorization.md @@ -64,13 +64,13 @@ spec: EOF ``` -The command above will deploy Authorino as a separate service (as oposed to a sidecar of the protected API and other architectures), in `namespaced` reconciliation mode, and with TLS termination disabled. For other variants and deployment options, check out the [Getting Started](./../getting-started.md#2-deploy-an-authorino-instance) section of the docs, the [Architecture](./../architecture.md#topologies) page, and the spec for the [`Authorino`](https://github.com/Kuadrant/authorino-operator/blob/main/config/crd/bases/operator.authorino.kuadrant.io_authorinos.yaml) CRD in the Authorino Operator repo. +The command above will deploy Authorino as a separate service (as opposed to a sidecar of the protected API and other architectures), in `namespaced` reconciliation mode, and with TLS termination disabled. For other variants and deployment options, check out the [Getting Started](./../getting-started.md#step-request-an-authorino-instance) section of the docs, the [Architecture](./../architecture.md#topologies) page, and the spec for the [`Authorino`](https://github.com/Kuadrant/authorino-operator/blob/main/config/crd/bases/operator.authorino.kuadrant.io_authorinos.yaml) CRD in the Authorino Operator repo. ## 4. Setup Envoy The following bundle from the Authorino examples (manifest referred in the command below) is to apply Envoy configuration and deploy Envoy proxy, that wire up the Talker API behind the reverse-proxy and external authorization with the Authorino instance. -For details and instructions to setup Envoy manually, see _Protect a service > Setup Envoy_ in the [Getting Started](./../getting-started.md#1-setup-envoy) page. For a simpler and straighforward way to manage an API, without having to manually install or configure Envoy and Authorino, check out [Kuadrant](https://github.com/kuadrant). +For details and instructions to setup Envoy manually, see _Protect a service > Setup Envoy_ in the [Getting Started](./../getting-started.md#step-setup-envoy) page. For a simpler and straightforward way to manage an API, without having to manually install or configure Envoy and Authorino, check out [Kuadrant](https://github.com/kuadrant). ```sh kubectl apply -f https://raw.githubusercontent.com/kuadrant/authorino-examples/main/envoy/envoy-notls-deploy.yaml @@ -84,7 +84,7 @@ kubectl port-forward deployment/envoy 8000:8000 & ## 5. Create the `AuthConfig` -In this example, we will use OPA to implement a read-only policy for requests coming from outside of a trusted network (IP range 192.168.1/24). +In this example, we will use OPA to implement a read-only policy for requests coming from outside a trusted network (IP range 192.168.1/24). The implementation relies on the [`X-Forwarded-For`](https://datatracker.ietf.org/doc/html/rfc7239) HTTP header to read the client's IP address. @@ -156,7 +156,7 @@ curl -H 'Authorization: APIKEY ndyBzreUzF4zqDQsqSPMHkRhriEOtcRx' \ # HTTP/1.1 200 OK ``` -Ouside the trusted network: +Outside the trusted network: ```sh curl -H 'Authorization: APIKEY ndyBzreUzF4zqDQsqSPMHkRhriEOtcRx' \ diff --git a/docs/user-guides/passing-credentials.md b/docs/user-guides/passing-credentials.md index 7013015e..b9a27eeb 100644 --- a/docs/user-guides/passing-credentials.md +++ b/docs/user-guides/passing-credentials.md @@ -62,13 +62,13 @@ spec: EOF ``` -The command above will deploy Authorino as a separate service (as oposed to a sidecar of the protected API and other architectures), in `namespaced` reconciliation mode, and with TLS termination disabled. For other variants and deployment options, check out the [Getting Started](./../getting-started.md#2-deploy-an-authorino-instance) section of the docs, the [Architecture](./../architecture.md#topologies) page, and the spec for the [`Authorino`](https://github.com/Kuadrant/authorino-operator/blob/main/config/crd/bases/operator.authorino.kuadrant.io_authorinos.yaml) CRD in the Authorino Operator repo. +The command above will deploy Authorino as a separate service (as opposed to a sidecar of the protected API and other architectures), in `namespaced` reconciliation mode, and with TLS termination disabled. For other variants and deployment options, check out the [Getting Started](./../getting-started.md#step-request-an-authorino-instance) section of the docs, the [Architecture](./../architecture.md#topologies) page, and the spec for the [`Authorino`](https://github.com/Kuadrant/authorino-operator/blob/main/config/crd/bases/operator.authorino.kuadrant.io_authorinos.yaml) CRD in the Authorino Operator repo. ## 4. Setup Envoy The following bundle from the Authorino examples (manifest referred in the command below) is to apply Envoy configuration and deploy Envoy proxy, that wire up the Talker API behind the reverse-proxy and external authorization with the Authorino instance. -For details and instructions to setup Envoy manually, see _Protect a service > Setup Envoy_ in the [Getting Started](./../getting-started.md#1-setup-envoy) page. For a simpler and straighforward way to manage an API, without having to manually install or configure Envoy and Authorino, check out [Kuadrant](https://github.com/kuadrant). +For details and instructions to setup Envoy manually, see _Protect a service > Setup Envoy_ in the [Getting Started](./../getting-started.md#step-setup-envoy) page. For a simpler and straightforward way to manage an API, without having to manually install or configure Envoy and Authorino, check out [Kuadrant](https://github.com/kuadrant). ```sh kubectl apply -f https://raw.githubusercontent.com/kuadrant/authorino-examples/main/envoy/envoy-notls-deploy.yaml diff --git a/docs/user-guides/resource-level-authorization-uma.md b/docs/user-guides/resource-level-authorization-uma.md index a71d1a9b..fb94cebb 100644 --- a/docs/user-guides/resource-level-authorization-uma.md +++ b/docs/user-guides/resource-level-authorization-uma.md @@ -1,6 +1,6 @@ # User guide: Resource-level authorization with User-Managed Access (UMA) resource registry -Fetch resource metadata relevant for your authorization policies from Keycloak authorization clients, unsing User-Managed Access (UMA) protocol. +Fetch resource metadata relevant for your authorization policies from Keycloak authorization clients, using User-Managed Access (UMA) protocol.
    @@ -76,13 +76,13 @@ spec: EOF ``` -The command above will deploy Authorino as a separate service (as oposed to a sidecar of the protected API and other architectures), in `namespaced` reconciliation mode, and with TLS termination disabled. For other variants and deployment options, check out the [Getting Started](./../getting-started.md#2-deploy-an-authorino-instance) section of the docs, the [Architecture](./../architecture.md#topologies) page, and the spec for the [`Authorino`](https://github.com/Kuadrant/authorino-operator/blob/main/config/crd/bases/operator.authorino.kuadrant.io_authorinos.yaml) CRD in the Authorino Operator repo. +The command above will deploy Authorino as a separate service (as opposed to a sidecar of the protected API and other architectures), in `namespaced` reconciliation mode, and with TLS termination disabled. For other variants and deployment options, check out the [Getting Started](./../getting-started.md#step-request-an-authorino-instance) section of the docs, the [Architecture](./../architecture.md#topologies) page, and the spec for the [`Authorino`](https://github.com/Kuadrant/authorino-operator/blob/main/config/crd/bases/operator.authorino.kuadrant.io_authorinos.yaml) CRD in the Authorino Operator repo. ## 4. Setup Envoy The following bundle from the Authorino examples (manifest referred in the command below) is to apply Envoy configuration and deploy Envoy proxy, that wire up the Talker API behind the reverse-proxy and external authorization with the Authorino instance. -For details and instructions to setup Envoy manually, see _Protect a service > Setup Envoy_ in the [Getting Started](./../getting-started.md#1-setup-envoy) page. For a simpler and straighforward way to manage an API, without having to manually install or configure Envoy and Authorino, check out [Kuadrant](https://github.com/kuadrant). +For details and instructions to setup Envoy manually, see _Protect a service > Setup Envoy_ in the [Getting Started](./../getting-started.md#step-setup-envoy) page. For a simpler and straightforward way to manage an API, without having to manually install or configure Envoy and Authorino, check out [Kuadrant](https://github.com/kuadrant). ```sh kubectl apply -f https://raw.githubusercontent.com/kuadrant/authorino-examples/main/envoy/envoy-notls-deploy.yaml @@ -98,7 +98,7 @@ kubectl port-forward deployment/envoy 8000:8000 & This user guide's implementation for resource-level authorization leverages part of Keycloak's User-Managed Access (UMA) support. Authorino will fetch resource attributes stored in a Keycloak resource server client. -The Keycloak server also provides the identities. The `sub` claim of the Keycloak-issued ID tokens must match the owner of the requested resource, identitfied by the URI of the request. +The Keycloak server also provides the identities. The `sub` claim of the Keycloak-issued ID tokens must match the owner of the requested resource, identified by the URI of the request. Create a required secret, used by Authorino to start the authentication with the UMA registry. diff --git a/docs/user-guides/sharding.md b/docs/user-guides/sharding.md index 08172711..9a1d0b1f 100644 --- a/docs/user-guides/sharding.md +++ b/docs/user-guides/sharding.md @@ -82,7 +82,7 @@ spec: EOF ``` -The commands above will deploy Authorino as a separate service (as oposed to a sidecar of the protected API and other architectures), in `cluster-wide` reconciliation mode, and with TLS termination disabled. For other variants and deployment options, check out the [Getting Started](./../getting-started.md#2-deploy-an-authorino-instance) section of the docs, the [Architecture](./../architecture.md#topologies) page, and the spec for the [`Authorino`](https://github.com/Kuadrant/authorino-operator/blob/main/config/crd/bases/operator.authorino.kuadrant.io_authorinos.yaml) CRD in the Authorino Operator repo. +The commands above will deploy Authorino as a separate service (as opposed to a sidecar of the protected API and other architectures), in `cluster-wide` reconciliation mode, and with TLS termination disabled. For other variants and deployment options, check out the [Getting Started](./../getting-started.md#step-request-an-authorino-instance) section of the docs, the [Architecture](./../architecture.md#topologies) page, and the spec for the [`Authorino`](https://github.com/Kuadrant/authorino-operator/blob/main/config/crd/bases/operator.authorino.kuadrant.io_authorinos.yaml) CRD in the Authorino Operator repo. ## 3. Create a namespace for user resources diff --git a/docs/user-guides/token-normalization.md b/docs/user-guides/token-normalization.md index 4cec2cf8..5d62e8ec 100644 --- a/docs/user-guides/token-normalization.md +++ b/docs/user-guides/token-normalization.md @@ -2,7 +2,7 @@ Broadly, the term token normalization in authentication systems usually implies the exchange of an authentication token, as provided by the user in a given format, and/or its associated identity claims, for another freshly issued token/set of claims, of a given (normalized) structure or format. -The most typical use-case for token normalization envolves accepting tokens issued by multiple trusted sources and of often varied authentication protocols, while ensuring that the eventual different data structures adopted by each of those sources are normalized, thus allowing to simplify policies and authorization checks that depend on those values. In general, however, any modification to the identity claims can be for the purpose of normalization. +The most typical use-case for token normalization involves accepting tokens issued by multiple trusted sources and of often varied authentication protocols, while ensuring that the eventual different data structures adopted by each of those sources are normalized, thus allowing to simplify policies and authorization checks that depend on those values. In general, however, any modification to the identity claims can be for the purpose of normalization. This user guide focuses on the aspect of mutation of the identity claims resolved from an authentication token, to a certain data format and/or by extending them, so that required attributes can thereafter be trusted to be present among the claims, in a desired form. For such, Authorino allows to extend resolved identity objects with custom attributes (custom claims) of either static values or with values fetched from the [Authorization JSON](./../architecture.md#the-authorization-json). @@ -77,13 +77,13 @@ spec: EOF ``` -The command above will deploy Authorino as a separate service (as oposed to a sidecar of the protected API and other architectures), in `namespaced` reconciliation mode, and with TLS termination disabled. For other variants and deployment options, check out the [Getting Started](./../getting-started.md#2-deploy-an-authorino-instance) section of the docs, the [Architecture](./../architecture.md#topologies) page, and the spec for the [`Authorino`](https://github.com/Kuadrant/authorino-operator/blob/main/config/crd/bases/operator.authorino.kuadrant.io_authorinos.yaml) CRD in the Authorino Operator repo. +The command above will deploy Authorino as a separate service (as opposed to a sidecar of the protected API and other architectures), in `namespaced` reconciliation mode, and with TLS termination disabled. For other variants and deployment options, check out the [Getting Started](./../getting-started.md#step-request-an-authorino-instance) section of the docs, the [Architecture](./../architecture.md#topologies) page, and the spec for the [`Authorino`](https://github.com/Kuadrant/authorino-operator/blob/main/config/crd/bases/operator.authorino.kuadrant.io_authorinos.yaml) CRD in the Authorino Operator repo. ## 4. Setup Envoy The following bundle from the Authorino examples (manifest referred in the command below) is to apply Envoy configuration and deploy Envoy proxy, that wire up the Talker API behind the reverse-proxy and external authorization with the Authorino instance. -For details and instructions to setup Envoy manually, see _Protect a service > Setup Envoy_ in the [Getting Started](./../getting-started.md#1-setup-envoy) page. For a simpler and straighforward way to manage an API, without having to manually install or configure Envoy and Authorino, check out [Kuadrant](https://github.com/kuadrant). +For details and instructions to setup Envoy manually, see _Protect a service > Setup Envoy_ in the [Getting Started](./../getting-started.md#step-setup-envoy) page. For a simpler and straightforward way to manage an API, without having to manually install or configure Envoy and Authorino, check out [Kuadrant](https://github.com/kuadrant). ```sh kubectl apply -f https://raw.githubusercontent.com/kuadrant/authorino-examples/main/envoy/envoy-notls-deploy.yaml diff --git a/docs/user-guides/validating-webhook.md b/docs/user-guides/validating-webhook.md index 1dbd439c..c89e9e73 100644 --- a/docs/user-guides/validating-webhook.md +++ b/docs/user-guides/validating-webhook.md @@ -2,7 +2,7 @@ Authorino provides an interface for raw HTTP external authorization requests. This interface can be used for integrations other than the typical Envoy gRPC protocol, such as (though not limited to) using Authorino as a generic Kubernetes ValidatingWebhook service. -The rules to validate a request to the Kubernetes API – typically a `POST`, `PUT` or `DELETE` request targeting a particular Kubernetes resource or collection –, according to which either the change will be deemed accepted or not, are written in an Authorino `AuthConfig` custom resource. Authentication and authorization are performed by the Kubernetes API server as usual, with auth features of Authorino implementing the aditional validation within the scope of an `AdmissionReview` request. +The rules to validate a request to the Kubernetes API – typically a `POST`, `PUT` or `DELETE` request targeting a particular Kubernetes resource or collection –, according to which either the change will be deemed accepted or not, are written in an Authorino `AuthConfig` custom resource. Authentication and authorization are performed by the Kubernetes API server as usual, with auth features of Authorino implementing the additional validation within the scope of an `AdmissionReview` request. This user guide provides an example of using Authorino as a Kubernetes ValidatingWebhook service that validates requests to `CREATE` and `UPDATE` Authorino `AuthConfig` resources. In other words, we will use Authorino as a validator inside the cluster that decides what is a valid AuthConfig for any application which wants to rely on Authorino to protect itself. @@ -17,7 +17,7 @@ This user guide provides an example of using Authorino as a Kubernetes Validatin - Authorino API key authentication - All metadata pulled from external sources must be cached for precisely 5 minutes (300 seconds) -For convinience, the same instance of Authorino used to enforce the AuthConfig associated with the validating webhook will also be targeted for the sample AuthConfigs created to test the validation. For using different instances of Authorino for the validating webhook and for protecting applications behind a proxy, check out the section about [sharding](./../architecture.md#sharding) in the docs. There is also a [user guide](./sharding.md) on the topic, with concrete examples. +For convenience, the same instance of Authorino used to enforce the AuthConfig associated with the validating webhook will also be targeted for the sample AuthConfigs created to test the validation. For using different instances of Authorino for the validating webhook and for protecting applications behind a proxy, check out the section about [sharding](./../architecture.md#sharding) in the docs. There is also a [user guide](./sharding.md) on the topic, with concrete examples.
    @@ -109,7 +109,7 @@ spec: EOF ``` -The command above will deploy Authorino as a separate service (as oposed to a sidecar of the protected API and other architectures), in `cluster-wide` reconciliation mode, and with TLS termination enabled. For other variants and deployment options, check out the [Getting Started](./../getting-started.md#2-deploy-an-authorino-instance) section of the docs, the [Architecture](./../architecture.md#topologies) page, and the spec for the [`Authorino`](https://github.com/Kuadrant/authorino-operator/blob/main/config/crd/bases/operator.authorino.kuadrant.io_authorinos.yaml) CRD in the Authorino Operator repo. +The command above will deploy Authorino as a separate service (as opposed to a sidecar of the protected API and other architectures), in `cluster-wide` reconciliation mode, and with TLS termination enabled. For other variants and deployment options, check out the [Getting Started](./../getting-started.md#step-request-an-authorino-instance) section of the docs, the [Architecture](./../architecture.md#topologies) page, and the spec for the [`Authorino`](https://github.com/Kuadrant/authorino-operator/blob/main/config/crd/bases/operator.authorino.kuadrant.io_authorinos.yaml) CRD in the Authorino Operator repo. ## 3. Create the `AuthConfig` and related `ClusterRole`