# istio-ecosystem/authservice architecture

> Architecture diagram of the GitHub repository istio-ecosystem/authservice, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/istio-ecosystem/authservice
- Repository: https://github.com/istio-ecosystem/authservice

## Overview

##### Project Type and Purpose
- The project is an external authorization service (“authservice”) that integrates with Istio and Kubernetes environments. Its primary purpose is to handle OIDC flows (i.e., the Authorization Code Grant Flow) to provide transparent login/logout, session management, and fine-grained URL protection.

##### Main Components
a. Client/Consumer:
- External clients or end-user applications initiating requests via a browser or API.
b. Envoy/Istio Gateway or Sidecar:
- How Envoy or Istio intercepts traffic and interacts with authservice to delegate authentication/authorization.
c. Authservice Core:
- Processing incoming auth requests.
- Invoking OIDC logic and session management.
- Inside the core, it’s helpful to decompose internal modules such as:
- internal/server – which handles HTTP endpoints (health checks, auth processing, request logging, etc.).
- internal/authz – which encapsulates the authorization logic and flows.
- internal/oidc – details functions like token handling, session management, discovery, delegation to OIDC providers, and possibly Redis integration (as seen in redis.go).
- internal/k8s – which includes controllers and secret management for Kubernetes integration.
- internal/http and logging packages – which manage HTTP layer utilities and structured logging.
d. Configuration & Protobuf Setup:
- A component that represents configuration management. Note the config directory which holds proto definitions (in config/v1), generated code under config/gen, and supporting files. This ensures that the service is highly configurable.
e. External Systems & Services:
- External OIDC Providers: Identify connections to generic OIDC providers (e.g., Keycloak is present in the e2e tests).
- Redis: As a session store, indicated by the internal/oidc/redis.go module and accompanying e2e tests.
- CI/CD and Deployment:
- Use of GitHub actions workflows (located in .github/workflows) showing a pipeline for testing, code scanning, publishing, etc.
- Docker (Dockerfile and run-in-docker.sh) for containerization.
- Deployment-oriented components in the e2e folder which include test harnesses for Istio clusters, keycloak, and mocked services.

##### Relationships and Interactions
- Data Flow:
- Further illustrate interactions inside core components where, for instance, the authservice invokes OIDC routines (discovery, token issuance, session refresh) and might interact with Redis for session caching.
- Dependencies:
- Bidirectional dependencies between the configuration components and the core business logic. Likewise, demonstrate how the k8s components may watch secrets or configuration changes in a cluster.

##### Architectural Patterns and Design Principles
- Modularity: The service is broken up into distinct internal packages (authz, oidc, server, k8s) which help enforce separation of concerns.
- Configuration-Driven: With protobufs and configuration files in the config directory, the design is strongly oriented toward a dynamically configurable system.

##### Final Touches
- Clarity by breaking down monolithic parts into subcomponents where relevant, especially given the extensive internal package organization.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Interface
    subgraph "External Interface"
        Client("External Client"):::network
        Gateway("Envoy/Istio Gateway / Sidecar"):::network
    end

    %% Authservice Core
    subgraph "Authservice Core"
        Main("Authservice Core (cmd/main.go)"):::core
        HTTPServer("HTTP Server (internal/server)"):::core
        Authz("Authz Module (internal/authz)"):::core
        OIDC("OIDC Module (internal/oidc)"):::core
        K8s("K8s Module (internal/k8s)"):::core
        HTTputil("HTTP & Logging Utils (internal/http, internal/logging.go)"):::core
    end

    %% Configuration and Deployment
    subgraph "Configuration & Deployment"
        Config("Configuration Engine (config/v1 & config/gen)"):::config
        CICD("CI/CD Pipeline (.github/workflows)"):::config
        Docker("Docker Setup (Dockerfile & run-in-docker.sh)"):::config
        E2E("E2E Test Artifacts (e2e/istio, e2e/keycloak)"):::config
        RedisManifest("Redis Manifest (e2e/istio/cluster/manifests/redis.yaml)"):::config
    end

    %% External Systems
    subgraph "External Systems"
        OIDCProv("External OIDC (Keycloak)"):::external
        Redis("Redis Session Store"):::external
    end

    %% Data Flow Connections
    Client -->|"initiates request"| Gateway
    Gateway -->|"for authentication"| Main
    Main -->|"routes request"| HTTPServer
    Main -->|"invokes"| Authz
    Main -->|"triggers"| OIDC
    Main -->|"manages secrets"| K8s
    Main -->|"logs & HTTP utilities"| HTTputil

    %% Internal Module Interactions
    OIDC -->|"token exchange"| OIDCProv
    OIDC -->|"session caching"| Redis
    K8s -->|"watches config"| Config
    HTTPServer -->|"handles healthcheck"| Main

    %% Configuration & Deployment Relationships
    Config ---|"configures"| Main
    CICD -->|"deploys"| Main
    CICD -->|"triggers"| Gateway
    Docker -->|"containerizes"| Main
    E2E -->|"tests"| Gateway
    E2E -->|"validates"| OIDCProv
    RedisManifest ---|"deploys"| Redis

    %% Click Events
    click Main "https://github.com/istio-ecosystem/authservice/blob/main/cmd/main.go"
    click HTTPServer "https://github.com/istio-ecosystem/authservice/tree/main/internal/server"
    click Authz "https://github.com/istio-ecosystem/authservice/tree/main/internal/authz"
    click OIDC "https://github.com/istio-ecosystem/authservice/tree/main/internal/oidc"
    click K8s "https://github.com/istio-ecosystem/authservice/tree/main/internal/k8s"
    click HTTputil "https://github.com/istio-ecosystem/authservice/tree/main/internal/http"
    click HTTputil "https://github.com/istio-ecosystem/authservice/blob/main/internal/logging.go"
    click Config "https://github.com/istio-ecosystem/authservice/tree/main/config/v1"
    click Config "https://github.com/istio-ecosystem/authservice/tree/main/config/gen"
    click Gateway "https://github.com/istio-ecosystem/authservice/tree/main/e2e/istio"
    click OIDCProv "https://github.com/istio-ecosystem/authservice/tree/main/e2e/keycloak"
    click Redis "https://github.com/istio-ecosystem/authservice/blob/main/internal/oidc/redis.go"
    click RedisManifest "https://github.com/istio-ecosystem/authservice/blob/main/e2e/istio/cluster/manifests/redis.yaml"
    click CICD "https://github.com/istio-ecosystem/authservice/tree/main/.github/workflows"
    click Docker "https://github.com/istio-ecosystem/authservice/tree/main/Dockerfile"
    click Docker "https://github.com/istio-ecosystem/authservice/blob/main/run-in-docker.sh"

    %% Styles
    classDef network fill:#add8e6,stroke:#000,stroke-width:2px;
    classDef core fill:#90ee90,stroke:#000,stroke-width:2px;
    classDef external fill:#ffcc99,stroke:#000,stroke-width:2px;
    classDef config fill:#d3d3d3,stroke:#000,stroke-width:2px;
```
