Skip to main content
Version: 1.2.x

OpenAPI Extensions

OpenAPIExtension

Metadata describing an extension to the OpenAPI spec.

FieldDescriptionValidation Rule

name

string
The name of the OpenAPI extension as it should appear in the OpenAPI document. For example: x-tsb-service

appliesTo

List of string
Parts of the OpenAPI spec where this custom extension is allowed. This is a list of names of the OpenAPI elements where the extension is supported. For example: ["info", "path"]

required

bool
Flag that configures if the extension is mandatory for the elements where it is supported.

OpenAPIExtensions

Available OpenAPI extensions to configure APi Gateway features in Service Bridge.

FieldDescriptionValidation Rule

x-tsb-service

string
Short name of the service in the TSB service registry where the path is exposed. if the extension is configured in the info section, all paths in the spec will be mapped to this service.

This service name will be used to generate all the routes for traffic coming to the associated paths.

OpenAPI extension name: x-tsb-service
Applies to: info, path
Required: Required unless x-tsb-redirect is defined for the target paths.

Example:

openapi: 3.0.0
info:
title: Sample API
version: 0.1.9
x-tsb-service: productpage.bookinfo
paths:
/users:
x-tsb-service: productpage.bookinfo
get:
summary: Returns a list of users.

x-tsb-redirect

tetrateio.api.tsb.gateway.v2.Redirect
Configures a redirection for the given path. If a redirection is configured for a given path, the x-tsb-service extension can be omitted.

OpenAPI extension name: x-tsb-redirect
Applies to: path
Required: false

Example:

paths:
/users:
x-tsb-redirect:
uri: /v2/users
get:
summary: Returns a list of users.

x-tsb-tls

tetrateio.api.tsb.gateway.v2.ServerTLSSettings
Configures the TLS settings for a given server. If omitted, the server will be configured to serve plain text connections.

OpenAPI extension name: x-tsb-redirect
Applies to: server
Required: false

Example:

openapi: 3.0.0
servers:
- url: http://api.example.com/v1
x-tsb-tls:
mode: SIMPLE
secretName: api-certs

x-tsb-cors

tetrateio.api.tsb.gateway.v2.CorsPolicy
Configures CORS policy settings for the given server. Note that Service Bridge does not currently support per-path CORS settings, so this applies at a server level.

OpenAPI extension name: x-tsb-cors
Applies to: server
Required: false

Example:

openapi: 3.0.0
servers:
- url: http://api.example.com/v1
x-tsb-cors:
allowOrigin:
- "*"

x-tsb-authentication

tetrateio.api.tsb.gateway.v2.Authentication
Configures Authentication rules for the given server. This extension must be configured if the Authorization is configured with rules based on JWT tokens.

OpenAPI extension name: x-tsb-authentication
Applies to: server
Required: Required if Authorization is based on JWT tokens.

Example:

openapi: 3.0.0
servers:
- url: http://api.example.com/v1
x-tsb-authentication:
jwt:
issuer: https://www.googleapis.com/oauth2/v1/certs
audience: bookinfo

x-tsb-external-authorization

tetrateio.api.tsb.gateway.v2.Authorization.ExternalAuthzBackend
Configures an external authorization server to handle all authorization requests for the configured server.

OpenAPI extension name: x-tsb-external-authorization
Applies to: server
Required: false

Example:

openapi: 3.0.0
servers:
- url: http://api.example.com/v1
x-tsb-external-authorization:
uri: http://authz-server.example.com
includeRequestHeaders:
- Authorization # forwards the header to the authorization service.

x-tsb-jwt-authorization

tetrateio.apo.tsb.application.v2.OpenAPIExtensions.JWTAuthz
Configures Authorization based on JWT tokens.

Note that if this is configured, the x-tsb-authentication extension must be configured for the servers so the tokens can be properly validated and trusted before reading their contents to enforce access control rules.

This can be applied at the server or path level. When applied at the server level, the authorization rules will be enforced for all paths in that server.

OpenAPI extension name: x-tsb-jwt-authorization
Applies to: server, path
Required: false

Example:

openapi: 3.0.0
servers:
- url: http://api.example.com/v1
x-tsb-authorization:
claims:
- iss: https://www.googleapis.com/oauth2/v1/certs
sub: expected-subject
other: # Additional claims to require int he token
group: engineering
paths:
/users:
x-tsb-authorization: # Override the server settings for the given path
claims:
- other:
group: admin

JWTAuthz

Configures authorization rules based on the JWT token in an incoming request.

FieldDescriptionValidation Rule

claims

List of tetrateio.api.tsb.gateway.v2.Subject.JWTClaims
List of claims to be required for incoming requests.