Authentication Policy

4 minute read

This package defines user-facing authentication policy.

MutualTls

TLS authentication params.

Field	Type	Description	Required
`mode`	`Mode`	Defines the mode of mTLS authentication.	No
`allowTls`	`bool`	Deprecated. Please use mode = PERMISSIVE instead. If set, will translate 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.	No

MutualTls.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 with Client cert.

PeerAuthenticationMethod

PeerAuthenticationMethod defines one particular type of authentication. Only mTLS is supported at the moment. The type can be progammatically determine by checking the type of the “params” field.

Field	Type	Description	Required
`mtls`	`MutualTls (oneof)`	Set if mTLS is used.	Yes

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. The policy name must be default, and it contains no rule for targets.

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

Policy to disable mTLS for “productpage” service

apiVersion: authentication.istio.io/v1alpha1
kind: Policy
metadata:
  name: productpage-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: productpage-mTLS-with-JWT
  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"
      jwtHeaders:
      - "x-goog-iap-jwt-assertion"
      triggerRules:
      - excludedPaths:
        - exact: /health_check
  principalBinding: USE_ORIGIN

Field	Type	Description	Required
`peers`	`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	No
`targets`	`TargetSelector[]`	Deprecated. Only mesh-level and namespace-level policies are supported. 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.	No
`peerIsOptional`	`bool`	Deprecated. Should set mTLS to PERMISSIVE instead. 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).	No
`origins`	`OriginAuthenticationMethod[]`	Deprecated. Please use security/v1beta1/RequestAuthentication instead. 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.	No
`originIsOptional`	`bool`	Deprecated. Please use security/v1beta1/RequestAuthentication instead. 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).	No
`principalBinding`	`PrincipalBinding`	Deprecated. Source principal is always from peer, and request principal is always from RequestAuthentication. 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.	No

Was this information useful?

Do you have any suggestions for improvement?

Thanks for your feedback!