authorino

README

Authorino

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

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

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

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

How it works

1. An application client (API consumer) obtains credentials to consume resources of the Upstream API, and sends a request to the Envoy exposed endpoint
2. The Envoy proxy establishes fast gRPC connection with Authorino carrying data of the HTTP request (context info)
3. Identity verification phase - Authorino verifies the identity of the the consumer, where at least one authentication method/identity provider must thrive
4. Ad hoc authorization metadata phase - Authorino integrates external sources of additional metadata (optional)
5. Policy enforcement phase - Authorino takes as input a JSON composed of context information, resolved identity and fetched additional metadata from previous phases, and triggers the evaluation of configured authorization policies
6. Wristband phase – Authorino issues the Festival Wristband OIDC token (optional), with standard and custom claims (static and dynamic values supported), to implement token normalization and/or Edge Authentication Architecture (EAA).
7. Authorino and Envoy settle the authorization protocol with either OK/NOK response (plus extra details available in the X-Ext-Auth-Reason and WWW-Authenticate headers when NOK)
8. If authorized, Envoy redirects to the requested 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), to enable API Zero Trust security, while allowing API developers to pick and combine protocols and settings into one cloud-native configuration (based on Kubernetes Custom Resource Definitions).

List of features

Feature		Description	Stage
Identity verification	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)
	OAuth 2.0 (token introspection)	Online introspection of access tokens with an OAuth 2.0 server.	Ready
	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
	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
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. 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
	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
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)
Festival Wristbands		JWTs issued by Authorino at the end of the auth pipeline and passed back to the client in the HTTP response header X-Ext-Auth-Wristband. Opt-in feature that can be used to enable Edge Authentication and token normalization, as well as to carry data from the external authorization back to the client (with support to static and dynamic custom claims). Authorino also exposes well-known endpoints for OpenID Connect Discovery, so the wristbands can be verified and validated, including by Authorino itself using the OIDC identity verification feature.	Ready
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 Service 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 config.authorino.3scale.net/Service 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.