soluto/airbag repository overview

⁠airbag

airbag is a tiny sidecar for your docker containers, meant to handle jwt authentication and basic metrics collection for you.

⁠How to use it

1. Deploy airbag next to your container (In kubernetes, you would usually put them in the same pod).
   airbag's image can be found at https://hub.docker.com/r/soluto/airbag/⁠
2. Configure airbag's BACKEND_HOST_NAME (If airbag and your container are in the same pod, set this to localhost) and BACKEND_SERVICE_PORT (the port your service is listening on).
3. Route traffic directed to your container to airbag

⁠Configuration

airbag uses environment variables for configuration, and supports the following options:

• BACKEND_HOST_NAME - The name or ip of your service. Requests will be forwarded to this host once authenticated. Defaults to localhost.
• BACKEND_SERVICE_PORT - The port exposed by your service. Requests will be forwarded to this port on the host once authenticated. Defaults to 80.
• AUTHORITY - The jwt authentication authority to use for authentication and token validation.
• AUDIENCE - Only tokens for this audience will be accepted and considered valid.
• ISSUER - Only tokens from this issuer will be accepted and considered valid.
• UNAUTHENTICATED_ROUTES - Backend routes that shouldn't be authenticated (for example, a health-check endpoint). Seperate the routes with ,.
  example: /isAlive,/health,/something/anonymous
  If a route contains a wildcard ( * ) then all matching routes will not be authenticated (For example - /swagger/* will cause all routes which start with /swagger/ to be unauthenticated.
• COLLECT_METRICS - Enable or disable metrics collection. Metrics are collected using AppMetrics⁠. Metrics will be available under /airbag/metrics
• AUTHORIZED_ROUTES_ENABLED - Enable or disable route white-listing.

⁠Using with multiple auth providers

To use multiple auth providers, provide these parmaters for every provider as a prefix:

• AUTHORITY_{{providerName}}
• AUDIENCE_{{providerName}}
• ISSUER_{{providerName}}

⁠Example

# Foo provider parameters
- AUTHORITY_FOO=http://foo_auth_server
- ISSUER_FOO=http://foo
- AUDIENCE_FOO=foo_api
# Bar provider parameters
- AUTHORITY_BAR=http://bar_auth_server
- ISSUER_BAR=http://bar
- AUDIENCE_BAR=bar_api

⁠External Authorization with Open Policy Agent

Airbag support authorization of incoming request with Open Policy Agent⁠(OPA). If enabled, Airbag will query OPA for a decision on each incoming request, and based on OPA decision approve or deny the request. Approved requests will be passed to upstream, denied request will return to client with 403 status code.

⁠Configuration

To use OPA, you need to configure the following environment variables:

• OPA_URL - The URL of the OPA server
• OPA_QUERY_PATH - the path used for OPA query. This path should return a single bollean result.
• OPA_MODE - The mode of OPA authorization. Support 3 values:
  • Disabled - Do not query OPA at all. This is the default value.
  • LogOnly - Query OPA, but only log result - do not perform authorization.
  • Enabled - Query OPA and perform authorization.