secure-access-configure-ssl-for-an-api

Overview

In the previous sections, you Installed Kong Using Docker Compose, Provisioned, Protected and Rate Limited your API, and looked at various Configuration Files.

In this section, you will secure access to your Kong Environment and your APIs.

Screen Shot 2017 08 10 At 11.37.29 Am

Scenario: Secure Access

Security is one of your top priorities. In a Kong environment, there are numerous access points you want to secure. These include:

  1. Kong Admin API
  2. Client to Kong
  3. Kong to Upstream API
  4. Kong to DB

In this exercise, you will configure SSL for an API (Scenario 2). Clients/Consumers will access the API endpoint over SSL. Kong will proxy the SSL request to the API Endpoint.

High Level Tasks

  1. Create a Cert and Key (Instructions here)
  2. Upload your Certificate and Key via Admin API
  3. Provision API in Kong
  4. Verify over HTTPs The API is served over HTTPs by Kong
  5. Optional- HTTPS only: Configure the API to only be served through HTTPS and not HTTP.

Detail Configurations

1. Create a Certificate and Key

If you haven’t created one yet find Instructions Here

2. Upload your Certificate and Key via Admin API

Once you have the Cert/Key, upload it using the Admin API.

$ curl -i -X POST http://localhost:8001/certificates \
-F "cert=@/<path_to_cert_folder>/server.crt" \
-F "key=@/<path_to_cert_folder>/server.key" \
-F "snis=sslmockbin.org,mockbin.org"

Note: You will use Mockbin as your API endpoint. This is for testing purposes. In your environment, you should use your API endpoint URL.

You should receive a response HTTP 201 Created

HTTP/1.1 201 Created
Date: Wed, 09 Aug 2017 11:12:54 GMT
Content-Type: application/json; charset=utf-8
Transfer-Encoding: chunked
Connection: keep-alive
Access-Control-Allow-Origin: *
Server: kong/0.11.0

{"cert":"-----BEGIN CERTIFICATE-----\nMIIDdDCCAlwCCQCOOJ\/LMV8ICTANBgkqhkiG9w0BAQsFADB8MQswCQYDVQQGEwJV\nUzELMAkGA1UECBMCQ0ExCzAJBgNVBAcTAlNGMQ0wCwYDVQQKEwRLb25nMREwDwYD\nVQQLEwhUcmFpbmluZzEQMA4GA1UEAxMHU2ltcGxydTEfMB0GCSqGSIb3DQEJARYQ\ndmlldEBzaW1wbHJ1LmNvbTAeFw0xNzA3MzExNTI0NDRaFw0xNzA4MzAxNTI0NDRa\nMHwxCzAJBgNVBAYTAlVTMQswCQYDVQQIEwJDQTELMAkGA1UEBxMCU0YxDTALBgNV\nBAoTBEtvbmcxETAPBgNVBAsTCFRyYWluaW5nMRAwDgYDVQQDEwdTaW1wbHJ1MR

3. Provision API in Kong

Provision your API in Kong as normal.

$ curl -i -X POST http://localhost:8001/apis \
-d "name=ssl-demo" \
-d "upstream_url=http://mockbin.org/requests" \
-d "hosts=sslmockbin.org,mockbin.org"

4. Verify API Access Over HTTPs

You can now expect the API to be served over HTTPs by Kong

Send a request to the host via HTTPs.

$ curl -i https://localhost:8443/ \
-H "Host: sslmockbin.org"

Response

curl: (60) SSL certificate problem: Invalid certificate chain
More details here: https://curl.haxx.se/docs/sslcerts.html
curl performs SSL certificate verification by default, using a "bundle"
 of Certificate Authority (CA) public keys (CA certs). If the default
 bundle file isn't adequate, you can specify an alternate file
 using the --cacert option.
If this HTTPS server uses a certificate signed by a CA represented in
 the bundle, the certificate verification probably failed due to a
 problem with the certificate (it might be expired, or the name might
 not match the domain name in the URL).
If you'd like to turn off curl's verification of the certificate, use
 the -k (or --insecure) option.

Error Message: You will get an error message on the certificate you created. Specifically: “SSL certificate problem: Invalid certificate chain”. This is due to the certificate you created.

Option -K

Lets add the -k option to the request to bypass this error message.

Important Note:This is for testing purpose to verify that you’ve

  • uploaded the certificate correctly
  • provisioned your API for HTTPS
  • and that Kong is serving your request over HTTPs.

In an actual environment, make sure that the Certificate/Key is created correctly with any Certificate Chains, and Hostnames/SNIs that match

$ curl -i https://localhost:8443/ \
-H "Host: sslmockbin.org" -k

Response: You should recieve an HTTP 200 OK response now:

HTTP/1.1 200 OK
Date: Thu, 03 Oct 2017 11:10:04 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 934
Connection: keep-alive
Set-Cookie: __cfduid=d3b757a11d53234615e0311e8b954640a1501758604; expires=Fri, 03-Oct-18 11:10:04 GMT; path=/; domain=.mockbin.org; HttpOnly
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET
Access-Control-Allow-Headers: host,connection,accept-encoding,x-forwarded-for,cf-ray,x-forwarded-proto,cf-visitor,user-agent,accept,cf-connecting-ip,x-request-id,x-forwarded-port,via,connect-time,x-request-start,total-route-time
Access-Control-Allow-Credentials: true
X-Powered-By: mockbin
Vary: Accept, Accept-Encoding
Etag: W/"3a6-Hm/jbhrgHjZi6z/FRBgjqg"
Via: kong/0.11.0
Server: cloudflare-nginx
CF-RAY: 3888d40e91874e24-DME
X-Kong-Upstream-Latency: 405
X-Kong-Proxy-Latency: 52

{

The response is an HTTP 200. This confirms that your HTTPs request is being proxied by Kong to the API endpoint.

Great! You have configure SSL for an API endpoint.

This API is now accessible via HTTP or HTTPS. If you want to only allow for HTTPs you can specify the HTTPs_Only parameter on the API.

5. Optional- HTTPS Only

If you want the API to only be served over HTTPS, you can do so by enabling its https_only property:

An example of this configuration is O-Auth plugin.. It requires access over HTTPs only.

Important Note: As of Kong version 0.11.0 - The API Object property http_if_terminated is now set to false by default. For Kong to evaluate the client X-Forwarded-Proto header, you must now configure Kong to trust the client IP and you must explicitly set this value to true. This affects you if you are doing SSL termination somewhere before your requests hit Kong, and if you have configured https_only on the API, or if you use a plugin that requires HTTPS traffic (e.g. OAuth2).

Modify HTTPs_Only parameter for the API

$ http patch :8001/apis/ssl-demo \
https_only=true

Request access via HTTP

$ http get :8000 host:sslmockbin.org

Response:

C02M90TWF6T6:~ vietp$ http get :8000 host:mockbin.org
		HTTP/1.1 426
		Connection: keep-alive
		Content-Type: application/json; charset=utf-8
		Date: Mon, 31 Oct 2017 16:04:04 GMT
		Server: kong/0.11.0
		Transfer-Encoding: chunked
		connection: Upgrade
		upgrade: TLS/1.2, HTTP/1.1
			{
	    		"message": "Please use HTTPS protocol"
			}

Notice the messsage: “Please use HTTPS protocol”

Request access via HTTPS

Now lets access the API over SSL

$ curl -i https://localhost:8443/ \
-H "Host: sslmockbin.org" -k

Response: You should recieve an HTTP 200 OK response now:

HTTP/1.1 200 OK
Date: Thu, 03 Oct 2017 11:10:04 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 934
Connection: keep-alive
Set-Cookie: __cfduid=d3b757a11d53234615e0311e8b954640a1501758604; expires=Fri, 03-Oct-18 11:10:04 GMT; path=/; domain=.mockbin.org; HttpOnly
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET
Access-Control-Allow-Headers: host,connection,accept-encoding,x-forwarded-for,cf-ray,x-forwarded-proto,cf-visitor,user-agent,accept,cf-connecting-ip,x-request-id,x-forwarded-port,via,connect-time,x-request-start,total-route-time
Access-Control-Allow-Credentials: true
X-Powered-By: mockbin
Vary: Accept, Accept-Encoding
Etag: W/"3a6-Hm/jbhrgHjZi6z/FRBgjqg"
Via: kong/0.11.0
Server: cloudflare-nginx
CF-RAY: 3888d40e91874e24-DME
X-Kong-Upstream-Latency: 405
X-Kong-Proxy-Latency: 52

{

Summary

You configured SSL for an API endpoint and optionally over HTTPs only. The tasked performed were as follows:

High Level Tasks

  1. Create a Cert and Key
  2. Upload your Certificate and Key via Admin API
  3. Provision API in Kong
  4. Verify over HTTPs You can now expect the API to be served over HTTPs by Kong:
  5. Optional- HTTPS only: If you wish an API to only be served through HTTPS, you can do so by enabling its https_only property:

What Next

You can also secure access to the ADMIN API Loopback Address, Kong to the Upstream API, and Kong to Database. These are bonus exercises where High level Task are provided (detail configurations - coming soon). Give these these try if time permits.

Otherwise, lets configure Kong High Availabilty and Redundancy.

Load Balance Incoming Request with Kong Ring Balancer - Round Robin

Bonus Exercises - Optional

Secure Access: Configure Admin API Lookback with SSL
Secure Access: Configure Database for SSL

Edit this page