Skip to main content
logoTetrate Service BridgeVersion: 1.8.x

Security Setting

SecuritySetting allows configuring security related properties such as TLS authentication and access control for traffic arriving at a proxy workload in a security group.

Security settings can be propagated along any defined security settings in the configuration hierarchy. How security settings are propagated can be configured by specifying a PropagationStrategy.

The following example creates a security group for the proxy workloads in ns1, ns2 and ns3 namespaces owned by its parent workspace w1 under tenant mycompany and defines a security setting that only allows mutual TLS authenticated traffic from other proxy workloads in the same group.

apiVersion: security.tsb.tetrate.io/v2
kind: Group
metadata:
name: t1
workspace: w1
tenant: mycompany
organization: myorg
spec:
namespaceSelector:
names:
- "*/ns1"
- "*/ns2"
- "*/ns3"
configMode: BRIDGED

And the associated security settings for all proxy workloads in the group

apiVersion: security.tsb.tetrate.io/v2
kind: SecuritySetting
metadata:
name: defaults
group: t1
workspace: w1
tenant: mycompany
organization: myorg
spec:
authenticationSettings:
trafficMode: REQUIRED
authorization:
mode: GROUP

The following example customizes the allowedSources to allow traffic from the namespaces within the group as well as the catalog-sa service account from ns4 namespace.

apiVersion: security.tsb.tetrate.io/v2
kind: SecuritySetting
metadata:
name: custom
group: t1
workspace: w1
tenant: mycompany
organization: myorg
spec:
authenticationSettings:
trafficMode: REQUIRED
http:
rules:
jwt:
- issuer: "https://auth.tetrate.io"
jwksUri: "https://oauth2.auth.tetrate.io/certs"
- issuer: "https://auth.tetrate.internal"
jwksUri: "https://oauth2.auth.tetrate.internal/certs"
authorization:
mode: CUSTOM
serviceAccounts:
- "ns1/*"
- "ns2/*"
- "ns3/*"
- "ns4/catalog-sa"
http:
external:
uri: "https://policy.auth.tetrate.io"
includeRequestHeaders:
- authorization

The following example rejects all traffic arriving at workloads from namespaces that belong to security group t1.

apiVersion: security.tsb.tetrate.io/v2
kind: SecuritySetting
metadata:
name: defaults
group: t1
workspace: w1
tenant: mycompany
organization: myorg
spec:
authenticationSettings:
trafficMode: REQUIRED
authorization:
mode: RULES
rules:
denyAll: true

The following example accepts all traffic arriving at workloads from namespaces that belong to security group t1. All authenticated requests are accepted because any workload is targeted to be allowed nor denied.

apiVersion: security.tsb.tetrate.io/v2
kind: SecuritySetting
metadata:
name: defaults
group: t1
workspace: w1
tenant: mycompany
organization: myorg
spec:
authenticationSettings:
trafficMode: REQUIRED
authorization:
mode: RULES

The following example accepts all traffic arriving at workloads in namespaces that belong to security group t1 traffic, except from workloads belonging to workspace w2.

apiVersion: security.tsb.tetrate.io/v2
kind: SecuritySetting
metadata:
name: defaults
group: t1
workspace: w1
tenant: mycompany
organization: myorg
spec:
authenticationSettings:
trafficMode: REQUIRED
authorization:
mode: RULES
rules:
deny:
- from:
fqn: organizations/myorg/tenants/mycompany/workspaces/w2
to:
fqn: organizations/myorg/tenants/mycompany/workspaces/w1/securitygroups/t1

The following example accepts traffic arriving at workloads in namespaces that belong to security group t1 traffic, from workloads belonging to workspace w2. Hence, only authenticated request to workloads in security group t1 coming from workloads in workspace w2 are accepted. All other request will be rejected.

apiVersion: security.tsb.tetrate.io/v2
kind: SecuritySetting
metadata:
name: defaults
group: t1
workspace: w1
tenant: mycompany
organization: myorg
spec:
authenticationSettings:
trafficMode: REQUIRED
authorization:
mode: RULES
rules:
allow:
- from:
fqn: organizations/myorg/tenants/mycompany/workspaces/w2
to:
fqn: organizations/myorg/tenants/mycompany/workspaces/w1/securitygroups/t1

The following example uses a combination of allows and denies to show how rules are evaluated. Let's say we have a workspace w3 which contains 3 security groups, sg31, sg32, and sg33. Besides we also have workspace w1 and w2. Security group sg31 contains workloads that handle sensitive data, and we want to only accept requests arriving from the same workspace w3 and explicitly reject requests coming from sg32. Hence, only authenticated request to workloads in security group sg31 coming from workloads in workspace w3 and security group sg31 or sg33 will be accepted. Requests coming from sg32 will be rejected. Moreover, a request coming from any workload that belongs to another workspace (w1, or w2), or security group that belong to another workspace, will also be reject by default because it is not in the list of allowed resource FQNs.

apiVersion: security.tsb.tetrate.io/v2
kind: SecuritySetting
metadata:
name: defaults
group: sg31
workspace: w3
tenant: mycompany
organization: myorg
spec:
authenticationSettings:
trafficMode: REQUIRED
authorization:
mode: RULES
rules:
allow:
- from:
fqn: organizations/myorg/tenants/mycompany/workspaces/w3
to:
fqn: organizations/myorg/tenants/mycompany/workspaces/w3/securitygroups/sg31
deny:
- from:
fqn: organizations/myorg/tenants/mycompany/workspaces/w3/securitygroups/sg32
to:
fqn: organizations/myorg/tenants/mycompany/workspaces/w3/securitygroups/sg31

The following example customizes the WAFSettings to enforce Web Application Firewall rules on sidecars in namespaces reside in SecurityGroup.

Please DO NOT use it in production.

apiVersion: security.tsb.tetrate.io/v2
kind: SecuritySetting
metadata:
name: defaults
group: t1
workspace: w1
tenant: mycompany
organization: myorg
spec:
waf:
rules:
- SecRuleEngine ON
- Include @owasp_crs/*.conf

The following example customizes the Extensions to enable the execution of the WasmExtensions list specified, detailing custom properties for the execution of each extension.

apiVersion: security.tsb.tetrate.io/v2
kind: SecuritySetting
metadata:
name: defaults
group: t1
workspace: w1
tenant: mycompany
organization: myorg
spec:
extension:
- fqn: hello-world # fqn of imported extensions in TSB
config:
foo: bar

AuthenticationSettings

AuthenticationSettings represents configuration related to authenticating traffic within the mesh and end-user credentials if present. It is HIGHLY RECOMMENDED to enable mutual TLS when end-user credentials are present. Sending credentials like JWT over plaintext is a security risk.

FieldDescriptionValidation Rule

trafficMode

tetrateio.api.tsb.security.v2.SecuritySetting.AuthenticationMode
Traffic authentication mode is used to specify if mTLS or plaintext traffic is accepted

http

tetrateio.api.tsb.auth.v2.Authentication
HTTP request authentication is used to configure authentication of origin/end-user credentials like JSON Web Token (JWT). It is highly recommended to set traffic authentication mode to REQUIRED so that it is transported only over mutual TLS

AuthorizationRules

AuthorizationRules specifies which target workloads are allowed or denied. When the mode is RULES, by default, if no authorization rules are provided all requests will be accepted. Currently, when a list of allow or deny rules are provided, a workload can only be targeted by providing the workspace or security group resource the workload belongs to. When different target workloads are allowed, denied or all workload are denied, to evaluate if a request is accepted or rejected, denies are evaluated first, and finally allows. Accepting or denying a request from a workload is determined by:

  • If deny_all is true, deny the request

  • If deny is defined and there are any denied target workload, deny the request.

  • If there are no allowed target workload, allow the request.

  • If allow is defined and there are any allowed target workload, allow the request.

  • Deny the request.

FieldDescriptionValidation Rule

allow

List of tetrateio.api.tsb.security.v2.Rule
Allow specifies a list of rules. If a request matches at least one rule, the request is accepted. If no allow rules are provided, all requests are allowed. Each rule must be unique, no duplicates are allowed. A rule that is fully contained by another rule is not allowed. For instance, defining a rule from workspace w1 to w2 and another rule from security group sg1 (which belongs to workspace w1) to sg2 (which belongs to workspace w2) is not allowed. It is not allowed, because from security group sg1 to sg2 rule is already allowed by the rule from workspace w1 to ws2.

denyAll

bool
Deny all specifies whether all requests should be rejected. If it is true all requests will be rejected. If it is false the list of deny rules will be evaluated.

deny

List of tetrateio.api.tsb.security.v2.Rule
Deny specifies a list of rules. If a request matches at least one rule, the request is rejected. If deny rules are provided, the match will never occur, so no request can be rejected. Each rule must be unique, no duplicates are allowed. A rule that is fully contained by another rule is not allowed. For instance, defining a rule from workspace w1 to w2 and another rule from security group sg1 (which belongs to workspace w1) to sg2 (which belongs to workspace w2) is not allowed. It is not allowed, because from security group sg1 to sg2 rule is already denied by the rule from workspace w1 to w2.

AuthorizationSettings

AuthorizationSettings define the set of service accounts in one or more namespaces allowed to access a workload (and hence its sidecar) in the mesh.

FieldDescriptionValidation Rule

mode

tetrateio.api.tsb.security.v2.AuthorizationSettings.Mode
A short cut for specifying the set of allowed callers.

serviceAccounts

List of string
When the mode is CUSTOM, serviceAccounts specify the allowed set of service accounts (and the workloads using them). Must be in the \<namespace\>/\<service-account-name\> format.

  • ./* indicates all service accounts in the namespace where the sidecar resides.

  • ns1/* indicates all service accounts in the ns1 namespace.

  • ns1/svc1-sa indicates svc1-sa service account in ns1 namespace.

Namespace should be a valid kubernetes namespace, which follows RFC 1123 Label Names rules. Service account should be a valid kubernetes service account, which follows DNS Subdomain Names rules.

repeated = {
  items: {string:{pattern:^\\./\\*$|^[^.*]+/[*]{1}$|^[^.*]+/[^*]+$}}
}

http

tetrateio.api.tsb.auth.v2.Authorization
This is for configuring HTTP request authorization. Currently, we only support authorizing through an external backend/policy engine like OPA. Inline authorization rules for JWT are not yet supported for sidecars.

rules

tetrateio.api.tsb.security.v2.AuthorizationRules
When the mode is RULES, you can allow or deny workload-to-workload communication by specifying in the rules field which target workloads are allowed or denied to communicate with other target workloads. When the mode is RULES, if no authorization rules are provided all requests will be accepted.

identityMatch

tetrateio.api.tsb.security.v2.IdentityMatch
identity_match specifies the strategy for client identity verification to be employed during the evaluation of authorization (authz) rules within the service. This field determines how the identity of a client is verified and utilized to make authz decisions, offering different levels of security and flexibility based on the chosen mode.

Possible values for identity_match are:

  • SOURCE_IDENTITY: Enforces authz decisions based on the service identity propagated from the client. This mode ensures that authz is evaluated strictly based on the explicit identity of the requesting service, suitable for environments requiring high security and strict identity verification.
  • PEER_CERTIFICATE: Utilizes the SPIFFE ID from mTLS certificates for authz decisions. This mode is aligned with certificate-based identity validation, providing a secure, cryptographic method of asserting service identities.
  • PERMISSIVE: Allows a flexible approach by accepting either SOURCE_IDENTITY or PEER_CERTIFICATE for authz evaluation. This mode is designed for transitional environments or for easing upgrades, offering a broader compatibility with different identity verification methods.

If identity_match is not explicitly specified, the system defaults to the PERMISSIVE mode, allowing for a more inclusive evaluation of authz rules that accommodates various identity verification strategies.

The use of this field is dependent upon the enableHttpMeshInternalIdentityPropagation feature being enabled in the Control plane's configuration resource (CR). When this feature is active, it allows for the propagation and recognition of HTTP mesh internal identities, enabling the specified identity_match mode to take effect. If the feature is disabled in the Control Plane CR, the system reverts to using PEER_CERTIFICATE mode for identity verification, relying solely on mTLS certificate identities for authz rule evaluation.

This configuration offers flexibility in adapting the identity verification strategy to the specific security requirements and operational contexts of your environment, ensuring that authz rules are applied effectively and securely based on the desired identity verification method.

Rule

Rule matches request from a targeted resource (and the workloads that belong to the resource), to another targeted resource (and the workloads that belong to the resource). A match occurs when from and to matches the request. Only resources of type Tenant, Workspace, or Security Group can be targeted.

FieldDescriptionValidation Rule

from

tetrateio.api.tsb.security.v2.Rule.From
REQUIRED
From specifies the source of a request.

to

tetrateio.api.tsb.security.v2.Rule.To
REQUIRED
To specifies the destination of a request.

From

From includes the target resource (and the workloads that belong to the resource) which will be the source of a request.

FieldDescriptionValidation Rule

fqn

string
The target resource identified by FQN which will be the source of a request.

To

To includes the target resource (and the workloads that belong to the resource) which will be destination of a request.

FieldDescriptionValidation Rule

fqn

string
The target resource identified by FQN which will be the destination of a request.

SecuritySetting

A security setting applies configuration to a set of proxy workloads in a security group or a workspace. When applied to a security group, missing fields will inherit values from the workspace-wide setting if any.

FieldDescriptionValidation Rule

authentication

tetrateio.api.tsb.security.v2.SecuritySetting.AuthenticationMode
DEPRECATED: Specifies whether the proxy workloads should accept only mutual TLS authenticated traffic or allow legacy plaintext traffic as well. This field is deprecated in favor of authentication_settings and will be removed in the future release

authorization

tetrateio.api.tsb.security.v2.AuthorizationSettings
The set of service accounts in one or more namespaces allowed or denied to access a workload (and hence its sidecar) in the mesh. Authorization is affected by the security setting's defined propagation strategy. If STRICTER is used the most restrictive AuthorizationSettings mode along the configuration hierarchy will prevail.

AuthorizationSettings mode can only be changed from UNSET to DISABLED to CLUSTER to WORKSPACE to NAMESPACE to GROUP to RULES to CUSTOM. Restricting two CUSTOM AuthorizationSettings is a special case. A service account is considered stricter if it belongs to the same namespace and it has a concrete service account other than a wildcard. Hence, the only possibilities to restrict service accounts is from "ns/*" to "ns/svc1-sa". When two lists of service accounts are compared (a parent and a child list) only the service accounts from the child list that are stricter (following the previously mentioned rules) or equal to any of the parent defined service accounts will be used. If none of the children's service accounts is stricter or equal, then the parent defined list will be used. For instance, a parent defines "ns/*", "ns2/svc-sa", and "./*" service accounts, whereas a child defines "ns/svc1-sa", "ns3/svc-sa", and "./". The effective strictest list will be "ns/svc1-sa", and "./". "ns3/svc2-sa" is discarded because it will extend the set of service accounts allowed to access the workload/s, as parent's defined service accounts does not include "ns3/*" or "ns3/svc2-sa".

Restricting two rules AuthorizationSettings is also a special case. To consider a rules stricter, both allowed and denied rules list need to be considered as stricter. Allowed rules can only be refined by subsets of the initial rule. Hence, you cannot allow more workloads, only less. For instance, if an allow rule from workspace w1 to w2 has been specified higher up in the hierarchy, it can only be refined with the same resource or lineage resources lower down in the resource hierarchy. Which means, if w1 has a child security group sg1, only sg1 and w1 itself are considered as a stricter from resource target. In the same way, if w2 has a child security group sg2, only sg2 and w2 itself are considered as a stricter to resource target. On the other hand, any provided list of denied rules lower down in the hierarchy, will be considered always stricter, because all ancestor's denied rules are also taken into consideration. Basically, stricter rules AuthorizationSettings can only allow the same or less, and/or deny more workloads.

authenticationSettings

tetrateio.api.tsb.security.v2.AuthenticationSettings
Authentication settings is used to set workload-to-workload traffic and end-user/origin authentication configuration. Authentication settings is affected by the security setting's defined propagation strategy. If STRICTER is used the most restrictive AuthenticationSettings traffic mode along the configuration hierarchy will prevail. AuthenticationSettings traffic mode can only be changed from UNSET to OPTIONAL to REQUIRED. Authentication settings http will use replace propagation strategy.

waf

tetrateio.api.tsb.security.v2.WAFSettings
NOTICE: this feature is in alpha stage and under active development. it would encounter breaking changes in further release and should not be adopted in production WAF settings is used to set firewall rules.

propagationStrategy

tetrateio.api.tsb.types.v2.PropagationStrategy
Propagation strategy specifies how a security setting is propagated along the configuration hierarchy. The default strategy is REPLACE. The propagation strategy from security settings can only be changed from REPLACE to STRICTER along the settings in the configuration hierarchy. Any security setting propagation strategy changed from the default one, higher up in the configuration hierarchy, will prevail over any other defined security setting propagation strategy further down in the configuration hierarchy. For instance, if an organization's default security setting propagation strategy is changed to STRICTER, a restrictive propagation strategy will be used at tenant, workspace default security settings and group security settings. STRICTER propagation strategy will be used even though, tenant, workspace or group security settings specifies a REPLACE propagation strategy.

Security setting properties affected by the propagation strategy are:

  • Authorization

  • AuthenticationSettings

  • Extension

All the other properties will use the default REPLACE propagation strategy. How each property affected by the propagation strategy will be restricted is explained in more detail at each property.

extension

List of tetrateio.api.tsb.types.v2.WasmExtensionAttachment
Extensions specifies all the WasmExtensions assigned to this SecuritySettings with the specific configuration for each extension. This custom configuration will override the one configured globally to the extension. Each extension has a global configuration including enabling and priority that will condition the execution of the assigned extensions.

configGenerationMetadata

tetrateio.api.tsb.types.v2.ConfigGenerationMetadata
Metadata values that will be add into the Istio generated configurations. When using YAML APIs liketctl or gitops, put them into the metadata.labels or metadata.annotations instead. This field is only necessary when using gRPC APIs directly.

Mode

A short cut for defining the common authorization patterns

FieldNumberDescription

UNSET

0

Inherit from parent if possible. Otherwise treated as DISABLED.

NAMESPACE

1

The workload allows traffic from any other authenticated workload in its own namespace.

GROUP

2

The workload allows traffic from any other authenticated workload in the security group.

WORKSPACE

3

The workload allows traffic from any other authenticated workload in the workspace.

CLUSTER

4

The workload allows traffic from any other authenticated workload in the cluster.

DISABLED

5

Authorization is disabled.

CUSTOM

6

The workload allows traffic from service accounts defined explicitly.

RULES

7

The workload allows or denies traffic from any other authenticated workload that belongs to the specified rules.

IdentityMatch

IdentityMatch defines the strategy for utilizing service identities during the evaluation of authorization (authz) rules. It specifies how the identity of a service or workload is verified and used in the context of authz policies. The strictness of identity verification progresses in the following order: UNKNOWN < PERMISSIVE < PEER_CERTIFICATE < SOURCE_IDENTITY.

FieldNumberDescription

UNKNOWN

0

UNKNOWN represents the default state when identityMatch is not explicitly set. In practice, it behaves identically to the PERMISSIVE mode, allowing for a flexible approach to identity verification. This mode is typically used as a fallback or when the specific identity verification strategy is undecided.

PEER_CERTIFICATE

1

PEER_CERTIFICATE mode mandates the use of Mutual TLS (mTLS) certificates for identity verification. Specifically, it utilizes the SPIFFE(Secure Production Identity Framework For Everyone) IDs presented in peer certificates as the basis for authz decision-making. This mode aligns with Istio's Principal match authorization policies, offering a secure method of asserting service identities through cryptographic certificates. It is suitable for environments where strong, certificate-based identity validation is required.

PERMISSIVE

2

PERMISSIVE mode offers a flexible, transitional approach to identity verification, allowing the evaluation of authz rules based on either SOURCE_IDENTITY or PEER_CERTIFICATE identities. This mode is designed to facilitate gradual adoption of identity verification practices or to ease system upgrades. It is particularly useful in mixed environments where some services use SPIFFE IDs and others use a different form of service identity.

In ALLOW rules contexts, PERMISSIVE mode authorizes workloads if either their SOURCE_IDENTITY or PEER_CERTIFICATE matches the allowed principals. This approach broadens the range of clients that can be permitted, offering more flexibility during policy enforcement.

Conversely, in DENY rules contexts, PERMISSIVE mode restricts access to workloads if either their SOURCE_IDENTITY or PEER_CERTIFICATE matches the denied principals. This results in a more conservative set of clients being allowed, enhancing security by restricting access more broadly.

SOURCE_IDENTITY

3

SOURCE_IDENTITY mode strictly uses the service identity for authz rules evaluation. This identity is propagated from the originating client to the target service workload, which then assesses authz rules based on this received identity. The mode ensures that authz decisions are made based on the explicit identity of the requesting service, facilitating fine-grained access control and enhancing security by strictly adhering to the principle of least privilege.

This mode is optimal in environments that require strict enforcement of service identities, where the assurance of the caller's identity is paramount for secure access control.

AuthenticationMode

AuthenticationMode indicates whether to accept only Istio mutual TLS authenticated traffic or allow legacy plaintext traffic as well.

FieldNumberDescription

UNSET

0

Inherit from parent, if has one. Otherwise treated as OPTIONAL.

OPTIONAL

1

Accept both plaintext and mTLS authenticated connections.

REQUIRED

2

Accept only mutual TLS authenticated connections.