Skip to main content
logoTetrate Service BridgeVersion: 1.9.x

Auth

Authentication and authorization configs at gateways, security group level

Authentication​

FieldDescriptionValidation Rule

jwt

tetrateio.api.tsb.auth.v2.Authentication.JWT oneof _authn
Authenticate an HTTP request from a JWT Token attached to it.

–

rules

tetrateio.api.tsb.auth.v2.Authentication.Rules oneof _authn
List of rules how to authenticate an HTTP request.

–

oidc

tetrateio.api.tsb.auth.v2.OIDCConfig
Authenticate an HTTP request using an external OIDC provider

–

JWT​

FieldDescriptionValidation Rule

issuer

string
REQUIRED
Identifies the issuer that issued the JWT. See issuer A JWT with different iss claim will be rejected.

Example: https://foobar.auth0.com Example: 1234567-compute@developer.gserviceaccount.com

string = {
  min_len: 1
}

audiences

List of string
The list of JWT audiences. that are allowed to access. A JWT containing any of these audiences will be accepted.

The service name will be accepted if audiences is empty.

–

jwksUri

string oneof _keys
URL of the provider's public key set to validate signature of the JWT. See OpenID Discovery.

Optional if the key set document can either (a) be retrieved from OpenID Discovery of the issuer or (b) inferred from the email domain of the issuer (e.g. a Google service account).

Example: https://www.googleapis.com/oauth2/v1/certs

Note: Only one of jwks_uri and jwks should be used. jwks_uri will be ignored if it does.

–

jwks

string oneof _keys
JSON Web Key Set of public keys to validate signature of the JWT. See https://auth0.com/docs/jwks.

Note: Only one of jwks_uri and jwks should be used. jwks_uri will be ignored if it does.

–

outputPayloadToHeader

string
This field specifies the header name to output a successfully verified JWT payload to the backend. The forwarded data is base64_encoded(jwt_payload_in_JSON). If it is not specified, the payload will not be emitted.

–

outputClaimToHeaders

List of tetrateio.api.tsb.auth.v2.Authentication.JWT.ClaimToHeader
This field specifies a list of operations to copy the claim to HTTP headers on a successfully verified token. This differs from the output_payload_to_header by allowing outputting individual claims instead of the whole payload. Only claims of type string, boolean, and integer are supported. Array type claims are not supported at this time. The header specified in each operation in the list must be unique. Nested claims of type string/int/bool is supported as well.

  outputClaimToHeaders:
  - header: x-my-company-jwt-group
    claim: my-group
  - header: x-test-environment-flag
    claim: test-flag
  - header: x-jwt-claim-group
    claim: nested.key.group

[Experimental] This feature is a experimental feature.

–

fromHeaders

List of tetrateio.api.tsb.auth.v2.Authentication.JWT.JWTHeader
This field specifies the locations to extract JWT token. If no explicit location is specified the following default locations are tried in order:

  1. The Authorization header using the Bearer schema, e.g. Authorization: Bearer <token>. (see Authorization Request Header Field)

  2. The access_token query parameter (see URI Query Parameter)

List of header locations from which JWT is expected. For example, below is the location spec if JWT is expected to be found in x-jwt-assertion header, and have Bearer prefix:

  fromHeaders:
  - name: x-jwt-assertion
    prefix: "Bearer "

Note: Multiple tokens present on the same request are not supported. The behaviour of authorization policies when there is more than one user identity is undefined

–

ClaimToHeader​

This message specifies the detail for copying claim to header.

FieldDescriptionValidation Rule

header

string
REQUIRED
The name of the header to be created. The header will be overridden if it already exists in the request.

string = {
  min_len: 1
}

claim

string
REQUIRED
The name of the claim to be copied from. Only claim of type string/int/bool is supported. The header will not be there if the claim does not exist or the type of the claim is not supported.

string = {
  min_len: 1
}

JWTHeader​

This message specifies a header location to extract JWT token.

FieldDescriptionValidation Rule

name

string
REQUIRED
The HTTP header name.

–

prefix

string
The prefix that should be stripped before decoding the token. For example, for Authorization: Bearer \<token\>, prefix=Bearer with a space at the end. If the header doesn't have this exact prefix, it is considered invalid.

–

Rules​

FieldDescriptionValidation Rule

jwt

List of tetrateio.api.tsb.auth.v2.Authentication.JWT
List of rules how to authenticate an HTTP request from a JWT Token attached to it. A JWT Token, if present in the HTTP request, must satisfy one of the rules defined here. The order in which rules are being checked at runtime might differ from the order in which they are defined here. If the JWT Token doesn't satisfy any of the rules, the request will be rejected. If the JWT Token does satisfy one of the rules, the identity of the request will be extracted from the JWT Token.

Notice that an HTTP request without a JWT Token attached to it will NOT be rejected based on the rules defined here. Remember to define HTTP request authorization settings to achieve that.

–

Authorization​

Configuration for authorizing a HTTP request

FieldDescriptionValidation Rule

external

tetrateio.api.tsb.auth.v2.Authorization.ExternalAuthzBackend oneof _authz

–

local

tetrateio.api.tsb.auth.v2.Authorization.LocalAuthz oneof _authz

–

ExternalAuthzBackend​

Use an authorization server running at the specified URI. Support both HTTP and gRPC server. It is recommended to enable TLS validation (SIMPLE or MUTUAL) to secure traffic between workload and external authorization server If you use gRPC, do not set includeRequestHeaders

FieldDescriptionValidation Rule

uri

string

–

includeRequestHeaders

List of string

–

tls

tetrateio.api.tsb.auth.v2.ClientTLSSettings

–

LocalAuthz​

Authorize the request in Envoy based on the JWT claims.

FieldDescriptionValidation Rule

rules

List of tetrateio.api.tsb.auth.v2.LocalAuthzRule

–

ClientTLSSettings​

Configure TLS parameters for the client

FieldDescriptionValidation Rule

mode

tetrateio.api.tsb.auth.v2.TLSMode
Set this to DISABLED to disable TLS (not recommended from the security perspective), SIMPLE for one-way TLS and MUTUAL for mutual TLS (where client is required to present its certificate as well)

–

files

tetrateio.api.tsb.auth.v2.TLSFileSource oneof _tls_key_source
TLS key source from files.

–

secretName

string oneof _tls_key_source
TLS key source from a Kubernetes Secret. This is applicable for gateway workloads.

–

subjectAltNames

List of string
Subject alternative names is the list of names that are accepted as service name as part of TLS handshake

–

LocalAuthzRule​

LocalAuthzRule

Bindings define the subjects that can access the resource a policy is attached to, and the conditions that need to be met for that access to be granted. A policy can have multiple bindings to configure different access controls for specific subjects.

FieldDescriptionValidation Rule

name

string
REQUIRED
A friendly name to identify the binding.

string = {
  min_len: 1
}

from

List of tetrateio.api.tsb.auth.v2.Subject
Subjects configure the actors (end users, other services) that are allowed to access the target resource.

–

to

List of tetrateio.api.tsb.auth.v2.LocalAuthzRule.HttpOperation
A set of HTTP rules that need to be satisfied by the HTTP requests to get access to the target resource.

–

HttpOperation​

FieldDescriptionValidation Rule

paths

List of string
The request path where the request is made against. E.g. ["/accounts"].

repeated = {
  items: {string:{min_len:1}}
}

methods

List of string
The HTTP methods that are allowed by this rule. E.g. ["GET", "HEAD"].

repeated = {
  items: {string:{in:[GET,HEAD,POST,PUT,PATCH,DELETE,OPTIONS]}}
}

OIDCConfig​

Configure OIDC authentication for a given hostname

FieldDescriptionValidation Rule

grantType

tetrateio.api.tsb.auth.v2.OIDCGrantType
Configure the authorization grant type to be used

enum = {
  defined_only: true
}

clientId

string
REQUIRED
The client_id to be used in the authorize calls. This value will be URL encoded when sent to the OAuth server.

string = {
  min_len: 1
}

clientTokenSecret

string
REQUIRED
The name of the Kubernetes secret containing the client secret.

Kubernetes generic opaque secret should contain istio_generic_secret key with base64 encoded client_secret as value.

For example​

apiVersion: v1 metadata: name: bar namespace: foo data: istio_generic_secret: e2Jhc2U2NF9lbmNvZGVkX3Rva2VuX3NlY3JldH0= kind: Secret type: Opaque

The secret must be present in the same namespace as the gateway or sidecar deployment for which the configuration is being applied for. The (gateway/ sidecar) deployment must also have RBAC permissions to view secrets in the current namespace. For gateways this is already configured, while for sidecar the permission should be added if not already present.

The secret token stored will be URL encoded when sent to the OAuth server.

string = {
  min_len: 1
}

redirectUri

string
REQUIRED
The redirect URI passed to the authorization endpoint

It can also be formulated from request parameters For example: %REQ(x-forwarded-proto)%://%REQ(:authority)%/callback

This URI should not contain any query parameters.

string = {
  min_len: 1
}

provider

tetrateio.api.tsb.auth.v2.OIDCProviderConfig
REQUIRED
The OIDC Provider configuration. If only issuer is provided, the config will be treated as dynamic and will be fetched from the well known endpoint. If more fields are configured, the configuration will be treated as static and thus should be complete.

message = {
  required: true
}

authType

tetrateio.api.tsb.auth.v2.OIDCAuthType
Defines how client_id and client_secret are sent in OAuth client to OAuth server requests. RFC https://datatracker.ietf.org/doc/html/rfc6749#section-2.3.1

enum = {
  defined_only: true
}

authScopes

List of string
Optional list of OAuth scopes to be claimed in the authorization request. If not specified, defaults to user scope. OAuth RFC https://tools.ietf.org/html/rfc6749#section-3.3

–

redirectPathMatcher

string
Matching criteria used to determine whether a path appears to be the result of a redirect from the authorization server. The query and fragment string (if present) are removed in the URL path portion. For example, the path /data will match URI header /data#fragment?param=value.

If not provided, default is derived from redirect_uri path Only exact match is configurable

–

signoutPath

string
The path to sign a user out, clearing their credential cookies.

If not provided, default is /signout Only exact match is configurable

–

OIDCProviderConfig​

OIDCProviderConfig defines the OIDC Provider configuration.

It has two modes dynamic and static meaning if the configuration has to be derived from the Issuer's Well-Known endpoint dynamically or is statically configured. To use dynamic configuration only issuer field should be set. If any other field along with issuer is set then the configuration will be treated as static.

For AUTHORIZATION_CODE grant type, fields that are needed if configuration is static:

  1. Issuer

  2. AuthorizationEndpoint

  3. TokenEndpoint

  4. oneof (JwksURI or Jwks)

FieldDescriptionValidation Rule

issuer

string
REQUIRED
The OIDC Provider's issuer identifier.

string = {
  uri_ref: true
}

authorizationEndpoint

string
The OIDC Provider's authorization endpoint. If not provided, it will be discovered from the provider's Well-Known Configuration Endpoint.

string = {
  uri_ref: true
}

tokenEndpoint

string
The OIDC Provider's token endpoint. If not provided, it will be discovered from the provider's Well-Known Configuration Endpoint.

string = {
  uri_ref: true
}

jwksUri

string oneof _jwks_setting
URI for the OIDC provider's JSON Web Key Sets. This can be found in the OIDC provider's configuration response. The JWKS are used for token verification.

string = {
  uri: true
}

jwks

string oneof _jwks_setting
JSON string with the OIDC provider's JSON Web Key Sets. In general the URI for the Key Set is the preferred method for configuring JWKS. This setting is provided in case the provider doesn't publish JWKS via a public URI.

string = {
  min_len: 1
}

Subject​

Subject

A subject designates an actor (user, service, etc) that attempts to access a target resource. Subjects can be modeled with JWT tokens, service accounts, and decorated with attributes such as HTTP request headers, JWT token claims, etc. The fields that define a subject will be matched to incoming requests, to fully qualify where the request comes from, and to decide if the given request is allowed or not for the target resource. All the fields in a subject are evaluated as AND expressions.

FieldDescriptionValidation Rule

jwt

tetrateio.api.tsb.auth.v2.Subject.JWTClaims
JWT configuration to identity the subject.

–

JWTClaims​

JWT based subject

JWT based subjects qualify a subject by matching against a JWT token present in the request. By default the token is expected to be present in the 'Authorization' HTTP header, with the 'Bearer" prefix.

FieldDescriptionValidation Rule

iss

string

–

sub

string

–

other

map<string, string>
A set of arbitrary claims that are required to qualify the subject. E.g. "iss": "*@foo.com".

map = {
  keys: {string:{min_len:1}}
}

TLSFileSource​

TLSFileSource is used to load the keys and certificates from files accessible to the workload

FieldDescriptionValidation Rule

clientCertificate

string
Certificate file to authenticate the client. This is mandatory for mutual TLS and must not be specified for simple (one-way) TLS

–

privateKey

string
Private key file associated with the client certificate. This is mandatory for mutual TLS and must not be specified for simple TLS

–

caCertificates

string
File containing CA certificates to verify the certificates presented by the server. This is mandatory for both simple and mutual TLS. Here are some common paths for the system CA bundle on Linux and can be specified here if the server certificate is signed by a well known authority, already part of the system CA bundle on the host - /etc/ssl/certs/ca-certificates.crt (Debian/Ubuntu/Gentoo etc.) /etc/pki/ca-trust/extracted/pem/tls-ca-bundle.pem (CentOS/RHEL 7) /etc/pki/tls/certs/ca-bundle.crt (Fedora/RHEL 6)

–

OIDCAuthType​

Configures how client_id and client_secret are sent in OAuth client to OAuth server requests.

FieldNumberDescription

DEFAULT_AUTH_TYPE

0

If no authentication type is specified, the default authentication type will be used. Currently, the default authentication type is set to BASIC_AUTH because it is widely supported by the majority of OIDC providers

URL_ENCODED_BODY

1

The client_id and client_secret will be sent in the URL encoded request body. This type should only be used when Auth server does not support Basic authentication.

BASIC_AUTH

2

The client_id and client_secret will be sent using HTTP Basic authentication scheme.

OIDCGrantType​

Configures authentication flow to be used

FieldNumberDescription

DEFAULT_GRANT_TYPE

0

If no grant type is explicitly specified, the default grant type will be used. The specific behavior of the default grant type may vary based on the type of workload to which the authentication settings are applied. Currently, only AUTHORIZATION_CODE is available, so this will be in effect in the future when additional grant types are introduced.

AUTHORIZATION_CODE

1

Use authorization code flow

TLSMode​

Describes how authentication is performed as part of establishing TLS connection

FieldNumberDescription

DISABLED

0

TLS is not used and communication is in plaintext.

SIMPLE

1

Only the server is authenticated.

MUTUAL

2

Both the peers in the communication must present their certificate for TLS authentication