Authorization for groups and list claims

This tutorial walks you through examples to configure the groups-baseauthorization and the authorization of list-typed claims in Istio.

Before you begin

Setup the required namespace and workloads

This tutorial runs in a new namespace called authz-groups-test-ns,with two workloads, httpbin and sleep, both running with an Envoy sidecarproxy. The following command sets an environmental variable to store thename of the namespace, creates the namespace, and starts the two workloads.Before running the following command, you need to enter the directorycontaining the Istio installation files.

  • Set the value of the NS environmental variable to authz-groups-test-ns:
  1. $ export NS=authz-groups-test-ns
  • Make sure that the NS environmental variable points to a testing-onlynamespace. Run the following command to delete all resources in the namespacepointed by the NS environmental variable.
  1. $ kubectl delete namespace $NS
  • Create the namespace for this tutorial:
  1. $ kubectl create ns $NS
  • Create the httpbin and sleep workloads and deployments:

ZipZip

  1. $ kubectl apply -f <(istioctl kube-inject -f @samples/httpbin/httpbin.yaml@) -n $NS
  2. $ kubectl apply -f <(istioctl kube-inject -f @samples/sleep/sleep.yaml@) -n $NS
  • To verify that httpbin and sleep workloads are running and sleep is able toreach httpbin, run the following curl command:
  1. $ kubectl exec $(kubectl get pod -l app=sleep -n $NS -o jsonpath={.items..metadata.name}) -c sleep -n $NS -- curl http://httpbin.$NS:8000/ip -s -o /dev/null -w "%{http_code}\n"

When the command succeeds, it returns the HTTP code 200.

Configure JSON Web Token (JWT) authentication with mutual TLS

The authentication policy you apply next enforces that a valid JWT is needed toaccess the httpbin workload.The JSON Web Key Set (JWKS) endpoint defined in the policy must sign the JWT.This tutorial uses theJWKS endpointfrom the Istio code base and usesthis sample JWT.The sample JWT contains a JWT claim with a groups claim key and a list ofstrings, ["group1", "group2"] as the claim value.The JWT claim value could either be a string or a list of strings; both typesare supported.

  • Apply an authentication policy to require both mutual TLS andJWT authentication for httpbin.
  1. $ cat <<EOF | kubectl apply -n $NS -f -
  2. apiVersion: "authentication.istio.io/v1alpha1"
  3. kind: "Policy"
  4. metadata:
  5.   name: "require-mtls-jwt"
  6. spec:
  7.   targets:
  8.   - name: httpbin
  9.   peers:
  10.   - mtls: {}
  11.   origins:
  12.   - jwt:
  13.       issuer: "testing@secure.istio.io"
  14.       jwksUri: "https://raw.githubusercontent.com/istio/istio/release-1.4/security/tools/jwt/samples/jwks.json"
  15.   principalBinding: USE_ORIGIN
  16. EOF
  • Apply a DestinationRule policy on sleep to use mutual TLS whencommunicating with httpbin.
  1. $ cat <<EOF | kubectl apply -n $NS -f -
  2. apiVersion: networking.istio.io/v1alpha3
  3. kind: DestinationRule
  4. metadata:
  5.   name: use-mtls-on-sleep
  6. spec:
  7.   host: httpbin.$NS.svc.cluster.local
  8.   trafficPolicy:
  9.     tls:
  10.       mode: ISTIO_MUTUAL
  11. EOF
  • Set the TOKEN environmental variable to contain a valid sample JWT.
  1. $ TOKEN=$(curl https://raw.githubusercontent.com/istio/istio/release-1.4/security/tools/jwt/samples/groups-scope.jwt -s)
  • Connect to the httpbin workload:
  1. $ kubectl exec $(kubectl get pod -l app=sleep -n $NS -o jsonpath={.items..metadata.name}) -c sleep -n $NS -- curl http://httpbin.$NS:8000/ip -s -o /dev/null -w "%{http_code}\n" --header "Authorization: Bearer $TOKEN"

When a valid JWT is attached, it returns the HTTP code 200.

  • Verify that the connection to the httpbin workload fails when the JWT is not attached:
  1. $ kubectl exec $(kubectl get pod -l app=sleep -n $NS -o jsonpath={.items..metadata.name}) -c sleep -n $NS -- curl http://httpbin.$NS:8000/ip -s -o /dev/null -w "%{http_code}\n"

When no valid JWT is attached, it returns the HTTP code 401.

Configure groups-based authorization

This section creates a policy to authorize the access to the httpbinworkload if the requests are originated from specific groups.As there may be some delays due to caching and other propagation overhead,wait until the newly defined authorization policy to take effect.

  • Run the following command to create a deny-all policy in the default namespace.The policy doesn’t have a selector field, which applies the policy to every workload in the$NS namespace. The spec: field of the policy has the empty value {}.The empty value means that no traffic is permitted, effectively denying all requests.
  1. $ cat <<EOF | kubectl apply -n $NS -f -
  2. apiVersion: security.istio.io/v1beta1
  3. kind: AuthorizationPolicy
  4. metadata:
  5.   name: deny-all
  6. spec:
  7.   {}
  8. EOF
  • Once the policy takes effect, verify that Istio rejected the curlconnection to the httpbin workload:
  1. $ kubectl exec $(kubectl get pod -l app=sleep -n $NS -o jsonpath={.items..metadata.name}) -c sleep -n $NS -- curl http://httpbin.$NS:8000/ip -s -o /dev/null -w "%{http_code}\n" --header "Authorization: Bearer $TOKEN"

Once the policy takes effect, the command returns the HTTP code 403.

  • To give read access to the httpbin workload, create the httpbin-viewerpolicy that applies to workload with label app: httpbin and allows users ingroup1 to access it with GET method:
  1. $ cat <<EOF | kubectl apply -n $NS -f -
  2. apiVersion: "security.istio.io/v1beta1"
  3. kind: "AuthorizationPolicy"
  4. metadata:
  5.   name: "httpbin-viewer"
  6. spec:
  7.   selector:
  8.     matchLabels:
  9.       app: httpbin
  10.   rules:
  11.   - to:
  12.     - operation:
  13.         methods: ["GET"]
  14.     when:
  15.     - key: request.auth.claims[groups]
  16.       values: ["group1"]
  17. EOF

Wait for the newly defined policy to take effect.

  • After the policy takes effect, verify the connection to the httpbinworkload succeeds:
  1. $ kubectl exec $(kubectl get pod -l app=sleep -n $NS -o jsonpath={.items..metadata.name}) -c sleep -n $NS -- curl http://httpbin.$NS:8000/ip -s -o /dev/null -w "%{http_code}\n" --header "Authorization: Bearer $TOKEN"

The HTTP header including a valid JWT with the groups claimvalue of ["group1", "group2"] returns HTTP code 200since it contains group1.

Configure the authorization of list-typed claims

Istio supports configuring the authorization of list-typed claims.The example JWT contains a JWT claim with a scope claim key anda list of strings, ["scope1", "scope2"] as the claim value.You may use the gen-jwtpython scriptto generate a JWT with other list-typed claims for testing purposes.Follow the instructions in the gen-jwt script to use the gen-jwt.py file.

  • To allow requests with a JWT including a list-typed scope claim with the value of scope1,update the policy httpbin-viewer with the following command:
  1. $ cat <<EOF | kubectl apply -n $NS -f -
  2. apiVersion: "security.istio.io/v1beta1"
  3. kind: "AuthorizationPolicy"
  4. metadata:
  5.   name: "httpbin-viewer"
  6. spec:
  7.   selector:
  8.     matchLabels:
  9.       app: httpbin
  10.   rules:
  11.   - to:
  12.     - operation:
  13.         methods: ["GET"]
  14.     when:
  15.     - key: request.auth.claims[scope]
  16.       values: ["scope1"]
  17. EOF

Wait for the newly defined policy to take effect.

  • After the policy takes effect, verify that the connection tothe httpbin workload succeeds:
  1. $ kubectl exec $(kubectl get pod -l app=sleep -n $NS -o jsonpath={.items..metadata.name}) -c sleep -n $NS -- curl http://httpbin.$NS:8000/ip -s -o /dev/null -w "%{http_code}\n" --header "Authorization: Bearer $TOKEN"

The HTTP header including a valid JWT with the scope claimvalue of ["scope1", "scope2"] returns HTTP code 200since it contains scope1.

Cleanup

After completing this tutorial, run the following command to delete allresources created in the namespace.

  1. $ kubectl delete namespace $NS

See also

Introducing the Istio v1beta1 Authorization Policy

Introduction, motivation and design principles for the Istio v1beta1 Authorization Policy.

Micro-Segmentation with Istio Authorization

Describe Istio's authorization feature and how to use it in various use cases.

Authorization Policy Trust Domain Migration

Shows how to migrate from one trust domain to another without changing authorization policy.

Authorization for HTTP traffic

Shows how to set up role-based access control for HTTP traffic.

Authorization for TCP traffic

Shows how to set up access control for TCP traffic.

Security

Describes Istio's authorization and authentication functionality.