From 807eba5fbda289d311771caddde73336d20c2fc0 Mon Sep 17 00:00:00 2001 From: Joshua Schmid Date: Thu, 11 Jul 2024 14:09:49 +0200 Subject: [PATCH 1/3] feat: add support for externalized consumers --- app/_hub/kong-inc/key-auth/overview/_index.md | 74 ++++++++++++++++++- 1 file changed, 71 insertions(+), 3 deletions(-) diff --git a/app/_hub/kong-inc/key-auth/overview/_index.md b/app/_hub/kong-inc/key-auth/overview/_index.md index 8eaae8b0730a..90a32d124916 100644 --- a/app/_hub/kong-inc/key-auth/overview/_index.md +++ b/app/_hub/kong-inc/key-auth/overview/_index.md @@ -77,9 +77,9 @@ For more information about how to configure anonymous access, see [Anonymous Acc ### Create a Key {:.important} -> **Note**: We recommend letting the API gateway autogenerate the key. Only specify it -yourself if you are migrating an existing system to {{site.base_gateway}}. -You must reuse your keys to make the migration to {{site.base_gateway}} transparent +> **Note**: We recommend letting the API gateway autogenerate the key. Only specify it +yourself if you are migrating an existing system to {{site.base_gateway}}. +You must reuse your keys to make the migration to {{site.base_gateway}} transparent to your consumers. {% navtabs %} @@ -303,3 +303,71 @@ No API key is provided. | No | 401 The API key is known to {{site.base_gateway}} | No | 401 A runtime error occurred. | No | 500 + +### Externalized Consumers + +-- Dummy/Link that points to Konnect Docs when ready. + +With the `pool_id` you obtained from the previous step, you can configure the key-auth plugin to validate API keys against the Identity Service. + +#### Configuring Multiple Pools + +In the key-auth plugin configuration, add the `pools` option as shown below: + +```yaml +pools: + - geo: us + id: + type: remote + - geo: null + id: null + type: local +``` + +The order in which you configure the pools dictates the priority in which the dataplane attempts to authenticate the provided API keys. + +In the example above, if the remote pool is listed first, the dataplane will first reach out to the identity service and, if necessary, subsequently to the local pool. + +Alternatively, you can configure the local pool first: + +```yaml +pools: + - geo: null + id: null + type: local + - geo: us + id: + type: remote +``` + +In this configuration, the dataplane will initially check the local pool (LMDB) before querying the remote Identity Service. + +If a matching key is found in any of these pools, the request will be authenticated. If the key is not found in any of the configured pools, the request will be blocked. + +#### Configuring Single Pools + +It is also possible to configure only a single pool, either local or remote. However, only one of each type can be configured. + +To configure only a remote pool: + +```yaml +pools: + - geo: us + id: + type: remote +``` + +In this case, the dataplane will only attempt to authenticate API keys against the remote Identity Service. + +To configure only a local pool: + +```yaml +pools: + - geo: null + id: null + type: local +``` + +In this scenario, the dataplane will only check the local pool (LMDB) for API key authentication. + +In both cases, if the API key is not found in the configured pool, the request will be blocked. From a89ecfc782873c1bdb341811289fae41c8f89f54 Mon Sep 17 00:00:00 2001 From: Angel Date: Mon, 19 Aug 2024 14:19:27 -0400 Subject: [PATCH 2/3] start restructuring information on this page --- app/_hub/kong-inc/key-auth/overview/_index.md | 47 +++++++++---------- 1 file changed, 22 insertions(+), 25 deletions(-) diff --git a/app/_hub/kong-inc/key-auth/overview/_index.md b/app/_hub/kong-inc/key-auth/overview/_index.md index b257ed69b0af..34a7ce051869 100644 --- a/app/_hub/kong-inc/key-auth/overview/_index.md +++ b/app/_hub/kong-inc/key-auth/overview/_index.md @@ -25,11 +25,26 @@ To restrict usage to certain authenticated users, also add the [ACL](/plugins/acl/) plugin (not covered here) and create allowed or denied groups of users. +## Upstream Headers + +{% include_cached /md/plugins-hub/upstream-headers.md %} + +### Request behavior matrix + +The following table describes how {{site.base_gateway}} behaves in various authentication scenarios: + +Description | Proxied to upstream service? | Response status code +--------|-----------------------------|--------------------- +The request has a valid API key. | Yes | 200 +No API key is provided. | No | 401 +The API key is not known to {{site.base_gateway}} | No | 401 +A runtime error occurred. | No | 500 + ## Usage ### Create a Consumer -You need to associate a credential to an existing [Consumer][consumer-object] object. +You need to associate a credential to an existing [Consumer](/gateway/latest/key-concepts/consumers/) object. A Consumer can have many credentials. {% navtabs %} @@ -69,13 +84,10 @@ service, you must add the new Consumer to the allowed group. See For more information about how to configure anonymous access, see [Anonymous Access](/gateway/latest/kong-plugins/authentication/reference/#anonymous-access). - -### Multiple Authentication +### Create a Key {{site.base_gateway}} supports multiple authentication plugins for a given service, allowing different clients to use different authentication methods to access a given service or route. For more information, see [Multiple Authentication](/gateway/latest/kong-plugins/authentication/reference/#multiple-authentication). -### Create a Key - {:.important} > **Note**: We recommend letting the API gateway autogenerate the key. Only specify it yourself if you are migrating an existing system to {{site.base_gateway}}. @@ -167,7 +179,7 @@ gRPC clients are supported too: grpcurl -H 'apikey: {some_key}' ... ``` -### About API Key Locations in a Request +### API Key Locations in a Request {% include /md/plugins-hub/api-key-locations.md %} @@ -199,11 +211,7 @@ HTTP/1.1 204 No Content * `USERNAME_OR_ID`: The `id` or `username` property of the [Consumer][consumer-object] entity to associate the credentials to. * `ID`: The `id` attribute of the key credential object. -### Upstream Headers - -{% include_cached /md/plugins-hub/upstream-headers.md %} - -### Paginate through keys +### Pagination Paginate through the API keys for all Consumers by making the following request: @@ -292,25 +300,14 @@ Response: [acl-associating]: /plugins/acl/#associating-consumers -### Request behavior matrix - -The following table describes how {{site.base_gateway}} behaves in various scenarios: - -Description | Proxied to upstream service? | Response status code ---------|-----------------------------|--------------------- -The request has a valid API key. | Yes | 200 -No API key is provided. | No | 401 -The API key is not known to {{site.base_gateway}} | No | 401 -A runtime error occurred. | No | 500 - -### Externalized Consumers +## Externalized Consumers -- Dummy/Link that points to Konnect Docs when ready. With the `pool_id` you obtained from the previous step, you can configure the key-auth plugin to validate API keys against the Identity Service. -#### Configuring Multiple Pools +### Configuring Multiple Pools In the key-auth plugin configuration, add the `pools` option as shown below: @@ -344,7 +341,7 @@ In this configuration, the dataplane will initially check the local pool (LMDB) If a matching key is found in any of these pools, the request will be authenticated. If the key is not found in any of the configured pools, the request will be blocked. -#### Configuring Single Pools +### Configuring Single Pools It is also possible to configure only a single pool, either local or remote. However, only one of each type can be configured. From ac821afa842886287c3a458c30e58705869b7c28 Mon Sep 17 00:00:00 2001 From: Angel Date: Wed, 21 Aug 2024 15:35:36 -0400 Subject: [PATCH 3/3] split out pool info into its own doc --- app/_hub/kong-inc/key-auth/how-to/_index.md | 71 +++++++++++++++++++ app/_hub/kong-inc/key-auth/overview/_index.md | 68 ------------------ 2 files changed, 71 insertions(+), 68 deletions(-) create mode 100644 app/_hub/kong-inc/key-auth/how-to/_index.md diff --git a/app/_hub/kong-inc/key-auth/how-to/_index.md b/app/_hub/kong-inc/key-auth/how-to/_index.md new file mode 100644 index 000000000000..0e6042e44b8a --- /dev/null +++ b/app/_hub/kong-inc/key-auth/how-to/_index.md @@ -0,0 +1,71 @@ +--- +nav_title: +title: How to configure pools + +minimum_version: 3.8.x +--- + + +With `pool_id` you can configure the key-auth plugin to validate API keys against the Identity Service. + +### Configuring Multiple Pools + +In the key-auth plugin configuration, add the `pools` option as shown below: + +```yaml +pools: + - geo: us + id: + type: remote + - geo: null + id: null + type: local +``` + +The order in which you configure the pools dictates the priority in which the dataplane attempts to authenticate the provided API keys. + +In the example above, if the remote pool is listed first, the dataplane will first reach out to the identity service and, if necessary, subsequently to the local pool. + +Alternatively, you can configure the local pool first: + +```yaml +pools: + - geo: null + id: null + type: local + - geo: us + id: + type: remote +``` + +In this configuration, the dataplane will initially check the local pool (LMDB) before querying the remote Identity Service. + +If a matching key is found in any of these pools, the request will be authenticated. If the key is not found in any of the configured pools, the request will be blocked. + +### Configuring Single Pools + +It is also possible to configure only a single pool, either local or remote. However, only one of each type can be configured. + +To configure only a remote pool: + +```yaml +pools: + - geo: us + id: + type: remote +``` + +In this case, the dataplane will only attempt to authenticate API keys against the remote Identity Service. + +To configure only a local pool: + +```yaml +pools: + - geo: null + id: null + type: local +``` + +In this scenario, the dataplane will only check the local pool (LMDB) for API key authentication. + +In both cases, if the API key is not found in the configured pool, the request will be blocked. diff --git a/app/_hub/kong-inc/key-auth/overview/_index.md b/app/_hub/kong-inc/key-auth/overview/_index.md index 34a7ce051869..c04ba4316688 100644 --- a/app/_hub/kong-inc/key-auth/overview/_index.md +++ b/app/_hub/kong-inc/key-auth/overview/_index.md @@ -300,71 +300,3 @@ Response: [acl-associating]: /plugins/acl/#associating-consumers - -## Externalized Consumers - --- Dummy/Link that points to Konnect Docs when ready. - -With the `pool_id` you obtained from the previous step, you can configure the key-auth plugin to validate API keys against the Identity Service. - -### Configuring Multiple Pools - -In the key-auth plugin configuration, add the `pools` option as shown below: - -```yaml -pools: - - geo: us - id: - type: remote - - geo: null - id: null - type: local -``` - -The order in which you configure the pools dictates the priority in which the dataplane attempts to authenticate the provided API keys. - -In the example above, if the remote pool is listed first, the dataplane will first reach out to the identity service and, if necessary, subsequently to the local pool. - -Alternatively, you can configure the local pool first: - -```yaml -pools: - - geo: null - id: null - type: local - - geo: us - id: - type: remote -``` - -In this configuration, the dataplane will initially check the local pool (LMDB) before querying the remote Identity Service. - -If a matching key is found in any of these pools, the request will be authenticated. If the key is not found in any of the configured pools, the request will be blocked. - -### Configuring Single Pools - -It is also possible to configure only a single pool, either local or remote. However, only one of each type can be configured. - -To configure only a remote pool: - -```yaml -pools: - - geo: us - id: - type: remote -``` - -In this case, the dataplane will only attempt to authenticate API keys against the remote Identity Service. - -To configure only a local pool: - -```yaml -pools: - - geo: null - id: null - type: local -``` - -In this scenario, the dataplane will only check the local pool (LMDB) for API key authentication. - -In both cases, if the API key is not found in the configured pool, the request will be blocked.