When a client sends an API key to authenticate with another service in the service mesh, the sidecar proxy can extract and validate the API key by using the API key extauth module. In addition, if the API key contains additional metadata, such as the user ID or email address, Gloo automatically extracts these metadata fields from the API key, and forwards them with the API key to the OPA module where additional validation checks can be performed.

In this guide, you can try out different API key and OPA configurations, such as:

  • Successfully validate requests with additional API key metadata by using the OPA extauth module.
  • Deny requests that do not provide additional metadata in the API key.
  • Create an OPA rule to allow only certain API keys.

Before you begin

  1. Complete the multicluster getting started guide to set up the following testing environment.

    • Three clusters along with environment variables for the clusters and their Kubernetes contexts.
    • The Gloo meshctl CLI, along with other CLI tools such as kubectl and istioctl.
    • The Gloo management server in the management cluster, and the Gloo agents in the workload clusters.
    • Istio installed in the workload clusters.
    • A simple Gloo workspace setup.
  2. Install Bookinfo and other sample apps.

  3. Make sure that the external auth service is installed and running. If not, install the external auth service.

      kubectl get pods --context $REMOTE_CONTEXT1  -A -l app=ext-auth-service

  4. Make sure that the extAuthService.extAuth.apiKey.metadataToState=true field is set on your external auth server. In Gloo Mesh Enterprise version 2.6.0 and later, this setting ensures that Gloo automatically extracts metadata fields from the API key to forward to OPA for validation checks.

    1. Check the Helm releases in your cluster. Depending on your installation method, you either have only a main installation release (such as gloo-platform), or a main installation and a separate add-ons release (such as gloo-agent-addons), in addition to your CRDs release.

        helm ls -A --kube-context ${REMOTE_CONTEXT1}

    2. Get your current installation values.

      • If you have only one release for your installation, get those values. Note that your Helm release might have a different name.
          helm get values gloo-platform -n gloo-mesh -o yaml --kube-context ${REMOTE_CONTEXT1} > gloo-values.yaml
open gloo-values.yaml
      • If you have a separate add-ons release, get those values.
          helm get values gloo-agent-addons -n gloo-mesh -o yaml --kube-context ${REMOTE_CONTEXT1} > gloo-agent-addons.yaml
open gloo-agent-addons.yaml

    3. Add the following settings to allow API key metadata to be sent to the OPA state.

        
extAuthService:
  enabled: true
  extAuth:
    apiKey:
      metadataToState: true

    4. Upgrade your Helm release.

      • If you have only one release for your installation, upgrade the gloo-platform release. Note that your Helm release might have a different name.
          helm upgrade gloo-platform gloo-platform/gloo-platform --kube-context ${REMOTE_CONTEXT1} \
   --namespace gloo-mesh \
   -f gloo-values.yaml \
   --version $GLOO_VERSION
      • If you have a separate add-ons release, upgrade the gloo-agent-addons release.
          helm upgrade gloo-agent-addons gloo-platform/gloo-platform --kube-context ${REMOTE_CONTEXT1} \
   --namespace gloo-mesh \
   -f gloo-agent-addons.yaml \
   --version $GLOO_VERSION

  5. Make sure that you have the following CLI tools, or something comparable:

    • base64 to encode strings.

Configure API key and OPA external auth

  1. Create an extauth server that you use to enforce the extauth policies in this guide.

      kubectl apply --context $REMOTE_CONTEXT1 -f - <<EOF
apiVersion: admin.gloo.solo.io/v2
kind: ExtAuthServer
metadata:
  name: ext-auth-server
  namespace: bookinfo
spec:
  destinationServer:
    port:
      number: 8083
    ref:
      cluster: $REMOTE_CLUSTER1
      name: ext-auth-service
      namespace: gloo-mesh
EOF

  2. Create a Kubernetes secret that stores your API key and additional metadata, such as the user ID and email address.

      kubectl -n bookinfo --context $REMOTE_CONTEXT1 create secret generic user-glooy \
--type extauth.solo.io/apikey \
--from-literal=user-id=user-id-glooy \
--from-literal=user-email=glooy@solo.io \
--from-literal=user-name=glooy \
--from-literal=api-key=N2YwMDIxZTEtNGUzNS1jNzgzLTRkYjAtYjE2YzRkZGVmNjcy

  3. Label the secret so that you can reference this secret in your extauth policy more easily.

      kubectl -n bookinfo --context $REMOTE_CONTEXT1 label secret user-glooy extauth=apikey

  4. Create a configmap for an OPA rule that validates the user’s email address that you added earlier. The following examples verifies that the email address in the user-email field ends with solo.io.

      kubectl apply --context $REMOTE_CONTEXT1 -f - <<EOF
apiVersion: v1
kind: ConfigMap
metadata:
  name: allow-api-key-from-trusted-email-domain
  namespace: bookinfo
  labels:
    team: infrastructure
data:
  policy.rego: |
    package test

    default allow = false
    allow {
      endswith(input.state["api_key_data"]["Metadata"]["user-email"], "@solo.io")
    }
EOF

  5. Create an extauth policy that references both the secret that contains the API key and the configmap with your OPA rule. Note that Gloo Mesh Enterprise automatically extracts the user-email field from the API key and passes it on to the OPA module for further validation.

      kubectl apply --context $REMOTE_CONTEXT1 -f - <<EOF
apiVersion: security.policy.gloo.solo.io/v2
kind: ExtAuthPolicy
metadata:
  name: ratings-apikey
  namespace: bookinfo
spec:
  applyToDestinations:
  - selector:
      labels:
        app: ratings
  config:
    server:
      name: ext-auth-server
      namespace: bookinfo
      cluster: $REMOTE_CLUSTER1
    glooAuth:
      configs:
      - name: APIKey
        apiKeyAuth:
          headerName: api-key
          k8sSecretApikeyStorage:
            labelSelector:
              extauth: apikey
      - name: opa
        opaAuth:
          modules:
          - name: allow-api-key-from-trusted-email-domain
            namespace: bookinfo
          query: "data.test.allow == true"
EOF

  6. Send a request to the ratings app and pass the API key that you added to the Kubernetes secret. Create a temporary curl pod in the bookinfo namespace, so that you can test the app setup. You can also use this method in Kubernetes 1.23 or later, but an ephemeral container might be simpler.

    1. Create the curl pod.
        kubectl run -it -n bookinfo --context $REMOTE_CONTEXT1 curl \
  --image=curlimages/curl:7.73.0 --rm  -- sh
    2. Send a request to the ratings app.
        curl http://ratings:9080/ratings/1 -v -i -H "api-key: N2YwMDIxZTEtNGUzNS1jNzgzLTRkYjAtYjE2YzRkZGVmNjcy"
    3. Exit the temporary pod. The pod deletes itself.
        exit

    Example output:

      < HTTP/2 200 
HTTP/2 200 
< content-type: application/json
content-type: application/json
< date: Tue, 28 Mar 2023 20:16:40 GMT
date: Tue, 28 Mar 2023 20:16:40 GMT
< x-envoy-upstream-service-time: 5
x-envoy-upstream-service-time: 5
< server: istio-envoy
server: istio-envoy

* Connection #0 to host www.example.com left intact
{"id":1,"ratings":{"Reviewer1":5,"Reviewer2":4}}%

  7. Create another configmap and add an OPA rule that references metadata that does not exist in the API key.

      kubectl apply --context $REMOTE_CONTEXT1 -f - <<EOF
apiVersion: v1
kind: ConfigMap
metadata:
  name: allow-api-key-from-certain-cost-centers
  namespace: bookinfo
  labels:
    team: infrastructure
data:
  policy.rego: |
    package test

    default allow = false
    allow {
      startswith(input.state["api_key_data"]["Metadata"]["user-cost-center"], "733")
    }
EOF

  8. Update the extauth policy to reference the new configmap.

      kubectl apply --context $REMOTE_CONTEXT1 -f - <<EOF
apiVersion: security.policy.gloo.solo.io/v2
kind: ExtAuthPolicy
metadata:
  name: ratings-apikey
  namespace: bookinfo
spec:
  applyToDestinations:
  - selector:
      labels:
        app: ratings
  config:
    server:
      name: ext-auth-server
      namespace: bookinfo
      cluster: $REMOTE_CLUSTER1
    glooAuth:
      configs:
      - name: APIKey
        apiKeyAuth:
          headerName: api-key
          k8sSecretApikeyStorage:
            labelSelector:
              extauth: apikey
      - name: opa
        opaAuth:
          modules:
          - name: allow-api-key-from-certain-cost-centers
            namespace: bookinfo
          query: "data.test.allow == true"
EOF

  9. Send another request to the ratings service. This time, the request is denied, because the new user-cost-center metadata field could not be extracted from the API key to be processed by the OPA module.

    1. Create the curl pod.
        kubectl run -it -n bookinfo --context $REMOTE_CONTEXT1 curl \
  --image=curlimages/curl:7.73.0 --rm  -- sh
    2. Send a request to the ratings app.
        curl http://ratings:9080/ratings/1 -v -i -H "api-key: N2YwMDIxZTEtNGUzNS1jNzgzLTRkYjAtYjE2YzRkZGVmNjcy"
    3. Exit the temporary pod. The pod deletes itself.
        exit

    Example output:

      * Connection state changed (MAX_CONCURRENT_STREAMS == 2147483647)!
< HTTP/2 403 
HTTP/2 403 
< date: Tue, 28 Mar 2023 20:51:24 GMT
date: Tue, 28 Mar 2023 20:51:24 GMT
< server: istio-envoy
server: istio-envoy

  10. Add the user-cost-center field to the API key.

      kubectl -n bookinfo --context $REMOTE_CONTEXT1  get secret user-glooy -o json | jq --arg cost_center "$(echo -n 73355 | base64)" '.data["user-cost-center"]=$cost_center' | kubectl apply -f -

  11. Send another request to the ratings service. This time, the request succeeds as the user-cost-center can be extracted and forwarded to the OPA extauth module for further validation.

    1. Create the curl pod.
        kubectl run -it -n bookinfo --context $REMOTE_CONTEXT1 curl \
  --image=curlimages/curl:7.73.0 --rm  -- sh
    2. Send a request to the ratings app.
        curl http://ratings:9080/ratings/1 -v -i -H "api-key: N2YwMDIxZTEtNGUzNS1jNzgzLTRkYjAtYjE2YzRkZGVmNjcy"
    3. Exit the temporary pod. The pod deletes itself.
        exit

    Example output:

      * Connection state changed (MAX_CONCURRENT_STREAMS == 2147483647)!
< HTTP/2 200 
HTTP/2 200 
< content-type: application/json
content-type: application/json
< date: Tue, 28 Mar 2023 20:54:17 GMT
date: Tue, 28 Mar 2023 20:54:17 GMT
< x-envoy-upstream-service-time: 3
x-envoy-upstream-service-time: 3
< server: istio-envoy
server: istio-envoy

  12. Create another configmap and add another OPA rule to verify the API key itself and deny requests that use a specific API key.

      kubectl apply --context $REMOTE_CONTEXT1 -f - <<EOF
apiVersion: v1
kind: ConfigMap
metadata:
  name: allow-api-key-from-allowlist
  namespace: bookinfo
  labels:
    team: infrastructure
data:
  policy.rego: |
    package test

    default allow = false
    is_key_allowed = true {
      allowed_keys := { "N2YwMDIxZTEtNGUzNS1jNzgzLTRkYjAtYjE2YzRkZGVmNjcy", "974b3a3f-0aa9-4a94-bfe7-3fd42942d5e3" }
      input.state["api_key_value"] == allowed_keys[_]
    }
    allow {
      # deny any keys listed in the allowed_keys array.
      not is_key_allowed
    }
EOF

  13. Update the extauth policy to use the new OPA rule.

      kubectl apply --context $REMOTE_CONTEXT1 -f - <<EOF
apiVersion: security.policy.gloo.solo.io/v2
kind: ExtAuthPolicy
metadata:
  name: ratings-apikey
  namespace: bookinfo
spec:
 applyToRoutes:
 - route:
     labels:
       route: ratings
 config:
   server:
     name: ext-auth-server
     namespace: bookinfo
     cluster: $REMOTE_CLUSTER1
   glooAuth:
     configs:
     - name: APIKey
       apiKeyAuth:
         k8sSecretApikeyStorage:
           labelSelector:
             extauth: apikey
     - name: opa
       opaAuth:
         modules:
         - name: allow-api-key-from-allowlist
           namespace: bookinfo
         query: "data.test.allow == true"
EOF

  14. Send another request to the ratings app. This time, the request is denied, because the API key that is used in the curl request is part of the API keys that are not allowed to be forwarded to the ratings app.

    1. Create the curl pod.
        kubectl run -it -n bookinfo --context $REMOTE_CONTEXT1 curl \
  --image=curlimages/curl:7.73.0 --rm  -- sh
    2. Send a request to the ratings app.
        curl http://ratings:9080/ratings/1 -v -i -H "api-key: N2YwMDIxZTEtNGUzNS1jNzgzLTRkYjAtYjE2YzRkZGVmNjcy"
    3. Exit the temporary pod. The pod deletes itself.
        exit

    Example output:

      * Connection state changed (MAX_CONCURRENT_STREAMS == 2147483647)!
< HTTP/2 403 
HTTP/2 403 
< date: Tue, 28 Mar 2023 20:54:45 GMT
date: Tue, 28 Mar 2023 20:54:45 GMT
< server: istio-envoy
server: istio-envoy

Cleanup

You can optionally remove the resources that you set up as part of this guide.

  kubectl delete extauthpolicy ratings-apikey -n bookinfo --context $REMOTE_CONTEXT1
kubectl delete configmap allow-api-key-from-allowlist -n bookinfo --context $REMOTE_CONTEXT1
kubectl delete configmap allow-api-key-from-certain-cost-centers -n bookinfo --context $REMOTE_CONTEXT1
kubectl delete configmap allow-api-key-from-trusted-email-domain -n bookinfo --context $REMOTE_CONTEXT1
kubectl delete secret user-glooy -n bookinfo --context $REMOTE_CONTEXT1

Known limitations

When you have multiple Kubernetes secrets that share the same label, and you use labels to reference the Kubernetes secret, the extauth policy passes the API key and metadata information from the first Kubernetes secret that is found to the OPA module.