{"id":19993736,"url":"https://github.com/revomatico/kong-oidc","last_synced_at":"2025-05-04T12:32:32.141Z","repository":{"id":40649503,"uuid":"242987276","full_name":"revomatico/kong-oidc","owner":"revomatico","description":"OIDC plugin for Kong","archived":true,"fork":true,"pushed_at":"2024-04-12T17:00:04.000Z","size":250,"stargazers_count":110,"open_issues_count":13,"forks_count":76,"subscribers_count":8,"default_branch":"master","last_synced_at":"2024-12-06T22:38:56.761Z","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":"nokia/kong-oidc","license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/revomatico.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}},"created_at":"2020-02-25T11:49:58.000Z","updated_at":"2024-10-07T02:58:17.000Z","dependencies_parsed_at":"2023-01-23T06:30:24.302Z","dependency_job_id":null,"html_url":"https://github.com/revomatico/kong-oidc","commit_stats":null,"previous_names":[],"tags_count":18,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/revomatico%2Fkong-oidc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/revomatico%2Fkong-oidc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/revomatico%2Fkong-oidc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/revomatico%2Fkong-oidc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/revomatico","download_url":"https://codeload.github.com/revomatico/kong-oidc/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252335094,"owners_count":21731520,"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-11-13T04:52:56.467Z","updated_at":"2025-05-04T12:32:30.894Z","avatar_url":"https://github.com/revomatico.png","language":"Lua","funding_links":[],"categories":["Lua"],"sub_categories":[],"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\n\u003e **Note:** at the moment, there is an issue using memcached/redis, probably due to session locking: the sessions freeze. Help to debug this is appreciated. I am currently using shared memory to store sessions.\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\nThe introspection functionality adds capability for already authenticated users and/or applications that\nalready possess access 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```json\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_credential` variable, which can be using in other Kong plugins:\n\n```lua\nngx.ctx.authenticated_credential = {\n    id = \"60f65308-3510-40ca-83f0-e9c0151cc680\",   -- sub field from Userinfo\n    username = \"alice\"                             -- preferred_username from Userinfo\n}\n```\n\nFor successfully authenticated request, possible (anonymous) consumer identity set by higher priority plugin is cleared as part of setting the credentials.\n\nThe plugin will try to retrieve the user's groups from a field in the token (default `groups`) and set `kong.ctx.shared.authenticated_groups` so that Kong authorization plugins can make decisions based on the user's group membership.\n\n## Dependencies\n\n**kong-oidc** depends on the following package:\n\n- [`lua-resty-openidc`](https://github.com/zmartzone/lua-resty-openidc/)\n\n## Installation\n\nIf you're using `luarocks` execute the following:\n\n     luarocks install kong-oidc\n\n[Kong \u003e= 0.14] Since `KONG_CUSTOM_PLUGINS` has been removed, you also need to set the `KONG_PLUGINS` environment variable to include besides the bundled ones, oidc\n\n     export KONG_PLUGINS=bundled,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`                          | \u003chttps://.well-known/openid-configuration\u003e | 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 authentication 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| `config.unauth_action`                      | auth                                       | false    | What action to take when unauthenticated \u003cbr\u003e - `auth` to redirect to the login page and attempt (re)authenticatation,\u003cbr\u003e - `deny` to stop with 401                                    |\n| `config.recovery_page_path`                 |                                            | false    | Path of a recovery page to redirect the user when error occurs (except 401). To not show any error, you can use '/' to redirect immediately home. The error will be logged server side. |\n| `config.ignore_auth_filters`                |                                            | false    | A comma-separated list of endpoints to bypass authentication for                                                                                                                        |\n| `config.redirect_uri`                       |                                            | false    | A relative or absolute URI the OP will redirect to after successful authentication                                                                                                      |\n| `config.userinfo_header_name`               | `X-Userinfo`                               | false    | The name of the HTTP header to use when passing the UserInfo to the upstream server                                                                                                     |\n| `config.id_token_header_name`               | `X-ID-Token`                               | false    | The name of the HTTP header to use when passing the ID Token to the upstream server                                                                                                     |\n| `config.access_token_header_name`           | `X-Access-Token`                           | false    | The name of the HTTP header to use when passing the Access Token to the upstream server                                                                                                 |\n| `config.access_token_as_bearer`             | no                                         | false    | Whether or not the access token should be passed as a Bearer token                                                                                                                      |\n| `config.disable_userinfo_header`            | no                                         | false    | Disable passing the Userinfo to the upstream server                                                                                                                                     |\n| `config.disable_id_token_header`            | no                                         | false    | Disable passing the ID Token to the upstream server                                                                                                                                     |\n| `config.disable_access_token_header`        | no                                         | false    | Disable passing the Access Token to the upstream server                                                                                                                                 |\n| `config.groups_claim`                       | groups                                     | false    | Name of the claim in the token to get groups from                                                                                                                                       |\n| `config.skip_already_auth_requests`         | no                                         | false    | Ignore requests where credentials have already been set by a higher priority plugin such as basic-auth                                                                                  |\n| `config.bearer_jwt_auth_enable`             | no                                         | false    | Authenticate based on JWT (ID) token provided in Authorization (Bearer) header. Checks iss, sub, aud, exp, iat (as in ID token). `config.discovery` must be defined to discover JWKS    |\n| `config.bearer_jwt_auth_allowed_auds`       |                                            | false    | List of JWT token `aud` values allowed when validating JWT token in Authorization header. If not provided, uses value from `config.client_id`                                           |\n| `config.bearer_jwt_auth_signing_algs`       | [ 'RS256' ]                                | false    | List of allowed signing algorithms for Authorization header JWT token validation. Must match to OIDC provider and `resty-openidc` supported algorithms                                  |\n| `config.header_names`                       |                                            | false    | List of custom upstream HTTP headers to be added based on claims. Must have same number of elements as `config.header_claims`. Example: `[ 'x-oidc-email', 'x-oidc-email-verified' ]`   |\n| `config.header_claims`                      |                                            | false    | List of claims to be used as source for custom upstream headers. Claims are sourced from Userinfo, ID Token, Bearer JWT, Introspection, depending on auth method.  Use only claims containing simple string values. Example: `[ 'email', 'email_verified'` |\n| `config.http_proxy` || false | http proxy url |\n| `config.https_proxy` || false | https proxy url (only supports url format __http__://proxy and not __https__://proxy) |\n\n### Enabling kong-oidc\n\nTo enable the plugin only for one API:\n\n```http\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\n```http\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\n```http\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\nFor successfully authenticated request, the plugin will set upstream header `X-Credential-Identifier` to contain `sub` claim from user info, ID token or introspection result. Header `X-Anonymous-Consumer` is cleared.\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```http\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### Standard OpenID Connect Scopes and Claims\n\nThe OpenID Connect Core 1.0 profile specifies the following standard scopes and claims:\n\n| Scope     | Claim(s)                                                                                                                               |\n| --------- | -------------------------------------------------------------------------------------------------------------------------------------- |\n| `openid`  | `sub`. In an ID Token, `iss`, `aud`, `exp`, `iat` will also be provided.                                                               |\n| `profile` | Typically claims like `name`, `family_name`, `given_name`, `middle_name`, `preferred_username`, `nickname`, `picture` and `updated_at` |\n| `email`   | `email` and `email_verified` (_boolean_) indicating if the email address has been verified by the user                                 |\n\n_Note that the `openid` scope is a mandatory designator scope._\n\n#### Description of the standard claims\n\n| Claim                | Type           | Description                                                                                                                                                 |\n| -------------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `iss`                | URI            | The Uniform Resource Identifier uniquely identifying the OpenID Connect Provider (_OP_)                                                                     |\n| `aud`                | string / array | The intended audiences. For ID tokens, the identity token is one or more clients. For Access tokens, the audience is typically one or more Resource Servers |\n| `nbf`                | integer        | _Not before_ timestamp in Unix Epoch time\\*. May be omitted or set to 0 to indicate that the audience can disregard the claim                               |\n| `exp`                | integer        | _Expires_ timestamp in Unix Epoch time\\*                                                                                                                    |\n| `name`               | string         | Preferred display name. Ex. `John Doe`                                                                                                                      |\n| `family_name`        | string         | Last name. Ex. `Doe`                                                                                                                                        |\n| `given_name`         | string         | First name. Ex. `John`                                                                                                                                      |\n| `middle_name`        | string         | Middle name. Ex. `Donald`                                                                                                                                   |\n| `nickname`           | string         | Nick name. Ex. `Johnny`                                                                                                                                     |\n| `preferred_username` | string         | Preferred user name. Ex. `johdoe`                                                                                                                           |\n| `picture`            | base64         | A Base-64 encoded picture (typically PNG or JPEG) of the subject                                                                                            |\n| `updated_at`         | integer        | A timestamp in Unix Epoch time\\*                                                                                                                            |\n\n`*` (Seconds since January 1st 1970).\n\n### Passing the Access token as a normal Bearer token\n\nTo pass the access token to the upstream server as a normal Bearer token, configure the plugin as follows:\n\n| Key                                    | Value           |\n| -------------------------------------- | --------------- |\n| `config.access_token_header_name`      | `Authorization` |\n| `config.access_token_as_bearer`        | `yes`           |\n\n## Development\n\n### Running Unit Tests\n\nTo run unit tests, run the following command:\n\n```shell\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```shell\nexport IP=192.168.0.1\n./bin/build-env.sh\n```\n\nTo tear the environment down:\n\n```shell\n./bin/teardown-env.sh\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frevomatico%2Fkong-oidc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frevomatico%2Fkong-oidc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frevomatico%2Fkong-oidc/lists"}