Auth

The differences between TSB and TSE API

Tetrate Service Express (TSE) utilizes many of the same components as the Tetrate Service Bridge(TSB) product but has the several distinctions. Go to Comparing TSE and TSB for more details.

Authentication and authorization configs at gateways, security group level

Authentication

Field	Description	Validation 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

Field	Description	Validation 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: The Authorization header using the Bearer schema, e.g. Authorization: Bearer <token>. (see Authorization Request Header Field) 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.

Field	Description	Validation 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.

Field	Description	Validation 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

Field	Description	Validation 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

Field	Description	Validation 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

Field	Description	Validation 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.

Field	Description	Validation Rule
rules	List of tetrateio.api.tsb.auth.v2.LocalAuthzRule	–

ClientTLSSettings

Configure TLS parameters for the client

Field	Description	Validation 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.

Field	Description	Validation 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

Field	Description	Validation 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

Field	Description	Validation 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)

Field	Description	Validation 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.

Field	Description	Validation 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.

Field	Description	Validation 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

Field	Description	Validation 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.

Field	Number	Description
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

Field	Number	Description
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

Field	Number	Description
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