OpenAPI

In this lab, we are going to deploy the Microgateway in Kubernetes and protect a backend with an OpenAPI spec.

Overview

Goal

Configure the Microgateway to protect a backend service by enforcing an OpenAPI spec.

Notes

Without a valid license, Airlock Microgateway runs as Community Edition. For more details see Features and support.

Preparation

  1. Deploy the Kubernetes exercise
  2. Run the following commands:
    3. copy
    cd openapi/exercise/
    copy
    kubectl apply -k .
  3. The exercise has been deployed successfully.

The exercise does not contain any licenses. Therefore, Airlock Microgateway runs as Community Edition

For more details see Features and support.

To run the exercise as Premium Edition, copy a valid license to .templates/microgateway/secret/microgateway.lic and execute kubectl apply -k . to re-deploy the Microgateway.

Instruction

  1. Configure Microgateway to enforce the OpenAPI spec
  2. Edit Microgateway's configuration file.

    3. Edit the file config/config.yaml and configure the following settings:

    • For the mapping openapi-petstore-api:
    • api_security.openapi.spec_file: /config/openapi-petstore.json

    Use the (Microgateway) DSL reference to accomplish this task.

    details...

    The modified part of the config.yaml looks as follow:

        - name: openapi-petstore-api 
        entry_path: 
          value: /v3/ 
        ...
        ...   
        api_security: 
          openapi: 
            spec_file: /config/openapi-petstore.json
  3. Apply the new configuration.

    4. After modifying the configuration file, apply the new configuration by running the following command:

    copy
    kubectl apply -k .
  4. Deploy the Microgateway with the new configuration.
    5. details...
    copy
    kubectl rollout restart deployment/microgateway

    A running Microgateway does not automatically reload the new configmap. The existing Microgatway pod must be killed. This way a new pod is deployed with the adapted configuration.

  5. Check the status of the Microgateway pod.
    6. details...

    List the Microgateway pods:

    copy
    kubectl get pod
    copy
    kubectl get pod -l app=microgateway

    Show Microgateway pod details:

    copy
    kubectl describe pod -l app=microgateway

    Once the pod is ready to process requests, the output of the kubectl describe command shows that the pod is ready.

    ...
   Conditions: 
  Type              Status 
  Initialized       True 
  Ready             True 
  ContainersReady   True 
  PodScheduled      True
...
  6. The Microgateway enforces the OpenAPI spec and protects the backend service.
  1. Send requests to the backend
  2. Connect to the website:
    • Open the URL in your browser: https://<MINIKUBE_IP>/
  3. Expand PUT /pet Update an existing pet
  4. Click Try it out
  5. Click Execute
  6. The response code is 200 and indicates that the request has been processed successfully.
  7. Replace the content of the example value textfield
    8. copy
    { 
  "photoUrls": [ 
    "photoUrls", 
    "photoUrls" 
  ], 
  "name": ["doggie"], 
  "id": 0, 
  "category": { 
    "name": "name", 
    "id": 6 
  }, 
  "tags": [ 
    { 
      "name": "name", 
      "id": 1 
    }, 
    { 
      "name": "name", 
      "id": 1 
    } 
  ], 
  "status": "available" 
}

    The difference to the original request payload is that the name is sent as a list.

    • Original: "name": "doggie",
    • Value from above: "name": ["doggie"],
  8. Click Execute
  9. The response code is 400 and the response code contains a request id from the Microgateway.
  10. Watch the logs of the Microgateway pod.
    11. details...

    Check the logs of the Microgateway configbuilder.

    copy
    kubectl logs -l app=microgateway -c configbuilder -f

    Follow the logs of the Microgateway runtime container.

    copy
    kubectl logs -l app=microgateway -c microgateway -f

    Follow the logs of the Microgateway runtime container and filter for interesting log messages. Mainly these are the log messages with the log_id WR-SG-SUMMARY and WR-SG-BLOCK. Under some circumstances, WR-SG-REJECT or WR-SG-BACK is also very interesting.

    copy
    kubectl logs -l app=microgateway -c microgateway -f | grep -iE "WR-SG-(SUMMARY|BLOCK|REJECT|BACK)"
  11. The following log messages could be noticed when sending an invalid payload:
    12. "log_id":"WR-SG-SUMMARY", ...,"mapping":"openapi-petstore-api", ...,"action":"blocked","attack_type":"Noncompliant API usage","block_type":"OpenAPI", ...

"log_id":"WR-SG-BLOCK-115", ... "mapping":"openapi-petstore-api", ..."attack_type":"Noncompliant API usage","block_type":"OpenAPI","constraint":"Type mismatch","th_mode":"BLOCK","position":"RequestValidator.Body.name","message":"Value is not a String"
    • Useful information for troubleshooting
    • Check also the position key in the log message to understand the reason why the OpenAPI filter blocked or rejected an HTTP request/response or could not read the OpenAPI spec. file.
    • For every request handled by the filtering engine, a log message with the "log_id": "WR-SG-SUMMARY" is logged. This log entry might also contain helpful information.

    It explains that the request has been blocked. The reason is that the OpenAPI spec defined name as type string.

    In case that you run Airlock Microgateway as Community Edition, this request is not being blocked. For more details see Features and support.

    The WR-SG-SUMMARY log message indicates that in the key action.

    "log_id":"WR-SG-SUMMARY", ..., "action":"allowed", ...

Cleanup

  1. Delete Kubernetes resources from previously exercises or solutions
  2. Run the following commands:
    3. copy
    kubectl delete all,ing,cm,secrets,pv,pvc,sa,roles,rolebindings,clusterroles,clusterrolebindings -l purpose=microgateway-tutorial
  3. All relevant Kubernetes resources in the namespace have been deleted successfully.