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.
- An application client (API consumer) obtains credentials to consume resources of the Upstream API, and sends a request to the Envoy exposed endpoint
- The Envoy proxy establishes fast gRPC connection with Authorino carrying data of the HTTP request (context info)
- Identity verification phase - Authorino verifies the identity of the the consumer, where at least one authentication method/identity provider must thrive
- Ad hoc authorization metadata phase - Authorino integrates external sources of additional metadata (optional)
- 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
- 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).
- Authorino and Envoy settle the authorization protocol with either OK/NOK response (plus extra details available in the
X-Ext-Auth-Reason
andWWW-Authenticate
headers when NOK) - If authorized, Envoy redirects to the requested Upstream API
- 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).
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 Account s (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.
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.
- Deploy Authorino to the Kubernetes server
- Have your upstream API ready to be protected
- Write and apply a
config.authorino.3scale.net
/Service
custom resource declaring the desired state of the protection of your API
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.
You can find definitions for terms used in this document and others in the Terminology document.
If you are interested in contributing to Authorino, please refer to instructions available here. You may as weel check our Code of Conduct.