diff --git a/app/_data/docs_nav_gateway_3.0.x.yml b/app/_data/docs_nav_gateway_3.0.x.yml index c081e66c53e5..a24614cbd7c3 100644 --- a/app/_data/docs_nav_gateway_3.0.x.yml +++ b/app/_data/docs_nav_gateway_3.0.x.yml @@ -57,7 +57,7 @@ items: - text: Proxy Caching url: /get-started/proxy-caching - text: Key Authentication - url: /get-started/secure-services + url: /get-started/key-authentication - text: Load-Balancing url: /get-started/load-balancing - title: Kong in Production diff --git a/app/moved_urls.yml b/app/moved_urls.yml index 2b59337c0466..481e6bfb39b1 100644 --- a/app/moved_urls.yml +++ b/app/moved_urls.yml @@ -1,8 +1,6 @@ --- /gateway-oss/VERSION/configuration/: "/gateway/VERSION/reference/configuration/" /gateway/VERSION/get-started/configure-services-and-routes/: "/gateway/VERSION/get-started/services-and-routes/" - - /gateway/VERSION/install-and-run/kubernetes/: "/gateway/VERSION/install/kubernetes/kubectl/" /gateway/VERSION/install-and-run/helm/: "/gateway/VERSION/install/kubernetes/helm/" /gateway/VERSION/install-and-run/openshift/: "/gateway/VERSION/install/kubernetes/openshift/" @@ -151,19 +149,4 @@ /gateway/VERSION/pdk/kong.vault/: "/gateway/VERSION/plugin-development/pdk/kong.vault/" /gateway/VERSION/plugin-development/plugin-configuration/: "/gateway/VERSION/plugin-development/configuration/" /gateway/VERSION/reference/external-plugins/: "/gateway/VERSION/plugin-development/pluginserver/go/" - - - - - - - - - - - - - - - - +/gateway/VERSION/get-started/secure-services/: "/gateway/VERSION/get-started/key-authentication/" diff --git a/src/gateway/get-started/key-authentication.md b/src/gateway/get-started/key-authentication.md new file mode 100644 index 000000000000..9f0d6a45ddfc --- /dev/null +++ b/src/gateway/get-started/key-authentication.md @@ -0,0 +1,223 @@ +--- +title: Key Authentication +content-type: tutorial +book: get-started +chapter: 5 +--- + +Authentication is the process of verifying that a requester has permissions to access a resource. +As it's name implies, API gateway authentication authenticates the flow of data to and from your upstream services. + +{{site.base_gateway}} has a library of plugins that support +the most widely used [methods of API gateway authentication](/hub/#authentication). + +Common authentication methods include: +* Key Authentication +* Basic Authentication +* OAuth 2.0 Authentication +* LDAP Authentication Advanced +* OpenID Connect + +## Authentication benefits + +With {{site.base_gateway}} controlling authentication, requests won't reach upstream services unless the client has successfully +authenticated. This means upstream services process pre-authorized requests, freeing them from the +cost of authentication, which is a savings in compute time *and* development effort. + +{{site.base_gateway}} has visibility into all authentication attempts, which provides the ability to build +monitoring and alerting capabilities supporting service availability and compliance. + +For more information, see [What is API Gateway Authentication?](https://konghq.com/learning-center/api-gateway/api-gateway-authentication). + +## Enable authentication + +The following tutorial walks through how to enable the [Key Authentication plugin](/hub/kong-inc/key-auth/) across +various aspects in {{site.base_gateway}}. + +API key authentication is a popular method for enforcing API authentication. In key authentication, +{{site.base_gateway}} is used to generate and associate an API key with a [consumer](/gateway/latest/admin-api/#consumer-object). +That key is the authentication secret presented by the client when making subsequent requests. {{site.base_gateway}} approves or +denies requests based on the validity of the presented key. This process can be applied globally or to individual +[services](/gateway/latest/key-concepts/services/) and [routes](/gateway/latest/key-concepts/routes/). + +### Prerequisites + +This chapter is part of the *Get Started with Kong* series. For the best experience, it is recommended that you follow the +series from the beginning. + +Start with the introduction, [Get Kong](/gateway/latest/get-started/get-kong), which includes +tool prerequisites and instructions for running a local {{site.base_gateway}}. + +Step two of the guide, [Services and Routes](/gateway/latest/get-started/services-and-routes), +includes instructions for installing a mock service used throughout this series. + +If you haven't completed these steps already, complete them before proceeding. + +### Set up consumers and keys + +Key authentication in {{site.base_gateway}} works by using the consumer object. Keys are assigned to +consumers, and client applications present the key within the requests they make. + +1. **Create a new consumer** + + For the purposes of this tutorial, create a new consumer with a username `luka`: + + ```sh + curl -i -X POST http://localhost:8001/consumers/ \ + --data username=luka + ``` + + You will receive a `201` response indicating the consumer was created. + +1. **Assign the consumer a key** + + Once provisioned, call the Admin API to assign a key for the new consumer. + For this tutorial, set the key value to `top-secret-key`: + + ```sh + curl -i -X POST http://localhost:8001/consumers/luka/key-auth \ + --data key=top-secret-key + ``` + + You will receive a `201` response indicating the key was created. + + In this example, you have explicitly set the key contents to `top-secret-key`. + If you do not provide the `key` field, {{site.base_gateway}} will generate the key value for you. + + {:.important} + > **Warning**: For the purposes of this tutorial, we have assigned an example key value. It is recommended that you let the + API gateway autogenerate a complex key for you. Only specify a key for testing or when migrating existing systems. + + +### Global key authentication + +Installing the plugin globally means *every* proxy request to {{site.base_gateway}} is protected by key authentication. + +1. **Enable key authentication** + + The Key Authentication plugin is installed by default on {{site.base_gateway}} and can be enabled + by sending a `POST` request to the plugins object on the Admin API: + + ```sh + curl -X POST http://localhost:8001/plugins/ \ + --data "name=key-auth" \ + --data "config.key_names=apikey" + ``` + + You will receive a `201` response indicating the plugin was installed. + + The `key_names` configuration field in the above request defines the name of the field that the + plugin looks for to read the key when authenticating requests. The plugin looks for the field in headers, + query string parameters, and the request body. + +1. **Send an unauthenticated request** + + Try to access the service without providing the key: + + ```sh + curl -i http://localhost:8000/mock/request + ``` + + Since you enabled key authentication globally, you will receive an unauthorized response: + + ```text + HTTP/1.1 401 Unauthorized + ... + { + "message": "No API key found in request" + } + ``` + +1. **Send the wrong key** + + Try to access the service with the wrong key: + + ```sh + curl -i http://localhost:8000/mock/request \ + -H 'apikey:bad-key' + ``` + + You will receive an unauthorized response: + + ```text + HTTP/1.1 401 Unauthorized + ... + { + "message":"Invalid authentication credentials" + } + ``` + +1. **Send a valid request** + + Send a request with the valid key in the `apikey` header: + + ```sh + curl -i http://localhost:8000/mock/request \ + -H 'apikey:top-secret-key' + ``` + + You will receive a `200 OK` response. + +### Service based key authentication + +The Key Authentication plugin can be enabled for specific services. The request is the same as above, but the `POST` request is sent +to the service URL: + + ```sh + curl -X POST http://localhost:8001/services/example_service/plugins \ + --data name=key-auth + ``` +### Route based key authentication + +The Key Authentication plugin can be enabled for specific routes. The request is the same as above, but the `POST` request is sent to the route URL: + + ```sh + curl -X POST http://localhost:8001/routes/example_route/plugins \ + --data name=key-auth + ``` + +## (Optional) Disable the plugin + +If you are following this getting started guide section by section, you will need to use this API key +in any requests going forward. If you don’t want to keep specifying the key, disable the plugin before moving on. + + +1. **Find the Key Authentication plugin ID** + + ```sh + curl -X GET http://localhost:8001/plugins/ + ``` + + You will receive a JSON response that contains the `id` field, similar to the following snippet: + + ```text + ... + "id": "2512e48d9-7by0-674c-84b7-00606792f96b" + ... + ``` + +1. **Disable the plugin** + + Use the plugin ID obtained above to `PATCH` the `enabled` field on the + installed Key Authentication plugin. Your request will look similar to this, + substituting the proper plugin ID: + + ```sh + curl -X PATCH http://localhost:8001/plugins/2512e48d9-7by0-674c-84b7-00606792f96b \ + --data enabled=false + ``` + +1. **Test disabled authentication** + + Now you can make a request without providing an API key: + + ```sh + curl -i http://localhost:8000/mock/request + ``` + + You should receive: + + ```text + HTTP/1.1 200 OK + ``` + diff --git a/src/gateway/get-started/secure-services.md b/src/gateway/get-started/secure-services.md deleted file mode 100644 index 22e3d47953ff..000000000000 --- a/src/gateway/get-started/secure-services.md +++ /dev/null @@ -1,153 +0,0 @@ ---- -title: Configure key authentication ---- -In this topic, you’ll learn about API Gateway authentication, set up the Key Authentication plugin, and add a consumer. - -If you are following the getting started workflow, make sure you have completed [Improve Performance with Proxy Caching](/gateway/{{page.kong_version}}/get-started/comprehensive/improve-performance) before moving on. - -## What is Authentication? - -API gateway authentication is an important way to control the data that is allowed to be transmitted using your APIs. Basically, it checks that a particular consumer has permission to access the API, using a predefined set of credentials. - -{{site.base_gateway}} has a library of plugins that provide simple ways to implement the best known and most widely used [methods of API gateway authentication](/hub/#authentication). Here are some of the commonly used ones: - -* Basic Authentication -* Key Authentication -* OAuth 2.0 Authentication -* LDAP Authentication Advanced -* OpenID Connect - -Authentication plugins can be configured to apply to service entities within the {{site.base_gateway}}. In turn, service entities are mapped one-to-one with the upstream services they represent, essentially meaning that the authentication plugins apply directly to those upstream services. - -## Why use API Gateway Authentication? - -With authentication turned on, {{site.base_gateway}} won’t proxy requests unless the client successfully authenticates first. This means that the upstream (API) doesn’t need to authenticate client requests, and it doesn’t waste critical resources validating credentials. - -{{site.base_gateway}} has visibility into all authentication attempts, successful, failed, and so on, which provides the ability to catalog and dashboard those events to prove the right controls are in place, and to achieve compliance. Authentication also gives you an opportunity to determine how a failed request is handled. This might mean simply blocking the request and returning an error code, or in some circumstances, you might still want to provide limited access. - -In this example, you’re going to enable the **Key Authentication plugin**. API key authentication is one of the most popular ways to conduct API authentication and can be implemented to create and delete access keys as required. - -For more information, see [What is API Gateway Authentication?](https://konghq.com/learning-center/api-gateway/api-gateway-authentication). - -## Set up the Key Authentication Plugin - -Call the Admin API on port `8001` and configure plugins to enable key -authentication. For this example, apply the plugin to the */mock* route you -created: - - -```sh -curl -X POST http://localhost:8001/routes/mocking/plugins \ - --data name=key-auth -``` - -Try to access the service again: - -```sh -curl -i http://localhost:8000/mock -``` - - - -Since you added key authentication, you should be unable to access it: - -```sh -HTTP/1.1 401 Unauthorized -... -{ - "message": "No API key found in request" -} -``` - -Before Kong proxies requests for this route, it needs an API key. For this -example, since you installed the Key Authentication plugin, you need to create -a consumer with an associated key first. - - -## Set up Consumers and Credentials - - -To create a consumer, call the Admin API and the consumer’s endpoint. -The following creates a new consumer called **consumer**: - - - -```sh -curl -i -X POST http://localhost:8001/consumers/ \ - --data username=consumer \ - --data custom_id=consumer -``` - - -Once provisioned, call the Admin API to provision a key for the consumer -created above. For this example, set the key to `apikey`. - - - -```sh -curl -i -X POST http://localhost:8001/consumers/consumer/key-auth \ - --data key=apikey -``` - - -If no key is entered, Kong automatically generates the key. - -Result: - -```sh -HTTP/1.1 201 Created -... -{ - "consumer": { - "id": "2c43c08b-ba6d-444a-8687-3394bb215350" - }, - "created_at": 1568255693, - "id": "86d283dd-27ee-473c-9a1d-a567c6a76d8e", - "key": "apikey" -} -``` - -You now have a consumer with an API key provisioned to access the route. - -## Validate Key Authentication - -To validate the Key Authentication plugin, access the *mocking* route again, using the header `apikey` with a key value of `apikey`. - -```sh -curl -i http://localhost:8000/mock/request \ - -H 'apikey:apikey' -``` -You should get an `HTTP/1.1 200 OK` message in response. - -## (Optional) Disable the plugin -If you are following this getting started guide topic by topic, you will need to use this API key in any requests going forward. If you don’t want to keep specifying the key, disable the plugin before moving on. - - -Find the plugin ID and copy it: - -```sh -curl -X GET http://localhost:8001/routes/mocking/plugins/ -``` - - -Output: -```sh -"id": "2512e48d9-7by0-674c-84b7-00606792f96b" -``` - -Disable the plugin: - -```sh -curl -X PATCH http://localhost:8001/routes/mocking/plugins/{} \ - --data enabled=false -``` - -## Summary and next steps - -In this topic, you: - -* Enabled the Key Authentication plugin. -* Created a new consumer named `consumer`. -* Gave the consumer an API key of `apikey` so that it could access the `/mock` route with authentication. - -Next, you’ll learn about [load balancing upstream services using targets](/gateway/{{page.kong_version}}/get-started/comprehensive/load-balancing).