{"id":13563423,"url":"https://github.com/nokia/kong-oidc","last_synced_at":"2025-04-12T22:19:16.989Z","repository":{"id":41086571,"uuid":"94380475","full_name":"nokia/kong-oidc","owner":"nokia","description":"OIDC plugin for Kong","archived":false,"fork":false,"pushed_at":"2023-06-23T09:56:25.000Z","size":212,"stargazers_count":478,"open_issues_count":105,"forks_count":347,"subscribers_count":26,"default_branch":"master","last_synced_at":"2025-04-04T01:18:02.867Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Lua","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nokia.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}},"created_at":"2017-06-14T23:21:30.000Z","updated_at":"2025-03-20T20:47:26.000Z","dependencies_parsed_at":"2024-01-25T05:09:43.735Z","dependency_job_id":"87eb55af-5af2-4d59-b234-cfcd4ab90ba8","html_url":"https://github.com/nokia/kong-oidc","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nokia%2Fkong-oidc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nokia%2Fkong-oidc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nokia%2Fkong-oidc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nokia%2Fkong-oidc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nokia","download_url":"https://codeload.github.com/nokia/kong-oidc/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248637933,"owners_count":21137573,"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","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":[],"created_at":"2024-08-01T13:01:19.070Z","updated_at":"2025-04-12T22:19:16.938Z","avatar_url":"https://github.com/nokia.png","language":"Lua","funding_links":[],"categories":["Lua","Authentication","Custom Plugins"],"sub_categories":["Auth Plugins"],"readme":"# What is Kong OIDC plugin\n\n[![Join the chat at https://gitter.im/nokia/kong-oidc](https://badges.gitter.im/nokia/kong-oidc.svg)](https://gitter.im/nokia/kong-oidc?utm_source=badge\u0026utm_medium=badge\u0026utm_campaign=pr-badge\u0026utm_content=badge)\n\n**Continuous Integration:** [![Build Status](https://travis-ci.org/nokia/kong-oidc.svg?branch=master)](https://travis-ci.org/nokia/kong-oidc) \n[![Coverage Status](https://coveralls.io/repos/github/nokia/kong-oidc/badge.svg?branch=master)](https://coveralls.io/github/nokia/kong-oidc?branch=master) \u003cbr/\u003e\n\n**kong-oidc** is a plugin for [Kong](https://github.com/Mashape/kong) implementing the\n[OpenID Connect](http://openid.net/specs/openid-connect-core-1_0.html) Relying Party (RP) functionality.\n\nIt authenticates users against an OpenID Connect Provider using\n[OpenID Connect Discovery](http://openid.net/specs/openid-connect-discovery-1_0.html)\nand the Basic Client Profile (i.e. the Authorization Code flow).\n\nIt maintains sessions for authenticated users by leveraging `lua-resty-openidc` thus offering\na configurable choice between storing the session state in a client-side browser cookie or use\nin of the server-side storage mechanisms `shared-memory|memcache|redis`.\n\nIt supports server-wide caching of resolved Discovery documents and validated Access Tokens.\n\nIt can be used as a reverse proxy terminating OAuth/OpenID Connect in front of an origin server so that\nthe origin server/services can be protected with the relevant standards without implementing those on\nthe server itself.\n\nIntrospection functionality add capability for already authenticated users and/or applications that\nalready posses acces token to go through kong. The actual token verification is then done by Resource Server.\n\n## How does it work\n\nThe diagram below shows the message exchange between the involved parties.\n\n![alt Kong OIDC flow](docs/kong_oidc_flow.png)\n\nThe `X-Userinfo` header contains the payload from the Userinfo Endpoint\n\n```\nX-Userinfo: {\"preferred_username\":\"alice\",\"id\":\"60f65308-3510-40ca-83f0-e9c0151cc680\",\"sub\":\"60f65308-3510-40ca-83f0-e9c0151cc680\"}\n```\n\nThe plugin also sets the `ngx.ctx.authenticated_consumer` variable, which can be using in other Kong plugins:\n```\nngx.ctx.authenticated_consumer = {\n    id = \"60f65308-3510-40ca-83f0-e9c0151cc680\",   -- sub field from Userinfo\n    username = \"alice\"                             -- preferred_username from Userinfo\n}\n```\n\n\n## Dependencies\n\n**kong-oidc** depends on the following package:\n\n- [`lua-resty-openidc`](https://github.com/pingidentity/lua-resty-openidc/)\n\n\n## Installation\n\nIf you're using `luarocks` execute the following:\n\n     luarocks install kong-oidc\n\nYou also need to set the `KONG_PLUGINS` environment variable\n\n     export KONG_PLUGINS=oidc\n     \n## Usage\n\n### Parameters\n\n| Parameter | Default  | Required | description |\n| --- | --- | --- | --- |\n| `name` || true | plugin name, has to be `oidc` |\n| `config.client_id` || true | OIDC Client ID |\n| `config.client_secret` || true | OIDC Client secret |\n| `config.discovery` | https://.well-known/openid-configuration | false | OIDC Discovery Endpoint (`/.well-known/openid-configuration`) |\n| `config.scope` | openid | false| OAuth2 Token scope. To use OIDC it has to contains the `openid` scope |\n| `config.ssl_verify` | false | false | Enable SSL verification to OIDC Provider |\n| `config.session_secret` | | false | Additional parameter, which is used to encrypt the session cookie. Needs to be random |\n| `config.introspection_endpoint` | | false | Token introspection endpoint |\n| `config.timeout` | | false | OIDC endpoint calls timeout |\n| `config.introspection_endpoint_auth_method` | client_secret_basic | false | Token introspection auth method. resty-openidc supports `client_secret_(basic|post)` |\n| `config.bearer_only` | no | false | Only introspect tokens without redirecting |\n| `config.realm` | kong | false | Realm used in WWW-Authenticate response header |\n| `config.logout_path` | /logout | false | Absolute path used to logout from the OIDC RP |\n\n### Enabling\n\nTo enable the plugin only for one API:\n\n```\nPOST /apis/\u003capi_id\u003e/plugins/ HTTP/1.1\nHost: localhost:8001\nContent-Type: application/x-www-form-urlencoded\nCache-Control: no-cache\n\nname=oidc\u0026config.client_id=kong-oidc\u0026config.client_secret=29d98bf7-168c-4874-b8e9-9ba5e7382fa0\u0026config.discovery=https%3A%2F%2F\u003coidc_provider\u003e%2F.well-known%2Fopenid-configuration\n```\n\nTo enable the plugin globally:\n```\nPOST /plugins HTTP/1.1\nHost: localhost:8001\nContent-Type: application/x-www-form-urlencoded\nCache-Control: no-cache\n\nname=oidc\u0026config.client_id=kong-oidc\u0026config.client_secret=29d98bf7-168c-4874-b8e9-9ba5e7382fa0\u0026config.discovery=https%3A%2F%2F\u003coidc_provider\u003e%2F.well-known%2Fopenid-configuration\n```\n\nA successful response:\n```\nHTTP/1.1 201 Created\nDate: Tue, 24 Oct 2017 19:37:38 GMT\nContent-Type: application/json; charset=utf-8\nTransfer-Encoding: chunked\nConnection: keep-alive\nAccess-Control-Allow-Origin: *\nServer: kong/0.11.0\n\n{\n    \"created_at\": 1508871239797,\n    \"config\": {\n        \"response_type\": \"code\",\n        \"client_id\": \"kong-oidc\",\n        \"discovery\": \"https://\u003coidc_provider\u003e/.well-known/openid-configuration\",\n        \"scope\": \"openid\",\n        \"ssl_verify\": \"no\",\n        \"client_secret\": \"29d98bf7-168c-4874-b8e9-9ba5e7382fa0\",\n        \"token_endpoint_auth_method\": \"client_secret_post\"\n    },\n    \"id\": \"58cc119b-e5d0-4908-8929-7d6ed73cb7de\",\n    \"enabled\": true,\n    \"name\": \"oidc\",\n    \"api_id\": \"32625081-c712-4c46-b16a-5d6d9081f85f\"\n}\n```\n\n### Upstream API request\n\nThe plugin adds a additional `X-Userinfo`, `X-Access-Token` and `X-Id-Token` headers to the upstream request, which can be consumer by upstream server. All of them are base64 encoded:\n\n```\nGET / HTTP/1.1\nHost: netcat:9000\nConnection: keep-alive\nX-Forwarded-For: 172.19.0.1\nX-Forwarded-Proto: http\nX-Forwarded-Host: localhost\nX-Forwarded-Port: 8000\nX-Real-IP: 172.19.0.1\nCache-Control: max-age=0\nUser-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/61.0.3163.100 Safari/537.36\nUpgrade-Insecure-Requests: 1\nAccept: text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8\nAccept-Encoding: gzip, deflate\nAccept-Language: pl-PL,pl;q=0.8,en-US;q=0.6,en;q=0.4\nCookie: session=KOn1am4mhQLKazlCA.....\nX-Userinfo: eyJnaXZlbl9uYW1lIjoixITEmMWaw5PFgcW7xbnEhiIsInN1YiI6ImM4NThiYzAxLTBiM2ItNDQzNy1hMGVlLWE1ZTY0ODkwMDE5ZCIsInByZWZlcnJlZF91c2VybmFtZSI6ImFkbWluIiwibmFtZSI6IsSExJjFmsOTxYHFu8W5xIYiLCJ1c2VybmFtZSI6ImFkbWluIiwiaWQiOiJjODU4YmMwMS0wYjNiLTQ0MzctYTBlZS1hNWU2NDg5MDAxOWQifQ==\nX-Access-Token: eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJGenFSY0N1Ry13dzlrQUJBVng1ZG9sT2ZwTFhBNWZiRGFlVDRiemtnSzZRIn0.eyJqdGkiOiIxYjhmYzlkMC1jMjlmLTQwY2ItYWM4OC1kNzMyY2FkODcxY2IiLCJleHAiOjE1NDg1MTA4MjksIm5iZiI6MCwiaWF0IjoxNTQ4NTEwNzY5LCJpc3MiOiJodHRwOi8vMTkyLjE2OC4wLjk6ODA4MC9hdXRoL3JlYWxtcy9tYXN0ZXIiLCJhdWQiOlsibWFzdGVyLXJlYWxtIiwiYWNjb3VudCJdLCJzdWIiOiJhNmE3OGQ5MS01NDk0LTRjZTMtOTU1NS04NzhhMTg1Y2E0YjkiLCJ0eXAiOiJCZWFyZXIiLCJhenAiOiJrb25nIiwibm9uY2UiOiJmNGRkNDU2YzBjZTY4ZmFmYWJmNGY4ZDA3YjQ0YWE4NiIsImF1dGhfdGltZSI6…IiwibWFuYWdlLWFjY291bnQtbGlua3MiLCJ2aWV3LXByb2ZpbGUiXX19LCJzY29wZSI6Im9wZW5pZCBwcm9maWxlIGVtYWlsIiwiZW1haWxfdmVyaWZpZWQiOmZhbHNlLCJwcmVmZXJyZWRfdXNlcm5hbWUiOiJhZG1pbiJ9.GWuguFjSEDGxw_vbD04UMKxtai15BE2lwBO0YkSzp-NKZ2SxAzl0nyhZxpP0VTzk712nQ8f_If5-mQBf_rqEVnOraDmX5NOXP0B8AoaS1jsdq4EomrhZGqlWmuaV71Cnqrw66iaouBR_6Q0s8bgc1FpCPyACM4VWs57CBdTrAZ2iv8dau5ODkbEvSgIgoLgBbUvjRKz1H0KyeBcXlVSgHJ_2zB9q2HvidBsQEIwTP8sWc6er-5AltLbV8ceBg5OaZ4xHoramMoz2xW-ttjIujS382QQn3iekNByb62O2cssTP3UYC747ehXReCrNZmDA6ecdnv8vOfIem3xNEnEmQw\nX-Id-Token: eyJuYmYiOjAsImF6cCI6ImtvbmciLCJpYXQiOjE1NDg1MTA3NjksImlzcyI6Imh0dHA6XC9cLzE5Mi4xNjguMC45OjgwODBcL2F1dGhcL3JlYWxtc1wvbWFzdGVyIiwiYXVkIjoia29uZyIsIm5vbmNlIjoiZjRkZDQ1NmMwY2U2OGZhZmFiZjRmOGQwN2I0NGFhODYiLCJwcmVmZXJyZWRfdXNlcm5hbWUiOiJhZG1pbiIsImF1dGhfdGltZSI6MTU0ODUxMDY5NywiYWNyIjoiMSIsInNlc3Npb25fc3RhdGUiOiJiNDZmODU2Ny0zODA3LTQ0YmMtYmU1Mi1iMTNiNWQzODI5MTQiLCJleHAiOjE1NDg1MTA4MjksImVtYWlsX3ZlcmlmaWVkIjpmYWxzZSwianRpIjoiMjI1ZDRhNDItM2Y3ZC00Y2I2LTkxMmMtOGNkYzM0Y2JiNTk2Iiwic3ViIjoiYTZhNzhkOTEtNTQ5NC00Y2UzLTk1NTUtODc4YTE4NWNhNGI5IiwidHlwIjoiSUQifQ==\n```\n\n\n## Development\n\n### Running Unit Tests\n\nTo run unit tests, run the following command:\n\n```\n./bin/run-unit-tests.sh\n```\n\nThis may take a while for the first run, as the docker image will need to be built, but subsequent runs will be quick.\n\n### Building the Integration Test Environment\n\nTo build the integration environment (Kong with the oidc plugin enabled, and Keycloak as the OIDC Provider), you will first need to find your computer's IP, and assign that to the environment variable `IP`. Finally, you will run the `./bin/build-env.sh` command. Here's an example:\n\n```\nexport IP=192.168.0.1\n./bin/build-env.sh\n```\n\nTo tear the environment down:\n\n```\n./bin/teardown-env.sh\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnokia%2Fkong-oidc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnokia%2Fkong-oidc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnokia%2Fkong-oidc/lists"}