Skip to content

Authservice

An implementation of Envoy External Authorization, focused on delivering authN/Z solutions for Istio and Kubernetes.

Overview

authservice helps delegate the OIDC Authorization Code Grant Flow to the Istio mesh. authservice is compatible with any standard OIDC Provider as well as other Istio End-user Auth features, including Authentication Policy and RBAC. Together, they allow developers to protect their APIs and web apps without any application code required.

graph LR
  pod("URL") --> authservice
  envoyfilter --> |redirect| pod2("IdP")
  pod2 --> |token| apppods

  subgraph "Authservice"
    subgraph "Any Namespace"
      apppods("Application Pod(s)")
    end

    subgraph "istio-system Namespace"
      envoyfilter{{"Envoy Filter"}}
    end

    subgraph "Authservice Namespace"
      authservice{{"Authservice Service"}} --> envoyfilter
    end

  end

  subgraph "Session Storage (Redis)"
    authservice --> database3[("Authservice DB")]
  end

  subgraph "Logging"
    authservice --> alloy(Alloy) --> loki[(Loki)]
  end

Big Bang Touch Points

Licensing

Authservice utilizes an Apache-2.0 License. The Iron Bank repo for the hardened authservice image can be found here and the Big Bang repo for the authservice Helm Chart can be found here.

Single Sign On

Authservice provides OIDC Single Sign On capabilities for apps that don’t have native support.

Sidecar enrollment

For the sidecar enrollment flow, enable Istio sidecar injection on the workload’s namespace, apply the protect=keycloak label to its Pods, and configure a corresponding Authservice chain. This Deployment fragment adds the Pod label:

spec:
  template:
    metadata:
      labels:
        protect: keycloak

This label can be adjusted via following values in the Big Bang chart:

packages:
  authservice:
    values:
      selector:
        key: protect
        value: keycloak

Ambient enrollment

In ambient mode, Authservice is enforced at a waypoint rather than an injected sidecar. For a package using bb-common as a subchart, configure the protected route under packages.<package>.values.bb-common.routes.inbound.<route>.authservice. The bb-common route example shows the route, issuer and client ID configuration that creates the waypoint and Service-scoped authentication and authorization policies.

Enroll the protected Service through its chart’s supported labels value or a Service patch. The following Service fragment uses the default waypoint name; use the rendered Gateway name if the package enables release-name prefixes:

metadata:
  labels:
    istio.io/use-waypoint: waypoint
    istio.io/ingress-use-waypoint: "true"

The second label sends ingress-gateway traffic through the waypoint as well. The Pod label alone does not enroll an ambient Service. See Service enrollment for the complete workflow. The workload namespace must be enrolled in ambient mode. Gateway API CRDs and the istio-waypoint GatewayClass must be available, the mesh must register the authservice extension provider, and network policies must permit the waypoint to call authservice/authservice on port 10003. Configure a matching Authservice chain in either mode.

Authservice chains

The corresponding chain is loaded into Authservice via the values in the Big Bang chart: For more information see the README.md in the Authservice package.

packages:
  authservice:
    chains:
      example:
        callback_uri: ...
        match: ...
        client_id: ...
        client_secret: ...

Storage

Authservice can be configured to use a local redis deployment (disabled by default) for distributed state storage. This Redis instance is used cache session data.

packages:
  authservice:
    values:
      redis:
        enabled: true

Authservice can also be configured to communicate with external Redis services such as ElastiCache.

packages:
  authservice:
    values:
      global:
        redis_server_uri: "tcp://redis-01.7abc2d.0001.usw2.cache.amazonaws.com:6379"

Big Bang automatically creates one outbound route on port 6379, preferring global.redis_server_uri and otherwise using the first chain-level redis_server_uri. If additional chains use different Redis hosts, add a bb-common.routes.outbound entry for each additional host:

packages:
  authservice:
    values:
      bb-common:
        routes:
          outbound:
            secondary-redis:
              enabled: true
              hosts:
                - redis-02.example.internal
              ports:
                - number: 6379
                  name: redis
                  protocol: TCP

High Availability

When setting replicaCount above 1, Authservice will require an HA redis deployment (see above) in order to function.

Authservice also utilizes a horizontal pod autoscaler, which can be configured with min & max replicas and target CPU & memory utilization:

packages:
  authservice:
    values:
      replicaCount: 2
      redis:
        enabled: true
      autoscaling:
        enabled: false
        minReplicas: 1
        maxReplicas: 3
        targetCPUUtilizationPercentage: 80
        targetMemoryUtilizationPercentage: 80

UI

There is no UI feature for authservice.

Logging

For cluster log collection, see Big Bang Logging Stacks.

Health Checks

The authservice Dockerfile includes a healthcheck and the authservice Helm Chart includes liveness & readiness probes in its deployment:

livenessProbe:
  tcpSocket:
    port: 10003
readinessProbe:
  tcpSocket:
    port: 10003

Dependent Packages

When setting replicaCount above 1, a redis configuration is required.