{"id":23663449,"url":"https://github.com/eyolas/kong-plugin-key-auth-referer","last_synced_at":"2025-09-01T17:31:49.629Z","repository":{"id":67394544,"uuid":"100488418","full_name":"eyolas/kong-plugin-key-auth-referer","owner":"eyolas","description":"PLUGIN KONG:  Key authentification and referer","archived":false,"fork":false,"pushed_at":"2018-02-17T21:58:41.000Z","size":12,"stargazers_count":4,"open_issues_count":0,"forks_count":3,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-04-02T22:04:22.409Z","etag":null,"topics":["kong-plugin"],"latest_commit_sha":null,"homepage":null,"language":"Lua","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/eyolas.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-08-16T12:45:57.000Z","updated_at":"2023-08-17T22:04:59.000Z","dependencies_parsed_at":"2023-02-22T05:16:11.459Z","dependency_job_id":null,"html_url":"https://github.com/eyolas/kong-plugin-key-auth-referer","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/eyolas/kong-plugin-key-auth-referer","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eyolas%2Fkong-plugin-key-auth-referer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eyolas%2Fkong-plugin-key-auth-referer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eyolas%2Fkong-plugin-key-auth-referer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eyolas%2Fkong-plugin-key-auth-referer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/eyolas","download_url":"https://codeload.github.com/eyolas/kong-plugin-key-auth-referer/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eyolas%2Fkong-plugin-key-auth-referer/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273162383,"owners_count":25056460,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-01T02:00:09.058Z","response_time":120,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["kong-plugin"],"created_at":"2024-12-29T05:28:22.658Z","updated_at":"2025-09-01T17:31:49.613Z","avatar_url":"https://github.com/eyolas.png","language":"Lua","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Key authentification and referer\n\nAdd Key Authentication (also referred to as an API key) and referer validation to your APIs. Consumers then add their key either in a querystring parameter or a header to authenticate their requests.\n\n----\n\n## Installation (for \u003e= v2.x)\n\nInstall the rock when building your Kong image/instance:\n```\nluarocks install kong-plugin-key-auth-referer\n```\n\nAdd the plugin to your `custom_plugins` section in `kong.conf`, the `KONG_CUSTOM_PLUGINS` is also available.\n\n```\ncustom_plugins = key-auth-referer\n```\n\n----\n\n## Compatibility\n\n| Plugin  | Kong version |\n|--|--|\n| v1.0 | 0.10.x |\n| v2.0 | 0.12.x |\n\n----\n\n## Terminology\n\n- `api`: your upstream service placed behind Kong, for which Kong proxies requests to.\n- `plugin`: a plugin executing actions inside Kong before or after a request has been proxied to the upstream API.\n- `consumer`: a developer or service using the api. When using Kong, a Consumer only communicates with Kong which proxies every call to the said, upstream api.\n- `credential`: in the key-auth-referer plugin context, a unique string associated with a consumer, also referred to as an API key.\n\n----\n\n## Configuration\n\nConfiguring the plugin is straightforward, you can add it on top of an [API][api-object] by executing the following request on your Kong server:\n\n\n```bash\n$ curl -X POST http://kong:8001/apis/{api}/plugins \\\n    --data \"name=key-auth-referer\" \\\n    --data \"config.hide_credentials=true\"\n```\n\n`api`: The `id` or `name` of the API that this plugin configuration will target\n\nYou can also apply it for every API using the `http://kong:8001/plugins/` endpoint. Read the [Plugin Reference](https://getkong.org/docs/latest/admin-api/#add-plugin) for more information.\n\nOnce applied, any user with a valid credential can access the service/API.\nTo restrict usage to only some of the authenticated users, also add the\n[ACL](https://getkong.org/plugins/acl/) plugin (not covered here) and create whitelist or\nblacklist groups of users.\n\nform parameter                   | default | description\n---                              | ---     | ---               \n`name`                           |         | The name of the plugin to use, in this case: `key-auth-referer`.\n`config.key_names`\u003cbr\u003e*optional* | `apikey`| Describes an array of comma separated parameter names where the plugin will look for a key. The client must send the authentication key in one of those key names, and the plugin will try to read the credential from a header or the querystring parameter with the same name.\u003cbr\u003e*note*: the key names may only contain [a-z], [A-Z], [0-9] and [-].\n`config.key_in_body`             | `false` | If enabled, the plugin will read the request body (if said request has one and its MIME type is supported) and try to find the key in it. Supported MIME types are `application/www-form-urlencoded`, `application/json`, and `multipart/form-data`.\n`config.hide_credentials`\u003cbr\u003e*optional* | `false` | An optional boolean value telling the plugin to hide the credential to the upstream API server. It will be removed by Kong before proxying the request.\n`config.anonymous`\u003cbr\u003e*optional*           | `` | An optional string (consumer uuid) value to use as an \"anonymous\" consumer if authentication fails. If empty (default), the request will fail with an authentication failure `4xx`\n\n----\n\n## Usage\n\nIn order to use the plugin, you first need to create a Consumer to associate one or more credentials to. The Consumer represents a developer using the final service/API.\n\n### Create a Consumer\n\nYou need to associate a credential to an existing [Consumer][consumer-object] object, that represents a user consuming the API. To create a [Consumer][consumer-object] you can execute the following request:\n\n```bash\n$ curl -X POST http://kong:8001/consumers/ \\\n    --data \"username=\u003cUSERNAME\u003e\" \\\n    --data \"custom_id=\u003cCUSTOM_ID\u003e\"\nHTTP/1.1 201 Created\n\n{\n    \"username\":\"\u003cUSERNAME\u003e\",\n    \"custom_id\": \"\u003cCUSTOM_ID\u003e\",\n    \"created_at\": 1472604384000,\n    \"id\": \"7f853474-7b70-439d-ad59-2481a0a9a904\"\n}\n```\n\nparameter                      | default | description\n---                            | ---     | ---\n`username`\u003cbr\u003e*semi-optional*  |         | The username of the Consumer. Either this field or `custom_id` must be specified.\n`custom_id`\u003cbr\u003e*semi-optional* |         | A custom identifier used to map the Consumer to another database. Either this field or `username` must be specified.\n\nA [Consumer][consumer-object] can have many credentials.\n\nIf you are also using the [ACL](https://getkong.org/plugins/acl/) plugin and whitelists with this\nservice, you must add the new consumer to a whitelisted group. See\n[ACL: Associating Consumers][acl-associating] for details.\n\n### Create an API Key\n\nYou can provision new credentials by making the following HTTP request:\n\n```bash\n$ curl -X POST http://kong:8001/consumers/{consumer}/key-auth-referer \\\n    --data \"authorized_referer=*\"\n\nHTTP/1.1 201 Created\n\n{\n    \"authorized_referer\":[\"*\"],\n    \"consumer_id\":\"2e2729d3-b58f-4980-a283-06302990f91b\",\n    \"id\":\"1014ecc5-c7e4-4e4c-8800-868a15aea0f3\",\n    \"key\":\"38f6b9c30560474e9998289928d86476\",\n    \"created_at\":1496150875000\n}\n```\n\n`consumer`: The `id` or `username` property of the [Consumer][consumer-object] entity to associate the credentials to.\n\nform parameter      | default | description\n---                 | ---     | ---\n`key`\u003cbr\u003e*optional* |         | You can optionally set your own unique `key` to authenticate the client. If missing, the plugin will generate one.\n`authorized_referer` |         | List of authorized referer (see [test-referer.lua](/kong/plugins/key-auth-referer/test-referer.lua))\n\n\u003cdiv class=\"alert alert-warning\"\u003e\n  \u003cstrong\u003eNote:\u003c/strong\u003e It is recommended to let Kong auto-generate the key. Only specify it yourself if you are migrating an existing system to Kong. You must re-use your keys to make the migration to Kong transparent to your Consumers.\n\u003c/div\u003e\n\n### Using the API Key\n\nSimply make a request with the key as a querystring parameter:\n\n```bash\n$ curl http://kong:8000/{api path}?apikey=\u003csome_key\u003e\n```\n\nOr in a header:\n\n```bash\n$ curl http://kong:8000/{api path} \\\n    -H 'apikey: \u003csome_key\u003e'\n```\n\n### Upstream Headers\n\nWhen a client has been authenticated, the plugin will append some headers to the request before proxying it to the upstream API/Microservice, so that you can identify the Consumer in your code:\n\n* `X-Consumer-ID`, the ID of the Consumer on Kong\n* `X-Consumer-Custom-ID`, the `custom_id` of the Consumer (if set)\n* `X-Consumer-Username`, the `username` of the Consumer (if set)\n* `X-Credential-Username`, the `username` of the Credential (only if the consumer is not the 'anonymous' consumer)\n* `X-Anonymous-Consumer`, will be set to `true` when authentication failed, and the 'anonymous' consumer was set instead.\n\nYou can use this information on your side to implement additional logic. You can use the `X-Consumer-ID` value to query the Kong Admin API and retrieve more information about the Consumer.\n\n[api-object]: https://getkong.org/docs/latest/admin-api/#api-object\n[configuration]: https://getkong.org/docs/latest/configuration\n[consumer-object]: https://getkong.org/docs/latest/admin-api/#consumer-object\n[acl-associating]: https://getkong.org/plugins/acl/#associating-consumers\n[faq-authentication]: https://getkong.org/about/faq/#how-can-i-add-authentication-to-a-microservice-api","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feyolas%2Fkong-plugin-key-auth-referer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Feyolas%2Fkong-plugin-key-auth-referer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feyolas%2Fkong-plugin-key-auth-referer/lists"}