{"id":46618810,"url":"https://github.com/hanlaur/oidcify","last_synced_at":"2026-03-07T21:01:01.913Z","repository":{"id":257806625,"uuid":"863319937","full_name":"hanlaur/oidcify","owner":"hanlaur","description":"Open-source OIDC plugin for Kong Gateway","archived":false,"fork":false,"pushed_at":"2026-03-01T10:49:20.000Z","size":248,"stargazers_count":20,"open_issues_count":2,"forks_count":4,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-03-01T14:44:41.304Z","etag":null,"topics":["kong","kong-plugin","oidc"],"latest_commit_sha":null,"homepage":"","language":"Go","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/hanlaur.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","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,"zenodo":null,"notice":"NOTICE","maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-09-26T05:14:46.000Z","updated_at":"2026-03-01T10:41:24.000Z","dependencies_parsed_at":"2026-01-07T19:05:46.167Z","dependency_job_id":null,"html_url":"https://github.com/hanlaur/oidcify","commit_stats":null,"previous_names":["hanlaur/oidcify","hanlaur/kong-plugin-freeoidc"],"tags_count":16,"template":false,"template_full_name":null,"purl":"pkg:github/hanlaur/oidcify","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hanlaur%2Foidcify","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hanlaur%2Foidcify/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hanlaur%2Foidcify/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hanlaur%2Foidcify/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hanlaur","download_url":"https://codeload.github.com/hanlaur/oidcify/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hanlaur%2Foidcify/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30231470,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-07T19:01:10.287Z","status":"ssl_error","status_checked_at":"2026-03-07T18:59:58.103Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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","kong-plugin","oidc"],"created_at":"2026-03-07T21:00:40.815Z","updated_at":"2026-03-07T21:01:01.902Z","avatar_url":"https://github.com/hanlaur.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# oidcify: OIDC plugin for Kong Gateway\n\nOpenID Connect (OIDC) plugin for [Kong Gateway](https://github.com/Kong/kong), written in Go using Kong Plugin Development Kit.\n\nThis project is not affiliated with or otherwise sponsored by Kong, Inc.\nThis project is not related to OpenID connect plugin by Kong, Inc.\n\n## Features\n\n* OIDC Authorization Code Flow, with PKCE support\n* Cookie-based session storage\n* Bearer token authentication based on JWT ID token\n* Sets group information in Kong context so that Kong ACL plugin can perform authorization based on groups\n* Mapping of ID token claims to HTTP headers\n\n## Required Kong version\n\nKong 3.8.0 or later. Do not use the plugin with older Kong versions.\n\n## Installation\n\nDownload the release archive from [Releases](https://github.com/hanlaur/oidcify/releases) page.\n\nPlace binary `oidcify` in `/usr/local/bin/`. \n\nSet following environment variables before starting Kong:\n\n```shell\nexport KONG_PLUGINS=\"bundled,oidcify\"\nexport KONG_PLUGINSERVER_NAMES=\"oidcify\"\nexport KONG_PLUGINSERVER_OIDCIFY_QUERY_CMD=\"/usr/local/bin/oidcify -dump\"\nexport KONG_PLUGINSERVER_OIDCIFY_START_CMD=\"/usr/local/bin/oidcify\"\n```\n\nConfigure the required configuration options for the plugin in kong plugin configuration.\n\n## Configuration\n\nPlugin supports the following configuration inputs:\n\n| Option | Description | Default Value | Required |\n| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ | -------- |\n| `issuer` | OIDC Issuer URL. Example: `https://oidc.issuer.internal/`. Will be used to formulate the URL for OIDC discovery document. Must match issuer values in the ID token. | | x |\n| `client_id` | OIDC Client ID for OIDC Authorization Code Flow. | | x |\n| `client_secret` | OIDC Client Secret. This value must be kept secret. | | x |\n| `redirect_uri` | OIDC redirect URI. For example `https://myserver.internal/cb` | | x |\n| `consumer_name` | Defines the Kong Consumer that will be set as authenticated consumer for a successful request. Example: `oidcuser`. The consumer must be defined in Kong. | | x |\n| `cookie_hash_key_hex` | Secret key used for cookie HMAC authentication. Must be cryptographically strong, 32 hex characters (256 bits). This value must be kept secret. If not set, random value is generated at startup. | randomized on startup | See note |\n| `cookie_block_key_hex` | Secret key used for cookie encryption. Must be cryptographically strong, 32 hex characters (256 bits). This value must be kept secret. If not set, random value is generated at startup. | randomized on startup | See note |\n| `ca_cert_files` | Array of PEM files to load as accepted TLS CA certificates. Example: `[\"/etc/oidcify/tlsca/internalca.pem\"]`. If not defined, then system certificate pool is used. | | |\n| `insecure_skip_verify` | Skip TLS certificate verification when communicating with OIDC provider. Skipping TLS certificate verification is not recommended as it is insecure. | false | |\n| `static_provider_config` | If defined, instead of OIDC discovery, configuration from this dictionary parameter is used. Dictionary keys: `authorization_endpoint`, `token_endpoint`, `userinfo_endpoint`, `jwks_uri`, `id_token_signing_alg_values_supported` | | |\n| `groups_claim` | Name of the ID token claim to retrieve user group memberships from. Claim must contain an array of string values. Groups are passed to other plugins via Kong context `authenticated_groups` variable. | `groups` | |\n| `scopes` | The scopes to request in the authorization code flow. You must include `openid` as one of the values. Example: `[\"openid\", \"profile\", \"email\", \"groups\"]` | `[\"openid\"]` | |\n| `use_pkce` | Use PKCE in the Authorization Code Flow. It is recommended to always use PKCE, if the OIDC provider supports it. | `true` | |\n| `use_userinfo` | Defines whether to call userinfo endpoint to collect additional claims for the purposes of `headers_from_claims` functionality. | `false` | |\n| `bearer_jwt_allowed_auds` | Allowed `aud` values when validating Authorization header Bearer token. By default Bearer JWT authentication is disabled. The `aud` may be same or different from the authorization code flow Client ID. | `[]` (no allowed ids) | |\n| `bearer_jwt_allowed_algs` | Allowed signing algorithms when validating Authorization header Bearer token. | `[\"RS256\"]` | |\n| `cookie_name` | Name prefix for OIDC session cookie. Sequence number will be appended to support cookie splitting. | `OIDCSESSION` | |\n| `session_lifetime_seconds` | Session lifetime in seconds. By default, session life time follows ID token expiry. If set, session expires based on ID token `iat` plus the configured lifetime value. Applies to auth code flow only. | `0` (use ID token value) | |\n| `redirect_unauthenticated` | Defines handling of unauthenticated HTTP requests. When set to `true`, client is redirected to OIDC authorization code flow. When set to `false`, HTTP 401 (Unauthorized) is returned. | `true` | |\n| `logout_path` | Defines path that is used to trigger logout (i.e. deletion of session cookie). | `/logout` | |\n| `post_logout_redirect_uri` | Defines URL where to redirect user after logout. If not defined, the logout path will not redirect user but instead display a message. Example: `https://myserver.internal/loggedout/` | | |\n| `headers_from_claims` | Defines rules to map ID token or Userinfo claims to HTTP headers for the upstream service. Example: `{ \"X-Oidc-Email\": \"email\" }`. | `{}` (no mappings) | |\n| `id_token_claims_header` | Defines name of header that provides all ID token claims to the upstream service as Base64 encoded JSON | | |\n| `userinfo_claims_header` | Defines name of header that provides all Userinfo claims to the upstream service as Base64 encoded JSON | | |\n| `skip_already_auth` | If set to `true`, plugin ignores (allows without authentication) requests that already have credential identifier set by higher priority auth plugin. | `false` | |\n\nNote: For sessions to survive Kong restart or work in multi-instance environment, the cookie hash and block keys must be defined. To generate random values for keys, consider: `python3 -c \"import secrets; print(secrets.token_hex(32))\"`\n\nWhen using Kong ACL plugin, set `always_use_authenticated_groups: true` in ACL plugin configuration to use the groups set by this plugin. If not set, Kong ACL plugin will use groups defined for the consumer. For more detail see Kong documentation.\n\n## Important notes\n\n* Configured `cookie_hash_key_hex` and `cookie_block_key_hex` values must be kept secret and rotated periodically. A person knowing the secrets can forge a session cookie. Also, `client_secret` should be kept secret.\n* Always use the plugin in combination with Kong ACL plugin and allow access only to defined groups. This provides additional protection layer.\n* Test your configuration carefully. This is especially important when using a combination of multiple authn/authz related plugins.\n* Access to kong logs should be protected as logs may contain security sensitive information from OIDC message exchanges.\n* Session refresh using refresh token is not supported.\n* Any changes in user profile at the provider during session life time are not reflected to the session.\n\n## Session storage\n\nSession information is stored in encrypted client-side cookie. Because there is no server side session\ndatabase, consider the following:\n\n* There is no way to end an individual session from the server side, other than waiting for the session\n to expire according to session lifetime. If required, as an emergency procedure, it is possible to invalidate all\n existing sessions by changing the cookie hash and block key in the plugin configuration.\n* Session cookie size can grow large depending on amount of data contained in OIDC tokens or OIDC UserInfo.\n The plugin automatically splits the data in multiple cookies if required, but you may need to allow larger\n size of HTTP headers in Kong and in the upstream service.\n\n## Development notes\n\n### Tests\n\nTests include both pure module tests and also integration tests with actual Kong. Integration tests require docker\ncompose environment with kong and pre-built oidcify. To run all tests:\n\n```shell\n# build oidcify\nmake\n\n# Restart the compose environment with the fresh build\ncd testenv/\ndocker compose down\ndocker compose up -d\ncd ..\n\n# wait for compose to initialize, and run tests\nmake test\n\n# shutdown compose env\ncd testenv\ndocker compose down\n```\n\n### Debugging\n\nTo run the plugin locally for development and debugging use, see example in `localenv/`. You must have kong installed\nlocally, and you must prepare `oidc.env` file that exports environment variables referenced in `kong-local.yml` that\ndefined the OIDC provider you want to use.\n\n## License information\n\nSee file [NOTICE](NOTICE) for copyright information and file [LICENSE](LICENSE) for license text.\n\n## Contributing to the project\n\nSee file [CONTRIBUTING.md](CONTRIBUTING.md) for requirements.\n\n## Dependencies\n\nUnder the hood, this project utilizes many open-source Go dependencies. See [go.mod](go.mod) for a list.\nDependency license texts are included in the release archives as collected automatically by\nthe [go-licenses](https://github.com/google/go-licenses) tool. Should any license information be missing\nfrom the archives, consult the dependency home page.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhanlaur%2Foidcify","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhanlaur%2Foidcify","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhanlaur%2Foidcify/lists"}