Navigation :

policy.proto

Package: `istio.authentication.v1alpha1`

Licensed under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License. You may obtain a copy of the License at

  http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Types:

StringMatch
MutualTls
Mode
Jwt
TriggerRule
PeerAuthenticationMethod
OriginAuthenticationMethod
Policy Top-Level Resource
MeshPolicy Top-Level Resource
TargetSelector
PortSelector

Enums:

- [PrincipalBinding](#principalbinding)

Source File: github.com/solo-io/supergloo/api/external/istio/authorization/v1alpha1/policy.proto

StringMatch

Describes how to match a given string. Match is case-sensitive.

"exact": string
"prefix": string
"suffix": string
"regex": string

Field	Type	Description
`exact`	`string`	exact string match.
`prefix`	`string`	prefix-based match.
`suffix`	`string`	suffix-based match.
`regex`	`string`	ECMAscript style regex-based match as defined by EDCA-262. Example: “^/pets/(.*?)?”

MutualTls

TLS authentication params.

"allowTls": bool
"mode": .istio.authentication.v1alpha1.MutualTls.Mode

Field	Type	Description	Default
`allowTls`	`bool`	WILL BE DEPRECATED, if set, will translates to `TLS_PERMISSIVE` mode. Set this flag to true to allow regular TLS (i.e without client x509 certificate). If request carries client certificate, identity will be extracted and used (set to peer identity). Otherwise, peer identity will be left unset. When the flag is false (default), request must have client certificate.
`mode`	.istio.authentication.v1alpha1.MutualTls.Mode	Defines the mode of mTLS authentication.

Mode

Defines the acceptable connection TLS mode.

Name	Description
`STRICT`	Client cert must be presented, connection is in TLS.
`PERMISSIVE`	Connection can be either plaintext or TLS, and client cert can be omitted.

Jwt

JSON Web Token (JWT) token format for authentication as defined by https://tools.ietf.org/html/rfc7519. See OAuth 2.0 and OIDC 1.0 for how this is used in the whole authentication flow.

For example:

A JWT for any requests:

issuer: https://example.com
audiences:
- bookstore_android.apps.googleusercontent.com
  bookstore_web.apps.googleusercontent.com
jwksUri: https://example.com/.well-known/jwks.json

A JWT for all requests except request at path /health_check and path with prefix /status/. This is useful to expose some paths for public access but keep others JWT validated.

issuer: https://example.com
jwks_uri: https://example.com/.well-known/jwks.json
trigger_rules:
- excluded_paths:
  - exact: /health_check
  - prefix: /status/

A JWT only for requests at path /admin. This is useful to only require JWT validation on a specific set of paths but keep others public accessible.

issuer: https://example.com
jwks_uri: https://example.com/.well-known/jwks.json
trigger_rules:
- included_paths:
  - prefix: /admin

A JWT only for requests at path of prefix /status/ but except the path of /status/version. This means for any request path with prefix /status/ except /status/version will require a valid JWT to proceed.

issuer: https://example.com
jwks_uri: https://example.com/.well-known/jwks.json
trigger_rules:
- excluded_paths:
  - exact: /status/version
  included_paths:
  - prefix: /status/

"issuer": string
"audiences": []string
"jwksUri": string
"jwtHeaders": []string
"jwtParams": []string
"triggerRules": []istio.authentication.v1alpha1.Jwt.TriggerRule

Field	Type	Description
`issuer`	`string`	Identifies the issuer that issued the JWT. See issuer Usually a URL or an email address. Example: https://securetoken.google.com Example: 1234567-compute@developer.gserviceaccount.com
`audiences`	`[]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. Example: `yaml audiences: - bookstore_android.apps.googleusercontent.com bookstore_web.apps.googleusercontent.com`
`jwksUri`	`string`	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
`jwtHeaders`	`[]string`	JWT is sent in a request header. `header` represents the header name. For example, if `header=x-goog-iap-jwt-assertion`, the header format will be x-goog-iap-jwt-assertion: .
`jwtParams`	`[]string`	JWT is sent in a query parameter. `query` represents the query parameter name. For example, `query=jwt_token`.
`triggerRules`	[]istio.authentication.v1alpha1.Jwt.TriggerRule	List of trigger rules to decide if this JWT should be used to validate the request. The JWT validation happens if any one of the rules matched. If the list is not empty and none of the rules matched, authentication will skip the JWT validation. Leave this empty to always trigger the JWT validation.

TriggerRule

Trigger rule to match against a request. The trigger rule is satisfied if and only if both rules, excluded_paths and include_paths are satisfied.

"excludedPaths": []istio.authentication.v1alpha1.StringMatch
"includedPaths": []istio.authentication.v1alpha1.StringMatch

Field	Type	Description	Default
`excludedPaths`	[]istio.authentication.v1alpha1.StringMatch	List of paths to be excluded from the request. The rule is satisfied if request path does not match to any of the path in this list.
`includedPaths`	[]istio.authentication.v1alpha1.StringMatch	List of paths that the request must include. If the list is not empty, the rule is satisfied if request path matches at least one of the path in the list. If the list is empty, the rule is ignored, in other words the rule is always satisfied.

PeerAuthenticationMethod

PeerAuthenticationMethod defines one particular type of authentication, e.g mutual TLS, JWT etc, (no authentication is one type by itself) that can be used for peer authentication. The type can be progammatically determine by checking the type of the “params” field.

"mtls": .istio.authentication.v1alpha1.MutualTls
"jwt": .istio.authentication.v1alpha1.Jwt

Field	Type	Description	Default
`mtls`	.istio.authentication.v1alpha1.MutualTls	Set if mTLS is used.
`jwt`	.istio.authentication.v1alpha1.Jwt	$hide_from_docs Set if JWT is used. This option is not yet available.

OriginAuthenticationMethod

OriginAuthenticationMethod defines authentication method/params for origin authentication. Origin could be end-user, device, delegate service etc. Currently, only JWT is supported for origin authentication.

"jwt": .istio.authentication.v1alpha1.Jwt

Field	Type	Description	Default
`jwt`	.istio.authentication.v1alpha1.Jwt	Jwt params for the method.

Policy

Policy defines what authentication methods can be accepted on workload(s), and if authenticated, which method/certificate will set the request principal (i.e request.auth.principal attribute).

Authentication policy is composed of 2-part authentication: - peer: verify caller service credentials. This part will set source.user (peer identity). - origin: verify the origin credentials. This part will set request.auth.user (origin identity), as well as other attributes like request.auth.presenter, request.auth.audiences and raw claims. Note that the identity could be end-user, service account, device etc.

Last but not least, the principal binding rule defines which identity (peer or origin) should be used as principal. By default, it uses peer.

Examples:

Policy to enable mTLS for all services in namespace frod

apiVersion: authentication.istio.io/v1alpha1
kind: Policy
metadata:
  name: mTLS_enable
  namespace: frod
spec:
  peers:
  - mtls:

Policy to disable mTLS for “productpage” service

apiVersion: authentication.istio.io/v1alpha1
kind: Policy
metadata:
  name: mTLS_disable
  namespace: frod
spec:
  targets:
  - name: productpage

Policy to require mTLS for peer authentication, and JWT for origin authentication for productpage:9000 except the path ‘/health_check’ . Principal is set from origin identity.

apiVersion: authentication.istio.io/v1alpha1
kind: Policy
metadata:
  name: mTLS_enable
  namespace: frod
spec:
  targets:
  - name: productpage
    ports:
    - number: 9000
  peers:
  - mtls:
  origins:
  - jwt:
      issuer: "https://securetoken.google.com"
      audiences:
      - "productpage"
      jwksUri: "https://www.googleapis.com/oauth2/v1/certs"
      jwt_headers:
      - "x-goog-iap-jwt-assertion"
      trigger_rules:
      - excluded_paths:
        - exact: /health_check
  principalBinding: USE_ORIGIN

"status": .core.solo.io.Status
"metadata": .core.solo.io.Metadata
"targets": []istio.authentication.v1alpha1.TargetSelector
"peers": []istio.authentication.v1alpha1.PeerAuthenticationMethod
"peerIsOptional": bool
"origins": []istio.authentication.v1alpha1.OriginAuthenticationMethod
"originIsOptional": bool
"principalBinding": .istio.authentication.v1alpha1.PrincipalBinding

Field	Type	Description
`status`	.core.solo.io.Status	Status indicates the validation status of this resource. Status is read-only by clients, and set by supergloo during validation
`metadata`	.core.solo.io.Metadata	Metadata contains the object metadata for this resource
`targets`	[]istio.authentication.v1alpha1.TargetSelector	List rules to select workloads that the policy should be applied on. If empty, policy will be used on all workloads in the same namespace.
`peers`	[]istio.authentication.v1alpha1.PeerAuthenticationMethod	List of authentication methods that can be used for peer authentication. They will be evaluated in order; the first validate one will be used to set peer identity (source.user) and other peer attributes. If none of these methods pass, request will be rejected with authentication failed error (401). Leave the list empty if peer authentication is not required
`peerIsOptional`	`bool`	Set this flag to true to accept request (for peer authentication perspective), even when none of the peer authentication methods defined above satisfied. Typically, this is used to delay the rejection decision to next layer (e.g authorization). This flag is ignored if no authentication defined for peer (peers field is empty).
`origins`	[]istio.authentication.v1alpha1.OriginAuthenticationMethod	List of authentication methods that can be used for origin authentication. Similar to peers, these will be evaluated in order; the first validate one will be used to set origin identity and attributes (i.e request.auth.user, request.auth.issuer etc). If none of these methods pass, request will be rejected with authentication failed error (401). A method may be skipped, depends on its trigger rule. If all of these methods are skipped, origin authentication will be ignored, as if it is not defined. Leave the list empty if origin authentication is not required.
`originIsOptional`	`bool`	Set this flag to true to accept request (for origin authentication perspective), even when none of the origin authentication methods defined above satisfied. Typically, this is used to delay the rejection decision to next layer (e.g authorization). This flag is ignored if no authentication defined for origin (origins field is empty).
`principalBinding`	.istio.authentication.v1alpha1.PrincipalBinding	Define whether peer or origin identity should be use for principal. Default value is USE_PEER. If peer (or origin) identity is not available, either because of peer/origin authentication is not defined, or failed, principal will be left unset. In other words, binding rule does not affect the decision to accept or reject request.

MeshPolicy

MeshPolicy copied from Policy

"status": .core.solo.io.Status
"metadata": .core.solo.io.Metadata
"targets": []istio.authentication.v1alpha1.TargetSelector
"peers": []istio.authentication.v1alpha1.PeerAuthenticationMethod
"peerIsOptional": bool
"origins": []istio.authentication.v1alpha1.OriginAuthenticationMethod
"originIsOptional": bool
"principalBinding": .istio.authentication.v1alpha1.PrincipalBinding

Field	Type	Description
`status`	.core.solo.io.Status	Status indicates the validation status of this resource. Status is read-only by clients, and set by supergloo during validation
`metadata`	.core.solo.io.Metadata	Metadata contains the object metadata for this resource
`targets`	[]istio.authentication.v1alpha1.TargetSelector	List rules to select workloads that the policy should be applied on. If empty, policy will be used on all workloads in the same namespace.
`peers`	[]istio.authentication.v1alpha1.PeerAuthenticationMethod	List of authentication methods that can be used for peer authentication. They will be evaluated in order; the first validate one will be used to set peer identity (source.user) and other peer attributes. If none of these methods pass, request will be rejected with authentication failed error (401). Leave the list empty if peer authentication is not required
`peerIsOptional`	`bool`	Set this flag to true to accept request (for peer authentication perspective), even when none of the peer authentication methods defined above satisfied. Typically, this is used to delay the rejection decision to next layer (e.g authorization). This flag is ignored if no authentication defined for peer (peers field is empty).
`origins`	[]istio.authentication.v1alpha1.OriginAuthenticationMethod	List of authentication methods that can be used for origin authentication. Similar to peers, these will be evaluated in order; the first validate one will be used to set origin identity and attributes (i.e request.auth.user, request.auth.issuer etc). If none of these methods pass, request will be rejected with authentication failed error (401). A method may be skipped, depends on its trigger rule. If all of these methods are skipped, origin authentication will be ignored, as if it is not defined. Leave the list empty if origin authentication is not required.
`originIsOptional`	`bool`	Set this flag to true to accept request (for origin authentication perspective), even when none of the origin authentication methods defined above satisfied. Typically, this is used to delay the rejection decision to next layer (e.g authorization). This flag is ignored if no authentication defined for origin (origins field is empty).
`principalBinding`	.istio.authentication.v1alpha1.PrincipalBinding	Define whether peer or origin identity should be use for principal. Default value is USE_PEER. If peer (or origin) identity is not available, either because of peer/origin authentication is not defined, or failed, principal will be left unset. In other words, binding rule does not affect the decision to accept or reject request.

TargetSelector

TargetSelector defines a matching rule to a workload. A workload is selected if it is associated with the service name and service port(s) specified in the selector rule.

"name": string
"ports": []istio.authentication.v1alpha1.PortSelector

Field	Type	Description	Default
`name`	`string`	REQUIRED. The name must be a short name from the service registry. The fully qualified domain name will be resolved in a platform specific manner.
`ports`	[]istio.authentication.v1alpha1.PortSelector	Specifies the ports. Note that this is the port(s) exposed by the service, not workload ports. For example, if a service is defined as below, then `8000` should be used, not `9000`. `kind: Service metadata: ... spec: ports: - name: http port: 8000 targetPort: 9000 selector: app: backend` Leave empty to match all ports that are exposed.

PortSelector

PortSelector specifies the name or number of a port to be used for matching targets for authentication policy. This is copied from networking API to avoid dependency.

"number": int
"name": string

Field	Type	Description	Default
`number`	`int`	Valid port number
`name`	`string`	Port name

PrincipalBinding

Description: Associates authentication with request principal.

Name	Description
USE_PEER	Principal will be set to the identity from peer authentication.
USE_ORIGIN	Principal will be set to the identity from origin authentication.