Authorino

Cloud-native AuthN/AuthZ enforcer for Zero Trust API protection.

• User identity verification and authentication
  JWTs, OIDC, OAuth2, K8s TokenReview, API key, mTLS, HMAC
• Ad hoc authorization metadata
  HTTP GET and GET-by-POST, OIDC UserInfo, UMA-protected resource data
• Authorization policy enforcement
  JSON/JWT pattern matching policies, OPA/Rego policies, K8s SubjectAccessReview
• Token normalization / Edge Authentication
  OIDC-compliant "Festival Wristband" ID tokens (signed JWTs)
• Dynamic Metadata
  Added HTTP headers and support for Envoy Dynamic Metadata

Authorino enables hybrid API security layer, with usually no code changes required, tailor-made for your combination of authentication standards and protocols and authorization policies of choice.

Authorino builds on top of the Envoy Proxy external authorization gRPC protocol, and complies with Red Hat Kuadrant architecture.

---

How it works

1. An application client (API consumer) obtains credentials or access token to consume resources of the Upstream API, 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)
3. Identity verification phase - Authorino verifies the identity of the the consumer, where at least one authentication method/identity provider must succeed
4. Metadata phase - Authorino fetches aditional metadata for the authorization from external sources (optional)
5. Policy enforcement phase - Authorino takes as input a JSON composed of context information, resolved identity and fetched additional metadata from previous phases, and triggers the evaluation of user-defined authorization policies
6. Response 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 API within added HTTP headers or as Envoy Dynamic Metadata (optional)
7. Authorino and Envoy settle the authorization protocol with either OK/NOK response (plus extra details available in the X-Ext-Auth-Reason and WWW-Authenticate headers when NOK)
8. If authorized, Envoy triggers other HTTP filters in the chain piping dynamic metadata returned by Authorino, and ultimately redirects the request to the Upstream API
9. The Upstream API serves the requested resource to the consumer

The core phases of Authorino "Auth Pipeline" (depicted in the diagram as steps 3 to 6) rely on well-established industry standards and protocols, such as OpenID Connect (OIDC), User-Managed Access (UMA), Open Policy Agent (OPA), mutual Transport Layer Security (mTLS), plus Authorino-specific implementations for simpler use-cases, to enable Zero Trust security for APIs, while allowing developers to pick and combine protocols and settings into one cloud-native straighforward configuration (based on Kubernetes Custom Resource Definitions).

List of features

Feature		Description	Stage
Identity verification	OpenID Connect (OIDC)	Offline signature verification and time validation of OpenID Connect ID tokens (JWTs). Authorino caches the OpenID Connect configuration and JSON Web Key Set (JWKS) obtained from the OIDC Discovery well-known endpoint, and uses them to verify and validate tokens in request time.	Ready
	OAuth 2.0 (token introspection)	Online introspection of access tokens with an OAuth 2.0 server.	Ready
	Kubernetes authN	Online verification of Kubernetes access tokens through the Kubernetes TokenReview API. The audiences of the token MUST include the ones specified in the API protection state, which, when omitted, is assumed to be equal to the host name of the protected API. It can be used to authenticate Kubernetes Service Accounts (e.g. other pods running in the cluster) and users of the cluster in general.	Ready
	OpenShift OAuth (user-echo endpoint)	Online token introspection of OpenShift-valid access tokens based on OpenShift's user-echo endpoint.	In analysis
	API key	Represented as Kubernetes Secret resources. The secret MUST contain an entry api_key that holds the value of the API key. The secret MUST also contain at least one lable authorino.3scale.net/managed-by with whatever value, plus any number of optional labels. The labels are used by Authorino to match corresponding API protections that accept the API key as valid credential.	Ready
	mTLS	Authentication by client certificate.	Planned (#8)
	HMAC	Authentication by Hash Message Authentication Code (HMAC), where a unique secret generated per API consumer, combined with parts of the request metadata, is used to generate a hash that is passed as authentication value by the client and verified by Authorino.	Planned (#9)
Ad hoc authorization metadata	OIDC user info	Online request to OpenID Connect User Info endpoint. Requires an associated OIDC identity source.	Ready
	UMA-protected resource attributes	Online request to a User-Managed Access (UMA) server to fetch data from the UMA Resource Set API.	Ready
	External HTTP service	Generic online HTTP request to an external service (GET or POST). It can be used to fetch online metadata for the auth pipeline or as a web hook.	Ready
Policy enforcement	JSON pattern matching (e.g. JWT claims)	Authorization policies represented as simple JSON pattern-matching rules. Values can be selected from the authorization JSON built along the auth pipeline. Operations include equals (eq), not equal (neq), includes (incl; for arrays), excludes (excl; for arrays) and matches (matches; for regular expressions). Individuals policies can be optionally skipped based on "conditions" represented with similar data selectors and operators.	Ready
	OPA Rego policies	Built-in evaluator of Open Policy Agent (OPA) inline Rego policies. The policies written in Rego language are compiled and cached by Authorino in reconciliation-time, and evaluated against the authorization JSON in every request.	Ready
	Kubernetes authZ	Checks with the underlying Kubernetes cluster about whether the user can access the requested API resource, according to the authorization rules defined in the cluster's RBAC. Based on Kubernetes SubjectAccessReview	Ready
	Keycloak (UMA-compliant Authorization API)	Online delegation of authorization to a Keycloak server.	In analysis
HTTP external authorization service	Generic online delegation of authorization to an external HTTP service.	In analysis
Custom responses	Festival Wristbands	Signed JWTs issued by Authorino at the end of the auth pipeline and passed back to the client (usually in an added HTTP header). Opt-in feature that can be used to implement Edge Authentication Architecture (EAA) and enable token normalization, with support to static and dynamic custom claims added to the JTW. Authorino exposes the OIDC discovery endpoints to verify and validate the wristbands, including by Authorino itself (using the OIDC identity verification feature).	Ready
	Dynamic JSON	User-defined JSON objects generated from static or dynamic data of the auth pipeline, and passed back to the client either within added HTTP headers or as Envoy Dynamic Metadata.	Ready
Caching	OIDC and UMA configs	OpenID Connect and User-Managed Access configurations discovered in reconciliation-time.	Ready
	JSON Web Keys (JWKs) and JSON Web Ket Sets (JWKS)	JSON signature verification certificates discovered usually in reconciliation-time, following an OIDC discovery associated to an identity source.	Ready
	Revoked access tokens	Caching of access tokens identified as revoked before expiration.	In analysis (#19)
	Resource data	Caching of resource data obtained in previous requests.	Planned (#21)
	Compiled Rego policies	Performed automatically by Authorino in reconciliation-time for the authorization policies based on the built-in OPA module.	Ready
	Repeated requests	For consecutive requests performed, within a given period of time, by a same user that request for a same resource, such that the result of the auth pipeline can be proven that would not change.	In analysis (#20)
External policy registry		Fetching of compatible policies from an external registry, in reconciliation-time.	Planned (#115)
Multitenancy		Managed instances of Authorino offered to API providers who create and maintain their own API protection states within their own realms and namespaces.	Ready

For a detailed description of the features above, refer to the Architecture page.

Architecture

The Architecture section of the docs covers the details of protecting your APIs with Envoy and Authorino, including a description of the components involved and specification of the Authorino AuthConfig Custom Resource Definition (CRD).

You will also find in that section information about the Authorino Auth Pipeline, and detailed description of features.

Usage

1. Deploy Authorino to the Kubernetes server
2. Have your upstream API ready to be protected
3. Write and apply a authorino.3scale.net/AuthConfig custom resource declaring the desired state of the protection of your API

Examples and Tutorials

The Examples page lists several use cases and demonstrates how to implement those as Authorino custom resources. Each example use case presents a feature of Authorino and is independent from the other.

The Authorino Tutorials provide guided examples for deploying and protecting an API with Authorino and the Envoy proxy, where each tutorial combines multiple features of Authorino into one cohesive use case, resembling real life use cases.

Terminology

You can find definitions for terms used in this document and others in the Terminology document.

Contributing

If you are interested in contributing to Authorino, please refer to instructions available here. You may as weel check our Code of Conduct.