--- title: Authentication Policy description: Authentication policy for Istio services. location: https://istio.io/docs/reference/config/istio.authentication.v1alpha1.html layout: protoc-gen-docs generator: protoc-gen-docs number_of_entries: 9 ---

This package defines user-facing authentication policy.

## 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.

Example,

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

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:
    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`.

## MutualTls

TLS authentication params.

Field | Type | Description
--- | --- | ---
`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` | `MutualTls.Mode` | Defines the mode of mTLS authentication.

## 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, and client cert can be omitted.

## 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.

Field | Type | Description
--- | --- | ---
`jwt` | `Jwt` | Jwt params for the method.

## 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.

Field | Type | Description
--- | --- | ---
`mtls` | `MutualTls (oneof)` | Set if mTLS is used.

## 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 authenticationn for productpage:9000. Principal is set from origin identity.

    apiVersion: authentication.istio.io/v1alpha1
    kind: Policy
    metadata:
      name: mTLS_enable
      namespace: frod
    spec:
      target:
      - 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"
      principaBinding: USE_ORIGIN

Policy to require mTLS for peer authentication, and JWT for origin authenticationn for productpage:9000, but allow origin authentication failed. Principal is set from origin identity. Note: this example can be used for use cases when we want to allow request from certain peers, given it comes with an approperiate authorization poicy to check and reject request accoridingly.

    apiVersion: authentication.istio.io/v1alpha1
    kind: Policy
    metadata:
      name: mTLS_enable
      namespace: frod
    spec:
      target:
      - 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"
      originIsOptional: true
      principalBinding: USE_ORIGIN

Field | Type | Description
--- | --- | ---
`targets` | `TargetSelector[]` | List rules to select destinations that the policy should be applied on. If empty, policy will be used on all destinations in the same namespace.
`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, and peerisoptional flag is false (see below), 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` | `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, and originisoptional is false (see below), request will be rejected with authentication failed error (401). 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` | `PrincipalBinding` | Define whether peer or origin identity should be use for principal. Default value is USE_PEER. If peer (or orgin) 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.

## PortSelector

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

Field | Type | Description
--- | --- | ---
`number` | `uint32 (oneof)` | Valid port number
`name` | `string (oneof)` | Port name

## PrincipalBinding

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.

## TargetSelector

TargetSelector defines a matching rule to a service/destination.

Field | Type | Description
--- | --- | ---
`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` | `PortSelector[]` | Specifies the ports on the destination. Leave empty to match all ports that are exposed.