Deploy as a Docker Image

In this walk-through, we will use Docker Compose to stand up a mock Nginx service protected by the Corsha Gatekeeper.

Technical Artifact Names

The Gatekeeper's Docker image is named corsha-docker.jfrog.io/proxy for backward compatibility. All references to "proxy" in commands, service names, and configuration refer to the Corsha Gatekeeper.

Creating your Filesystem

Although we chose to deploy our Docker containers with Docker Compose, in an actual deployment you should leverage the infrastructure you currently use to deploy a Docker container.

We will create the directory structure and files as listed:

├── docker-compose.yaml
├── proxy-config.yaml
├── auth-server-certs
│   ├── cert.crt
│   └── cert.key
├── html
│   └── data.json
├── tls-certs # tls certs are expected at this path, but are not required for this demo
├── ca-certs # ca certs are expected at this path, but are not required for this demo

4 directories, 5 files

If you need to obtain the Corsha Gatekeeper or have any questions regarding the deployment of the Corsha Gatekeeper, reach out to your Corsha TPOC.

Creating a Default Docker Compose File with Corsha

First, login to the Corsha Docker repository to pull Corsha images.

docker login corsha-docker.jfrog.io --username <username>

Second, we need to generate a PROXY_SECRET to seed the Gatekeeper. The command to generate a proxy secret is defined in the Generating A Proxy Secret Guide. This secret will be passed to the Gatekeeper via an environment variable in the docker compose.

Next, we will create a Docker Compose file that can deploy the Corsha Gatekeeper.

Copy the following into a file named docker-compose.yaml and replace <latest version> with the version of the Corsha Gatekeeper provided by your Corsha TPOC:

version: "3.9"
services:
  proxy:
    environment:
      - PROXY_SECRET=< Generated via the "Generating A Proxy Secret Guide" referenced above >
    image: corsha-docker.jfrog.io/proxy:<latest version>
    ports:
      # listen address for the proxy service
      - "8080:8080"
    volumes:
      - ./proxy-config.yaml:/etc/proxy/proxy-config.yaml
#     - ./tls-certs:/etc/pki/tls/private/  tls certs are expected at this path, but are not required for this demo
#     - ./ca-certs:/etc/pki/ca-trust/source/anchors/  ca certs are expected at this path, but are not required for this demo
      - ./auth-server-certs:/etc/pki/auth-server/source/anchors/

Adding in a Service for Corsha to Protect

Now we need to add a simple nginx proxy into the Docker compose file for the Gatekeeper to protect. Add the mock-api service code block to the bottom of your docker compose file like so.

version: "3.9"
services:
  proxy:
    environment:
      - PROXY_SECRET=< Generated via the "Generating A Proxy Secret Guide" referenced above >
    image: corsha-docker.jfrog.io/proxy:<latest version>
    ports:
      - "8080:8080"
    volumes:
      - ./proxy-config.yaml:/etc/proxy/proxy-config.yaml
#     - ./tls-certs:/etc/pki/tls/private/  tls certs are expected at this path, but are not required for this demo
#     - ./ca-certs:/etc/pki/ca-trust/source/anchors/  ca certs are expected at this path, but are not required for this demo
      - ./auth-server-certs:/etc/pki/auth-server/source/anchors/
  # ADD in the mock-api Service here!
  mock-api:
    image: nginx:1.19.10
    ports:
      - "8081:80"
    volumes:
      - ./html:/usr/share/nginx/html

Now our docker-compose.yaml file will spin up a Corsha Gatekeeper container, and an nginx service container. All that is remaining, is to configure the Gatekeeper to protect the nginx service.

Configuring the Corsha Gatekeeper

The Corsha Gatekeeper needs to be configured so it can properly check Corsha Creds. This configuration is done through a yaml file.

Create a file called proxy-config.yaml. This file will include the configuration for the Corsha Gatekeeper. See Configuration for additional information on additional parameters.

Note: domains and hosts do not contain ports or protocols. Do not include them in these parameters.

http:
  # listen address for the proxy service
  listenPort: 8080

  observeOnlyMode:
    enabled: false

  tlsTermination:
    enabled: false

  # the location of the proxied apis
  proxies:
    - name: proxy
      domain: "proxy"
      upstream:
        host: "mock-api"
        port: 80
        protocol: HTTP
# TLS certs can be configured like this but are not required for this demo
#      tls:
#        cert: /etc/pki/tls/private/cert.crt
#        key: /etc/pki/tls/private/cert.key


# The location of Corsha's auth-server. This connection is over mTLS so it requires client certs
# Please fill in the <NAMESPACE> variable.
authserver:
  host: "auth-server-<NAMESPACE>-paas-proxy-auth.corshatech.net"
  port: 443
  tls:
    cert: /etc/pki/auth-server/source/anchors/cert.crt
    key: /etc/pki/auth-server/source/anchors/cert.key

# Trusted CAs can be configured for TLS validation as follows but are not required for this demo
# trustedCAs: /etc/pki/ca-trust/source/anchors/ca-bundle.pem

Lastly, we need to add in the cert and key to ./auth-server-certs/. These proxy certs are provided to your team in your initial file bundle, and can be reacquired by contacting your Corsha TPOC. With these certs, the Gatekeeper can now establish a connection to the auth-server over Mutual TLS (mTLS).

Configuring the Mock API service

The mock api service also needs configured before it starts responding to requests. Add a file that provides the following response data for our protected service to html/data.json.

{
    "message": "Hello, World!"
}

Running the Demo

Now we are ready to make a call to the mock api service through the Gatekeeper. Open a terminal in the directory for the docker-compose.yaml file and run the following command:

docker compose up

After the services come up, we will make a request without the X-Corsha-Cred header to show that access to the mock nginx service is denied.

curl -H "Host:proxy" -v "http://localhost:8080/data.json"

*   Trying 127.0.0.1:8080...
* Connected to localhost (127.0.0.1) port 8080 (#0)
> GET /data.json HTTP/1.1
> Host:api
> User-Agent: curl/8.1.2
> Accept: */*
>
< HTTP/1.1 403 Forbidden
< server: envoy
< date: Wed, 01 Nov 2023 18:44:17 GMT
< content-type: application/json
< content-length: 86
< x-envoy-upstream-service-time: 222
<
* Connection #0 to host localhost left intact
{"error":"Error 4105: Cred Not Valid","code":7,"message":"Error 4105: Cred Not Valid"}%

Next Steps

Next, we will make a request with a Corsha Cred. You will need to outfit your API clients with Corsha Authenticators using the guide: Adding an Authenticator to API Clients.

Creating your Filesystem​

Creating a Default Docker Compose File with Corsha​

Adding in a Service for Corsha to Protect​

Configuring the Corsha Gatekeeper​

Configuring the Mock API service​

Running the Demo​

Next Steps​