Skip to content

Cloud-native AuthN/AuthZ enforcer to protect your APIs.

License

Notifications You must be signed in to change notification settings

porueesq/authorino

 
 

Repository files navigation

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

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.

About

Cloud-native AuthN/AuthZ enforcer to protect your APIs.

Resources

License

Code of conduct

Stars

Watchers

Forks

Packages

No packages published

Languages

  • Go 96.4%
  • Makefile 3.4%
  • Dockerfile 0.2%