feat: add support for externalized consumers #7657
+167
−24
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,45 @@ | ||
| --- | ||
| nav_title: Configure realms for consumers | ||
| title: Configure realms for consumers in {{site.konnect_short_name}} | ||
| --- | ||
|
|
||
| Starting in {{site.base_gateway]] 3.10.x, credentials that are stored centrally in {{site.konnect_short_name}} that are shared across multiple {{site.base_gateway}} can be validated by configuring `identity_realms` field in the Key Auth plugin. You can use these realms when you create [centrally managed consumers](/konnect/centralized-consumer-management/). A data plane can only reach out to realms in the same region as they are deployed. | ||
|
|
||
| Add the `identity_realms` field as shown below: | ||
|
|
||
| ```bash | ||
| curl -X POST \ | ||
| https://{region}.api.konghq.com/v2/control-planes/{controlPlaneId}/core-entities/plugins/ \ | ||
| --header "accept: application/json" \ | ||
| --header "Content-Type: application/json" \ | ||
| --header "Authorization: Bearer TOKEN" \ | ||
| --data '{ | ||
| "name": "key-auth", | ||
| "config": { | ||
| "key_names": ["apikey"], | ||
| "identity_realms": [ | ||
| { | ||
| "region": "$REGION", | ||
| "id": "$REALM_ID", | ||
| "scope": "realm" | ||
| }, | ||
| { | ||
| "scope": "cp" | ||
| } | ||
| ] | ||
| } | ||
| }' | ||
| ``` | ||
| Be sure to replace the following with your own values: | ||
| * {region}: Region for your {{site.konnect_short_name}} instance. | ||
| * {controlPlaneId}: UUID of your control plane. | ||
| * $KONNECT_TOKEN: Replace with your {{site.konnect_short_name}} personal access token. | ||
| * $REALM_ID: The ID of the realm you created previously. | ||
| * $REGION: Region for your {{site.konnect_short_name}} instance. | ||
|
|
||
| `identity_realms` are scoped to the control plane by default (`scope: cp`). The order in which you configure the `identity_realms` dictates the priority in which the data plane attempts to authenticate the provided API keys: | ||
|
|
||
| * **Realm is listed first:** The data plane will first reach out to the realm. If the API key is not found in the realm, the data plane will look for the API key in the control plane config. | ||
| * **Control plane scope listed first:** The data plane will initially check the control plane configuration (LMDB) for the API key before looking up the API Key in the realm. | ||
| * **Realm only:** You can also configure a single `identity_realms` by omitting the `scope: cp` from the example. In this case, the data plane will only attempt to authenticate API keys against the realm. If the API key isn't found, the request will be blocked. | ||
| * **Control plane only:** You can configure a look up only in the control plane config by only specifying `scope: cp` for `identity_realms`. In this scenario, the data plane will only check the control plane configuration (LMDB) for API key authentication. If the API key isn't found, the request will be blocked. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,97 @@ | ||
| --- | ||
| title: Centralized consumer management | ||
| --- | ||
|
|
||
| A [consumer](/gateway/latest/key-concepts/consumers/) is a {{site.base_gateway}} entity that consumes or uses the APIs managed by {{site.base_gateway}}. These can be things like applications, services, or users who interact with your APIs. Consumers can be scoped to a {{site.konnect_short_name}} region and managed centrally, or be scoped to a control plane in Gateway Manager. | ||
|
|
||
| Centralized consumer management provides the following benefits: | ||
| * Set up consumer identity centrally instead of defining it in multiple control planes. | ||
| * Share consumers across multiple control planes. Users don't need to replicate changes to consumer identity in multiple control planes and consumer configuration doesn't conflict. | ||
| * Reduce configuration sync issues between the control plane and the data planes. Consumers that are managed centrally aren't part of the configuration that is pushed down from the control plane to the data planes, so it reduces config size and latency. | ||
|
|
||
| ## How centralized consumer management works | ||
|
|
||
| When you create a consumer centrally, you must assign it to a realm. A realm groups consumers around an identity, defined by organizational boundaries, such as a production realm or a development realm. Realms are connected to a [geographic region](/konnect/geo/) in {{site.konnect_short_name}}. Centrally managed consumers exist outside of control planes, so they can be used across control planes. | ||
|
|
||
| ## Create consumers and realms | ||
|
|
||
| You can manage consumers centrally using the {{site.konnect_short_name}} API. Only Org Admins and Control Plane Admins have CRUD permissions for these consumers. | ||
|
|
||
| {:.important} | ||
| > Centralized consumer management is only available for {{site.base_gateway}} 3.10 data planes. Make sure your control plane uses 3.10 data planes at minimum when configuring these consumers. | ||
|
|
||
| 1. Use the `/realms` endpoint to create a realm and optionally associate it with allowed control planes and time-to-live values: | ||
| ``` | ||
| curl -X POST \ | ||
| https://{region}.api.konghq.com/v1/realms \ | ||
| -H "Content-Type: application/json" \ | ||
| -H "Authorization: Bearer $KONNECT_TOKEN" \ | ||
| -d '{ | ||
| "name": "prod", | ||
| "allowed_control_planes": [ | ||
| "$CONTROL_PLANE_UUID" | ||
| ], | ||
| "ttl": 10, | ||
| "negative_ttl": 10, | ||
| "consumer_groups": [ | ||
| "$CONSUMER_GROUP" | ||
| ] | ||
| }' | ||
| ``` | ||
| Save the ID of the realm. | ||
|
|
||
| Be sure to replace the following with your own values: | ||
| * `{region}`: Region for your {{site.konnect_short_name}} instance. Data planes can only reach out to realms in the same region as the data plane. | ||
| * `$KONNECT_TOKEN`: Replace with your {{site.konnect_short_name}} personal access token. | ||
| * `$CONTROL_PLANE_UUID`: (Optional) Replace with your control plane UUID. | ||
| * `ttl`: (Optional) 'ttl' is the time-to-live (TTL) in minutes of the consumer for this realm in the {{site.base_gateway}} cache. | ||
| * `negative_ttl`: (Optional) Represents the TTL of a bad login cache entry. | ||
| * `$CONSUMER_GROUP`: (Optional) Replace with the name of the consumer groups you want to associate with the realm. | ||
| 1. Use the `/realms/{realmId}/consumers` endpoint to create a centrally managed consumer and optionally assign it to a consumer group: | ||
| ```sh | ||
| curl -X POST \ | ||
| https://{region}.api.konghq.com/v1/realms/{realmId}/consumers \ | ||
| -H "Content-Type: application/json" \ | ||
| -H "Authorization: Bearer TOKEN" \ | ||
| -d '{ | ||
| "username": "$CONSUMER_NAME", | ||
| "consumer_groups": ["$CONSUMER_GROUP"] | ||
| }' | ||
| ``` | ||
| Save the ID of the consumer. | ||
|
|
||
| Be sure to replace the following with your own values: | ||
| * `{region}`: Region for your {{site.konnect_short_name}} instance. Data planes can only reach out to realms in the same region as the data plane. | ||
| * `$KONNECT_TOKEN`: Replace with your {{site.konnect_short_name}} personal access token. | ||
| * `{realmId}`: The ID of the realm you created previously. | ||
| * `$CONSUMER_NAME`: Replace with the name of the consumer. | ||
| * `$CONSUMER_GROUP`: (Optional) Replace with the name of the consumer groups you want to associate with the consumer. Consumer groups set here are additive. This means that if you configure the realm with consumer groups A and B, and then configure the consumer with consumer group C, the authenticated consumer will be assigned to consumer groups A, B, and C. | ||
| 1. Configure authentication keys for consumers: | ||
| ```sh | ||
| curl -X POST \ | ||
| https://{region}.api.konghq.com/v1/realms/{realmId}/consumers/{consumerId}/keys \ | ||
| -H "Content-Type: application/json" \ | ||
| -H "Authorization: Bearer TOKEN" \ | ||
| -d '{ | ||
| "type": "new" | ||
| }' | ||
| ``` | ||
| Be sure to replace the following with your own values: | ||
| * `{region}`: Region for your {{site.konnect_short_name}} instance. Data planes can only reach out to realms in the same region as the data plane. | ||
| * `$KONNECT_TOKEN`: Replace with your {{site.konnect_short_name}} personal access token. | ||
| * `{realmId}`: The ID of the realm you created previously. | ||
| * `{consumerId}`: The ID of the consumer you created previously. | ||
|
|
||
| 1. Consumers require authentication. Configure authentication using the [Key Auth plugin](/hub/kong-inc/key-auth/how-to/). | ||
|
|
||
| `identity_realms` are scoped to the control plane by default (`scope: cp`). The order in which you configure the `identity_realms` dictates the priority in which the data plane attempts to authenticate the provided API keys: | ||
|
|
||
| * **Realm is listed first:** The data plane will first reach out to the realm. If the API key is not found in the realm, the data plane will look for the API key in the control plane config. | ||
| * **Control plane scope listed first:** The data plane will initially check the control plane configuration (LMDB) for the API key before looking up the API Key in the realm. | ||
| * **Realm only:** You can also configure a single `identity_realms` by omitting the `scope: cp` from the example. In this case, the data plane will only attempt to authenticate API keys against the realm. If the API key isn't found, the request will be blocked. | ||
| * **Control plane only:** You can configure a look up only in the control plane config by only specifying `scope: cp` for `identity_realms`. In this scenario, the data plane will only check the control plane configuration (LMDB) for API key authentication. If the API key isn't found, the request will be blocked. | ||
|
|
||
| {:.note} | ||
| > **Note:** If you are using KIC to manage your data plane nodes in {{site.konnect_short_name}}, ensure that you configure the `telemetry_endpoint` in the data plane. You can find the `telemetry_endpoint` in the {{site.konnect_short_name}} UI in [Gateway Manager](https://cloud.konghq.com/gateway-manager/) in the data plane node instructions. | ||
|
|
||
|
There was a problem hiding this comment. Do we want to add a section around changing the scope of consumers from cp to realm? The user will need to do the following call: POST https://us.api.konghq.com/identity/pools/%7BpoolID%7D/consumers)/Alice-123/keys There was a problem hiding this comment. Since that's optional, I'd rather link them to the API spec so they can see what else they can do. Do you have a predicted link to the public API spec? There was a problem hiding this comment. I am adding a new step to create new keys for the consumer, since I think that was missing. |
||
|
|
||
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
We define time-to-live further down the document. Should we define it here as well?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I'll leave this one as-is since we typically follow this format in docs where we explain it later in the bullets and it could bloat the step instruction if I put it here.