Get Started With Tyk API Gateway
Tyk offers various products to manage APIs and services. The heart of its product palette is its open-source API Gateway. It is completely developed in Go and can serve as a proxy for REST, GraphQL, and other services. This guide describes how to run the API Gateway with Docker.
What You’ll Need
- Docker
- A REST client — I’ll use HTTPie in my examples, but any client works
Run Tyk Gateway With Docker
To get Tyk Gateway up and running you need to run Redis and, of course, Tyk Gateway itself. Follow the below instructions to get everything working.
1. Configure a Network
$ docker network create tyk2. Pull and Run Redis
I’m using Redis 5.0.10 instead of the latest version because this is the latest supported version according to the Tyk docs. Please note, that running Redis like this is not the preferred way for production environments. There Redis should be highly available and deployed as a cluster.
$ docker pull redis:5.0.10
$ docker run -itd --rm --name redis --network tyk -p 6379:6379 redis:5.0.103. Create Tyk Configuration
Create a new directory, which will hold your configuration and API definitions. Additionally, create a new file that contains the following JSON. I’d suggest tyk.conf as the name for this file. As we are using the Tyk API Gateway without any other (enterprise) products, this config is based on the tyk.standalone.conf in this repository. I removed some attributes, that isn’t important for now. The most important change I made is removing the secret as we will set this via an environment variable to not expose it in the configuration.
Most values are quite self-explanatory. Head over to Tyk’s documentation to learn more about them.
4. Pull and Run Tyk Gateway
Now it‘s time to run the API Gateway. Execute the below-printed commands to pull the Docker image for the API Gateway and to run it.
$ docker pull tykio/tyk-gateway:latest
$ docker run -d \
--name tyk_gateway \
--network tyk \
-p 8080:8080 \
-e TYK_GW_SECRET=[YOUR-SECRET] \
-v $(pwd)/tyk.conf:/opt/tyk-gateway/tyk.conf \
-v $(pwd)/apps:/opt/tyk-gateway/apps \
tykio/tyk-gateway:latestBelow the arguments of the run command is explained:
--name tyk_gateway: Sets the name of the container.--network tyk: Connects the container to the networktyk.-p 8080:8080: Exposes port 8080 of the container to port 8080 of your system.-e TYK_GW_SECRET=[YOUR-SECRET]: Sets the environment variable that holds your secret.-v $(pwd)/tyk.conf:/opt/tyk-gateway/tyk.conf: Bind mounts the configuration we created in the previous step to the configuration file inside the container.-v $(pwd)/apps:/opt/tyk-gateway/apps: Bind mounts the app directory in our current folder to the directoryopt/tyk-gateway/appsinside the container.
5. Verify Everything Is Set Up Correctly
To verify that the API Gateway is up and running, you can simply send a GET request to /hello. The answer should look similar to the below printed JSON.
Edit Tyk’s Configuration
Editing your configuration is quite easy. As we created a bind mount for the configuration, you can simply edit the configuration file we created earlier to make config changes.
NOTE: Vim doesn’t save a file directly, but creates a new file and copies it into place. Therefore the inode of the file is being changed and saving the file breaks the bind mount. To avoid this, you need to set
set backupcopy=yesin vim. If you want to make this setting permanent, you need to add it to the file~/.vimrc. If this file doesn’t exist, you can simply create it and vim will take notice of it.
Now all that’s left to do is reloading the API Gateway. This can be achieved with a GET call to /tyk/reload.
Add an API
Now, that the API Gateway is up and running, it’s time to add an API to it. You can either add an API by making a request to the REST API of the API Gateway or by adding the API definition to the folder /opt/tyk-gateway/apps, which we mounted to the ./apps directory earlier. I’ll use the second option in this guide, as I prefer to have configurable files. If you opt for the first possibility you can simply send a POST request to /tyk/apis that contains the API definition in its body. Please don’t forget to set the x-tyk-authorization header in this request.
We’ll add an API that is available at /httpbin and proxies requests to https://httpbin.org. The minimal configuration for this API can be found in the below Gist. Again, a description of all attributes can be found in Tyk’s documentation.
Navigate to the ./apps directory Docker created for you and create a new file httpbin.json that contains the above-shown JSON.
The last step, to add a new endpoint, is to reload the API Gateway with the following request.
$ http :8080/tyk/reload 'x-tyk-authorization:[YOUR-SECRET]'That’s it. As you can see in the Gist below, requests to localhost:8080/httpbin are proxied to httpbin.org now.
Authentication With Tyk
There are several ways to implement authentication for APIs. Tyk supports the following methods to authenticate. Since Tyk version 2.3, it’s also possible to chain authentication middleware.
- Basic Authentication
- Bearer Token
- HMAC Request Signing
- JSON Web Token
- OpenID Connect
Tyk also provides support for OAuth 2.0 and can even serve as a provider for authorization and access tokens.
As this guide aims to get you started with Tyk, this section doesn’t cover all authentication and authorization methods. To provide a rough understanding of how authentication works, Bearer Token and Basic Authentication are explained in the next subsections.
Bearer Token
Bearer Token authentication is the default way of securing APIs with Tyk. In the definition of the API we added earlier, we set the use_keyless attribute to true to expose the API without authentication. Below you can see an API definition, with Bearer Token authentication. It is very similar to the definition we used above. The values for name, listen_path, and id changed and use_keyless has been removed.
If you reload your API Gateway, requests to /httpbin are still working as before, because they belong to the previously created API. If you make a request to /httpbin/bearer the API Gateway will return 401 Unauthorized, with the error Authorization field missing. After setting the Authorization header to any value (we’ll issue a token in a second), the gateway will return 403 Forbidden — Access to this API has been disallowed.
The API is ready now, therefore we need to issue a token to access it. To do so, we need to define a session object. Below a minimal definition is shown. It grants access to the API with ID 2 (the one we just created) in organization 1. With a session object like the one below, you can configure lots of things. Check out the official documentation to learn more about that.
Now send the session object with a POST request to /tyk/keys to issue an authentication token.
Your token is contained in the key field of the response. It needs to be sent in the Authorization header of all requests to /httpbin/bearer.
Basic Authentication
To configure Basic Authentication we will create a new API. The definition looks similar to the ones you already know, but name, id, and listen_path changed. The most important change is that the field use_basic_auth is added and set to true. This tells Tyk to secure this endpoint with Basic Auth instead of Bearer Tokens. You don’t need to configure anything else, as Tyk knows how to handle the Basic Auth standard.
After reloading the API Gateway, requests to httpbin/basic will fail if no or an invalid user is passed. To create a new user, we need to create a session token. You can see the configuration for this token in the snippet below. Again, the definition is very similar to the one we used to issue a Bearer Token. Of course name and id of the API changed, as we want to create a user for API 3 now. Further, the password of the user was added within basic_auth_data.
Now everything is ready to publish the user to the API Gateway with a POST request to /tyk/keys/[USERNAME]. The following snippet shows how to create a new user with the name a-user.
Now you can make requests with the newly created credentials.
Conclusion
Within this introduction, we covered how to get the Tyk API Gateway up and running with Docker and how to define basic APIs and simple authentication mechanisms.
That’s it. Thanks a lot for reading this article! I hope it helps you to get into the Tyk API Gateway.
