Api Gateway 0.6.2 Readme

Overview

This is a reverse proxy component built with Spring Cloud Gateway. It routes requests to different backend microservices based on the request path.

API Gateway solves below problems:

API Gateway receives all traffic, authenticates the request and aggregates the response from multiple microservices (if required). This keeps the complexity of individual microservices low.
API gateway enables components to talk to each other on the internal network without requiring access to the external interface.
Enables useful features such as circuit breakers, timeouts, retries, rate limiting, centralized logging and monitoring and caching support for all microservices in a centralized place.

API Gateway Components

Security

As this gateway protects applications accessible over the public internet, security is a primary responsibility. The gateway uses OIDC to secure various endpoints.

There are two types of security restrictions that are applied depending on the endpoints. These are

Local Authentication - These are users signed up to the application with their email address and attempting to authenticate and access the Platform Manager endpoints.
SSO Authentication - These are users authenticating with their Organization SSO (Active Directory, LDAP etc) identities.

The Local authentication can be supported by either Auth0 (for SaaS deployments) or Keycloak (for on-prem deployments). Both rely on OAuth2 protocol so effectively there is no difference between them.

Local authentication is configured as below:

local:
  auth:
    # Used to validate the iss claim of the JWT token
    issuerUrlForValidation: ""
    # Used to connect and fetch public keys that signed the JWT token
    jwkSetUri: ""
    # Disable trust chain validation when connecting to Authorization server
    useInsecureTrustManager: false

SSO authentication is only supported with Keycloak. It can be configured as below:

sso:
  keycloak:
    # URL where Keycloak is accessible
    baseUrl: ""
    # Disable trust chain validation when connecting to Authorization server
    useInsecureTrustManager: false

Filters

Route filters allow the modification of the incoming HTTP request or outgoing HTTP response in some manner. Route filters are scoped to a particular route. Spring Cloud Gateway includes many built-in GatewayFilter Factories.

We define a few custom GatewayFilter factories for our use-cases. These are described below:

AdUserHeadersFilterFactory

This filter inspects the JWT token of a request and adds a bunch of HTTP headers to transfer user and tenant information to backend services. The following table lists the JWT claims and the mapped headers:

JWT Claims HTTP Headers

JWT Claims	HTTP Headers
`given_name`	X-User-First-Name
`family_name`	X-User-Last-Name
`email`	X-User-Email
`tenant_name`	X-User-Tenant-Name
`tenant_short_name`	X-User-Tenant-Short-Name
`initial_group`	X-User-Initial-Group

given_name

X-User-First-Name

family_name

X-User-Last-Name

email

X-User-Email

tenant_name

X-User-Tenant-Name

tenant_short_name

X-User-Tenant-Short-Name

initial_group

X-User-Initial-Group

It is the responsibility of the Authorization Server (Auth0 or Keycloak) to ensure the issued tokens have these claims present.

If the claims are not present, the filter skips adding the headers and allows to request to continue for further processing. It does not throw any errors.

PermissionsApiFilterFactory

This filter calls the Permissions API to authorize the request. If successfully authorized, the request is allowed to continue for further processing. If not authorized, the request is immediately terminated with a 403 Access denied error.

The filter requires certain inputs to call the Permissions API. These are listed below:

Inputs Description

Inputs	Description
`action`	The action being performed. Eg `STREAM_BROWSE`
`resourceType`	The type of the resource on which permission check is required. Eg `STREAM_CONFIG`
`uriTemplate`	A structure of URI containing `{id}`. It is used to extract the resource ID. Eg `/api/stream_configs/{id}/browse`

action

The action being performed. Eg STREAM_BROWSE

resourceType

The type of the resource on which permission check is required. Eg STREAM_CONFIG

uriTemplate

A structure of URI containing {id}. It is used to extract the resource ID. Eg /api/stream_configs/{id}/browse

Services Request Flow

This section describes how requests to various backend services flow through the gateway.

Platform Manager

Requests matching /api are forwarded to Platform Manager. The request is authenticated via Spring Security. If the request contains the header realm, it is authenticated against the SSO Authorization Server else the Local Authorization server.

The JWT token must contain the claims email, given_name, family_name, tenant_name, tenant_short_name when issued by the Global Authorization server.

The JWT token must contain the claims email, given_name and family_name when issued by the SSO Authorization server.

Once the request is successfully authenticated, it goes through the AddUserHeaders filter and the relevant claims are mapped to HTTP headers. Then the request is forwarded to Platform Manager service.

Topic Browse

Requests matching /api/stream_configs/*/browse are forwarded to Topic Browse service. The request is authenticated via Spring Security. If the request contains the header realm, it is authenticated against the SSO Authorization Server else the Local Authorization server.

The same rules apply for JWT token claims as mentioned in Platform Manager section above. Once the request is successfully authenticated, it goes through the AddUserHeaders filter and the relevant claims are mapped to HTTP headers.

Then the request goes through PermissionsApi filter where the request is checked for authorization. If rejected, the request is immediately terminated with 403 Access denied.

If authorized, the request continues through TopicBrowseConfig filter where the request is enriched with configuration obtained from Platform Manager.

Finally, the request body is added by the built-in filter with required fields before finally proxying the request to Topic browse service.

Metrics Exposer

Requests matching /api/metrics/query are forwarded to Metrics Exposer service. The request is authenticated via Spring Security. If the request contains the header realm, it is authenticated against the SSO Authorization Server else the Local Authorization server.

Then the request goes through MetricsExposerConfig filter where the request is enriched with configuration obtained from Platform Manager.

Finally, the request body is added by the built-in filter with required fields before finally proxying the request to Metrics Exposer service.

Docker environment variables

Name Possible Values Description Required

Name	Possible Values	Description	Required
GATEWAY_ENDPOINTS_BILLING_ENABLED	true/false default: true	If billing component is enabled	No
GATEWAY_ENDPOINTS_BILLING_URL	URL	URL of billing component	Yes if(`GATEWAY_ENDPOINTS_BILLING_ENABLED=true`)
GATEWAY_ENDPOINTS_BILLING_PATH	string default: `/api/billing/**`	Path of the billing	No
GATEWAY_ENDPOINTS_KEYCLOAK_ENABLED	true/false default: true	If keycloak is enabled	No
GATEWAY_ENDPOINTS_KEYCLOAK_URL	URL	URL of keycloak	Yes if(`GATEWAY_ENDPOINTS_KEYCLOAK_ENABLED=true`)
GATEWAY_ENDPOINTS_KEYCLOAK_PATH	string default: `/auth/**`	Path of keycloak	No
GATEWAY_ENDPOINTS_ORGANIZATION_MANAGER_ENABLED	true/false default: false	If Organization Manager is enabled	No
GATEWAY_ENDPOINTS_ORGANIZATION_MANAGER_URL	URL	URL of the Organization Manager.	Yes if(`GATEWAY_ENDPOINTS_ORGANIZATION_MANAGER_ENABLED=true`)
GATEWAY_ENDPOINTS_ORGANIZATION_MANAGER_PATH	string default: `/api/organizations/**`	Path of the Organization manager	No
GATEWAY_ENDPOINTS_PLATFORM_MANAGER_ENABLED	true/false default: true	If the Platform Manager is enabled	No
GATEWAY_ENDPOINTS_PLATFORM_MANAGER_URL	URL	URL of the Platform Manager	Yes if(`GATEWAY_ENDPOINTS_PLATFORM_MANAGER_ENABLED=true`)
GATEWAY_ENDPOINTS_PLATFORM_MANAGER_PATH	string default: `/api/**`	URL of the Platform Manager	No
GATEWAY_ENDPOINTS_PLATFORM_UI_ENABLED	true/false default: true	If the Self Service UI is enabled	No
GATEWAY_ENDPOINTS_PLATFORM_UI_URL	URL	URL of the Self Service UI	Yes if(`GATEWAY_ENDPOINTS_PLATFORM_UI_ENABLED=true`)
GATEWAY_ENDPOINTS_PLATFORM_UI_PATH	URL default: `/**`	Path of the Self Service UI	No
GATEWAY_ENDPOINTS_TOPIC_BROWSE_ENABLED	true/false default: true	If the Topic browse is enabled	No
GATEWAY_ENDPOINTS_TOPIC_BROWSE_URL	URL	URL of the Topic browse	Yes if(`GATEWAY_ENDPOINTS_TOPICBROWSE_ENABLED=true`)
GATEWAY_ENDPOINTS_TOPIC_BROWSE_PATH	string default: `/api/stream_configs/*/browse`	Path of the Topic browse	No
GATEWAY_ENDPOINTS_STREAM_BROWSE_LEGACY_ENABLED	true/false	If the Stream Browse Legacy is enabled	No
GATEWAY_ENDPOINTS_STREAM_BROWSE_LEGACY_URL	URL	URL of the Stream Browse Legacy	Yes if(`GATEWAY_ENDPOINTS_STREAMBROWSELEGACY_ENABLED=true`)
GATEWAY_ENDPOINTS_STREAM_BROWSE_LEGACY_PATH	string default: `/api/browse/**`	Path of the Stream Browse Legacy	No
GATEWAY_ENDPOINTS_METRICS_EXPOSER_ENABLED	true/false default: true	If the Metrics Exposer is enabled	No
GATEWAY_ENDPOINTS_METRICS_EXPOSER_URL	URL	URL of the Metrics Exposer	Yes if(`GATEWAY_ENDPOINTS_METRICSEXPOSER_ENABLED=true`)
GATEWAY_ENDPOINTS_METRICS_EXPOSER_PATH	string default: `/api/metrics/**`	Path of the Metrics Exposer	No
PERMISSIONS_API_URL	URL	Endpoint to validate permissions	Yes if(`GATEWAY_ENDPOINTS_TOPICBROWSE_ENABLED=true`)
TOPICBROWSE-CONFIG-API_URL	URL	Endpoint to retrieve topic browse configuration	Yes if(`GATEWAY_ENDPOINTS_TOPICBROWSE_ENABLED=true`)
METRICSEXPOSER-CONFIG-API_URL	URL	Endpoint to retrieve Metrics Exposer configuration	Yes if(`GATEWAY_ENDPOINTS_METRICSEXPOSER_ENABLED=true`)
SSO_KEYCLOAK_ADVERTISED_BASE_URL	URL	URL of Keycloak to be accessed outside the cluster	No
SSO_KEYCLOAK_INTERNAL_BASE_URL	URL	URL of Keycloak to be accessed within the cluster	No
SSO_KEYCLOAK_USE_INSECURE_TRUST_MANAGER	true/false default: false	Allow accessing Keycloak without TLS chain validation	No
LOCAL_AUTH_ISSUER_URL_FOR_VALIDATION	URL	Endpoint of the Local Authentication Server Issuer URI (e.g. `https://idp.example.com` ). This endpoint is never called. It is used to compare the `iss` claim of the JWT token.	Yes
LOCAL_AUTH_JWK_SET_URI	URL	Endpoint of the Local Authentication Server JWK Set URI (e.g. `https://idp.example.com/.well-known/jwks.json` ). Used for signing up new tenants.	Yes
LOCAL_AUTH_USE_INSECURE_TRUST_MANAGER	true/false default: true	Allow accessing the Local AuthenticationServer (Auth0 or Keycloak) without TLS chain validation	No
SPRING_APPLICATION_NAME	string default: `gateway`	No	Name of the application
LOGGING_FILTER_ENABLED	true/false default: true	If Logging Filtering is enabled	No
MANAGEMENT_SERVER_PORT	true/false default: 8086	Port on which to access Management API	No
MANAGEMENT_ENDPOINT_HEALTH_PROBES_ENABLED	true/false default: true	If the Health probes on the Actuator should be enabled	No
MANAGEMENT_ENDPOINTS_WEB_EXPOSURE_INCLUDE	string	Actuator Endpoint IDs that should be included or ’*’ for all	No
MANAGEMENT_TRACING_ENABLED	true/false default: true	Tracing is enabled	No
MANAGEMENT_TRACING_SAMPLING_PROBABILITY	number	Probability in the range from 0.0 to 1.0 that a trace will be sampled	No

GATEWAY_ENDPOINTS_BILLING_ENABLED

true/false default: true

If billing component is enabled

GATEWAY_ENDPOINTS_BILLING_URL

URL

URL of billing component

Yes if(GATEWAY_ENDPOINTS_BILLING_ENABLED=true)

GATEWAY_ENDPOINTS_BILLING_PATH

string default: /api/billing/**

Path of the billing

GATEWAY_ENDPOINTS_KEYCLOAK_ENABLED

true/false default: true

If keycloak is enabled

GATEWAY_ENDPOINTS_KEYCLOAK_URL

URL

URL of keycloak

Yes if(GATEWAY_ENDPOINTS_KEYCLOAK_ENABLED=true)

GATEWAY_ENDPOINTS_KEYCLOAK_PATH

string default: /auth/**

Path of keycloak

GATEWAY_ENDPOINTS_ORGANIZATION_MANAGER_ENABLED

true/false default: false

If Organization Manager is enabled

GATEWAY_ENDPOINTS_ORGANIZATION_MANAGER_URL

URL

URL of the Organization Manager.

Yes if(GATEWAY_ENDPOINTS_ORGANIZATION_MANAGER_ENABLED=true)

GATEWAY_ENDPOINTS_ORGANIZATION_MANAGER_PATH

string default: /api/organizations/**

Path of the Organization manager

GATEWAY_ENDPOINTS_PLATFORM_MANAGER_ENABLED

true/false default: true

If the Platform Manager is enabled

GATEWAY_ENDPOINTS_PLATFORM_MANAGER_URL

URL

URL of the Platform Manager

Yes if(GATEWAY_ENDPOINTS_PLATFORM_MANAGER_ENABLED=true)

GATEWAY_ENDPOINTS_PLATFORM_MANAGER_PATH

string default: /api/**

URL of the Platform Manager

GATEWAY_ENDPOINTS_PLATFORM_UI_ENABLED

true/false default: true

If the Self Service UI is enabled

GATEWAY_ENDPOINTS_PLATFORM_UI_URL

URL

URL of the Self Service UI

Yes if(GATEWAY_ENDPOINTS_PLATFORM_UI_ENABLED=true)

GATEWAY_ENDPOINTS_PLATFORM_UI_PATH

URL default: /**

Path of the Self Service UI

GATEWAY_ENDPOINTS_TOPIC_BROWSE_ENABLED

true/false default: true

If the Topic browse is enabled

GATEWAY_ENDPOINTS_TOPIC_BROWSE_URL

URL

URL of the Topic browse

Yes if(GATEWAY_ENDPOINTS_TOPICBROWSE_ENABLED=true)

GATEWAY_ENDPOINTS_TOPIC_BROWSE_PATH

string default: /api/stream_configs/*/browse

Path of the Topic browse

GATEWAY_ENDPOINTS_STREAM_BROWSE_LEGACY_ENABLED

true/false

If the Stream Browse Legacy is enabled

GATEWAY_ENDPOINTS_STREAM_BROWSE_LEGACY_URL

URL

URL of the Stream Browse Legacy

Yes if(GATEWAY_ENDPOINTS_STREAMBROWSELEGACY_ENABLED=true)

GATEWAY_ENDPOINTS_STREAM_BROWSE_LEGACY_PATH

string default: /api/browse/**

Path of the Stream Browse Legacy

GATEWAY_ENDPOINTS_METRICS_EXPOSER_ENABLED

true/false default: true

If the Metrics Exposer is enabled

GATEWAY_ENDPOINTS_METRICS_EXPOSER_URL

URL

URL of the Metrics Exposer

Yes if(GATEWAY_ENDPOINTS_METRICSEXPOSER_ENABLED=true)

GATEWAY_ENDPOINTS_METRICS_EXPOSER_PATH

string default: /api/metrics/**

Path of the Metrics Exposer

PERMISSIONS_API_URL

URL

Endpoint to validate permissions

Yes if(GATEWAY_ENDPOINTS_TOPICBROWSE_ENABLED=true)

TOPICBROWSE-CONFIG-API_URL

URL

Endpoint to retrieve topic browse configuration

Yes if(GATEWAY_ENDPOINTS_TOPICBROWSE_ENABLED=true)

METRICSEXPOSER-CONFIG-API_URL

URL

Endpoint to retrieve Metrics Exposer configuration

Yes if(GATEWAY_ENDPOINTS_METRICSEXPOSER_ENABLED=true)

SSO_KEYCLOAK_ADVERTISED_BASE_URL

URL

URL of Keycloak to be accessed outside the cluster

SSO_KEYCLOAK_INTERNAL_BASE_URL

URL

URL of Keycloak to be accessed within the cluster

SSO_KEYCLOAK_USE_INSECURE_TRUST_MANAGER

true/false default: false

Allow accessing Keycloak without TLS chain validation

LOCAL_AUTH_ISSUER_URL_FOR_VALIDATION

URL

Endpoint of the Local Authentication Server Issuer URI (e.g. https://idp.example.com ). This endpoint is never called. It is used to compare the iss claim of the JWT token.

Yes

LOCAL_AUTH_JWK_SET_URI

URL

Endpoint of the Local Authentication Server JWK Set URI (e.g. https://idp.example.com/.well-known/jwks.json ). Used for signing up new tenants.

Yes

LOCAL_AUTH_USE_INSECURE_TRUST_MANAGER

true/false default: true

Allow accessing the Local AuthenticationServer (Auth0 or Keycloak) without TLS chain validation

SPRING_APPLICATION_NAME

string default: gateway

Name of the application

LOGGING_FILTER_ENABLED

true/false default: true

If Logging Filtering is enabled

MANAGEMENT_SERVER_PORT

true/false default: 8086

Port on which to access Management API

MANAGEMENT_ENDPOINT_HEALTH_PROBES_ENABLED

true/false default: true

If the Health probes on the Actuator should be enabled

MANAGEMENT_ENDPOINTS_WEB_EXPOSURE_INCLUDE

string

Actuator Endpoint IDs that should be included or ’*’ for all

MANAGEMENT_TRACING_ENABLED

true/false default: true

Tracing is enabled

MANAGEMENT_TRACING_SAMPLING_PROBABILITY

number

Probability in the range from 0.0 to 1.0 that a trace will be sampled