soluto/airbag

airbag

![Build Status]([***]

airbag是一个轻量级的Docker容器sidecar工具，旨在帮助用户处理JWT认证和基础指标收集，减轻服务本身的负担。

核心功能

1. JWT认证：验证令牌的有效性、受众（Audience）和发行方（Issuer），支持多认证提供者
2. 基础指标收集：通过AppMetrics收集服务指标，可通过指定端点访问
3. 路由配置：支持免认证路由和路由白名单
4. 外部授权：与Open Policy Agent（OPA）集成，实现细粒度的请求授权

使用场景

1. Kubernetes集群中与服务容器同Pod部署，统一处理认证和监控
2. 需要简化JWT认证流程的微服务应用
3. 需收集基础运行指标的轻量级服务
4. 需要多认证源或外部授权策略的场景

配置说明

airbag通过环境变量配置，支持以下选项：

• BACKEND_HOST_NAME：后端服务的主机名或IP，认证通过后请求将转发至此，默认值为localhost
• BACKEND_SERVICE_PORT：后端服务暴露的端口，默认值为80
• AUTHORITY：JWT认证的授权服务器地址
• AUDIENCE：仅接受该受众的令牌
• ISSUER：仅接受该发行方的令牌
• UNAUTHENTICATED_ROUTES：无需认证的后端路由（用逗号分隔，支持通配符*），例如/isAlive,/swagger/*
• COLLECT_METRICS：是否启用指标收集，启用后可通过/airbag/metrics访问指标
• AUTHORIZED_ROUTES_ENABLED：是否启用路由白名单

多认证提供者配置

为每个提供者添加前缀即可支持多认证源：

• AUTHORITY_{{providerName}}：提供者的授权服务器地址
• AUDIENCE_{{providerName}}：提供者的受众
• ISSUER_{{providerName}}：提供者的发行方

示例：

yaml
# Foo提供者配置
- AUTHORITY_FOO=http://foo_auth_server
- ISSUER_FOO=http://foo
- AUDIENCE_FOO=foo_api
# Bar提供者配置
- AUTHORITY_BAR=http://bar_auth_server
- ISSUER_BAR=http://bar
- AUDIENCE_BAR=bar_api

Open Policy Agent（OPA）集成

通过OPA实现外部授权，需配置以下变量：

• OPA_URL：OPA服务器地址
• OPA_QUERY_PATH：OPA查询路径（需返回布尔结果）
• OPA_MODE：授权模式（Disabled：禁用；LogOnly：仅日志；Enabled：启用授权）

部署示例

Docker Run

bash
docker run -d \
  --name airbag \
  -e BACKEND_HOST_NAME=localhost \
  -e BACKEND_SERVICE_PORT=8080 \
  -e AUTHORITY=https://auth.example.com \
  -e AUDIENCE=my_service \
  -e COLLECT_METRICS=true \
  soluto/airbag

Kubernetes Pod示例

yaml
apiVersion: v1
kind: Pod
metadata:
  name: my-service-pod
spec:
  containers:
  - name: my-service
    image: my-service-image
    ports:
    - containerPort: 8080
  - name: airbag
    image: soluto/airbag
    env:
    - name: BACKEND_HOST_NAME
      value: localhost
    - name: BACKEND_SERVICE_PORT
      value: "8080"
    - name: AUTHORITY
      value: "[***]"
    - name: AUDIENCE
      value: "my_service"