{"id":25524745,"url":"https://github.com/cerberauth/openapi-oathkeeper","last_synced_at":"2026-04-14T00:05:57.069Z","repository":{"id":147782746,"uuid":"611484700","full_name":"cerberauth/openapi-oathkeeper","owner":"cerberauth","description":"openapi-oathkeeper is a CLI for generating Ory Oathkeeper rules from an OpenAPI 3 contract and save a lot of time and effort, especially for larger projects with many endpoints or many services.","archived":false,"fork":false,"pushed_at":"2025-08-24T21:14:08.000Z","size":435,"stargazers_count":11,"open_issues_count":10,"forks_count":5,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-08-25T00:40:41.248Z","etag":null,"topics":["api-rest","authorization","cybersecurity","golang","oathkeeper","openapi","openapi3","ory","ory-oathkeeper","security","swagger"],"latest_commit_sha":null,"homepage":"https://www.cerberauth.com","language":"Go","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/cerberauth.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":["emmanuelgautier"],"buy_me_a_coffee":"emmanuelgautier"}},"created_at":"2023-03-08T23:18:03.000Z","updated_at":"2025-06-03T07:47:17.000Z","dependencies_parsed_at":"2023-05-27T12:45:09.624Z","dependency_job_id":"2608da87-d0af-45e5-8d2e-4143c0d3acb2","html_url":"https://github.com/cerberauth/openapi-oathkeeper","commit_stats":null,"previous_names":[],"tags_count":29,"template":false,"template_full_name":null,"purl":"pkg:github/cerberauth/openapi-oathkeeper","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cerberauth%2Fopenapi-oathkeeper","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cerberauth%2Fopenapi-oathkeeper/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cerberauth%2Fopenapi-oathkeeper/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cerberauth%2Fopenapi-oathkeeper/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cerberauth","download_url":"https://codeload.github.com/cerberauth/openapi-oathkeeper/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cerberauth%2Fopenapi-oathkeeper/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273754329,"owners_count":25161917,"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-05T02:00:09.113Z","response_time":402,"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":["api-rest","authorization","cybersecurity","golang","oathkeeper","openapi","openapi3","ory","ory-oathkeeper","security","swagger"],"created_at":"2025-02-19T20:05:34.492Z","updated_at":"2026-04-14T00:05:57.036Z","avatar_url":"https://github.com/cerberauth.png","language":"Go","funding_links":["https://github.com/sponsors/emmanuelgautier","https://buymeacoffee.com/emmanuelgautier"],"categories":["Projects"],"sub_categories":["Ory Oathkeeper"],"readme":"# Ory Oathkeeper rules from OpenAPI\n\n\n[![Join Discord](https://img.shields.io/discord/1242773130137833493?label=Discord\u0026style=for-the-badge)](https://www.cerberauth.com/community)\n[![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/cerberauth/openapi-oathkeeper/ci.yml?branch=main\u0026label=core%20build\u0026style=for-the-badge)](https://github.com/cerberauth/openapi-oathkeeper/actions/workflows/ci.yml)\n![Latest version](https://img.shields.io/github/v/release/cerberauth/openapi-oathkeeper?sort=semver\u0026style=for-the-badge)\n![Codecov](https://img.shields.io/codecov/c/gh/cerberauth/openapi-oathkeeper?token=BD1WPXJDAW\u0026style=for-the-badge)\n[![Go Report Card](https://goreportcard.com/badge/github.com/cerberauth/openapi-oathkeeper?style=for-the-badge)](https://goreportcard.com/report/github.com/cerberauth/openapi-oathkeeper)\n[![GoDoc reference](https://img.shields.io/badge/godoc-reference-5272B4.svg?style=for-the-badge)](https://godoc.org/github.com/cerberauth/openapi-oathkeeper)\n\nThis CLI generates OathKeeper rules that enforce authentication and authorization policies for each API endpoint from an OpenAPI file.\n\nThis project automate the generation of Oathkeeper rules from an OpenAPI contract and save a lot of time especially for larger projects with many endpoints or many services by using the existing documentation provided in an OpenAPI contract. This can improve the overall security of the API and ensure that access is granted only to authorized parties. Additionally, this tool can simplify the development process by reducing the amount of manual work required to write and maintain OathKeeper rules.\n\n## Ory Oathkeeper\n\nIf you're not yet familiar with Ory Oathkeeper, Oathkeeper is an Identity \u0026 Access Proxy (IAP) and Access Control Decision API that authorizes HTTP requests based on sets of Access Rules. You can find more information and get started with [Ory Oathkeeper](https://github.com/ory/oathkeeper).\n\n\u003e An Identity \u0026 Access Proxy is typically deployed in front of (think API Gateway or Service mesh) web-facing applications and is capable of authenticating and optionally authorizing access requests. The Access Control Decision API can be deployed alongside an existing API Gateway or reverse proxy.\n\n## Installation\n\nBelow are the instructions to install on Linux, Windows, MacOS, and Docker. You can choose the installation method that best suits your needs and environment.\n\nIf none of the installation methods below work for you, you can also download the binary from the latest [release](https://github.com/cerberauth/openapi-oathkeeper/releases).\n\n### Linux (Snap)\n\nInstall using [Snap](https://snapcraft.io/openapi-oathkeeper).\n\n```sh\nsudo snap install vulnapi\n```\n\n### MacOS (Homebrew)\n\nInstall using Homebrew.\n\n```sh\nbrew tap cerberauth/openapi-oathkeeper https://github.com/cerberauth/openapi-oathkeeper\nbrew install $(brew --repository cerberauth/openapi-oathkeeper)/openapi-oathkeeper.rb\n```\n\n## Get Started\n\nProvides the path to your OpenAPI contract file.\n\n```sh\n./openapi-oathkeeper generate -f ./openapi.json\n```\n\nOnce you have specified these options, the tool will analyze your contract and generate OathKeeper rules that enforce the specified access policies. You can then save these rules to a file to make it read by Oathkeeper.\n\nHere is an example Oathkeeper rules output from the [Petstore OpenAPI](./test/stub/petstore.openapi.json)\n\n\u003cdetails\u003e\n    \u003csummary\u003eOathkeeper rules output\u003c/summary\u003e\n\n```json\n[\n    {\n        \"id\": \"addPet\",\n        \"version\": \"\",\n        \"description\": \"Add a new pet to the store\",\n        \"match\": {\n            \"methods\": [\n                \"POST\"\n            ],\n            \"url\": \"\u003c(https://cerberauth\\\\.com/api/v3|http://swagger\\\\.io/api/v3)\u003e/pet\"\n        },\n        \"authenticators\": [\n            {\n                \"handler\": \"jwt\",\n                \"config\": {\n                    \"required_scope\": [\n                        \"write:pets\",\n                        \"read:pets\"\n                    ]\n                }\n            }\n        ],\n        \"authorizer\": {\n            \"handler\": \"allow\",\n            \"config\": null\n        },\n        \"mutators\": null,\n        \"errors\": null,\n        \"upstream\": {\n            \"preserve_host\": false,\n            \"strip_path\": \"\",\n            \"url\": \"\"\n        }\n    },\n    {\n        \"id\": \"createUser\",\n        \"version\": \"\",\n        \"description\": \"This can only be done by the logged in user.\",\n        \"match\": {\n            \"methods\": [\n                \"POST\"\n            ],\n            \"url\": \"\u003c(https://cerberauth\\\\.com/api/v3|http://swagger\\\\.io/api/v3)\u003e/user\"\n        },\n        \"authenticators\": [\n            {\n                \"handler\": \"noop\",\n                \"config\": null\n            }\n        ],\n        \"authorizer\": {\n            \"handler\": \"allow\",\n            \"config\": null\n        },\n        \"mutators\": null,\n        \"errors\": null,\n        \"upstream\": {\n            \"preserve_host\": false,\n            \"strip_path\": \"\",\n            \"url\": \"\"\n        }\n    },\n    {\n        \"id\": \"createUsersWithListInput\",\n        \"version\": \"\",\n        \"description\": \"Creates list of users with given input array\",\n        \"match\": {\n            \"methods\": [\n                \"POST\"\n            ],\n            \"url\": \"\u003c(https://cerberauth\\\\.com/api/v3|http://swagger\\\\.io/api/v3)\u003e/user/createWithList\"\n        },\n        \"authenticators\": [\n            {\n                \"handler\": \"noop\",\n                \"config\": null\n            }\n        ],\n        \"authorizer\": {\n            \"handler\": \"allow\",\n            \"config\": null\n        },\n        \"mutators\": null,\n        \"errors\": null,\n        \"upstream\": {\n            \"preserve_host\": false,\n            \"strip_path\": \"\",\n            \"url\": \"\"\n        }\n    },\n    {\n        \"id\": \"deleteOrder\",\n        \"version\": \"\",\n        \"description\": \"For valid response try integer IDs with value \u003c 1000. Anything above 1000 or nonintegers will generate API errors\",\n        \"match\": {\n            \"methods\": [\n                \"DELETE\"\n            ],\n            \"url\": \"\u003c(https://cerberauth\\\\.com/api/v3|http://swagger\\\\.io/api/v3)\u003e/store/order/\u003c\\\\d+\u003e\"\n        },\n        \"authenticators\": [\n            {\n                \"handler\": \"noop\",\n                \"config\": null\n            }\n        ],\n        \"authorizer\": {\n            \"handler\": \"allow\",\n            \"config\": null\n        },\n        \"mutators\": null,\n        \"errors\": null,\n        \"upstream\": {\n            \"preserve_host\": false,\n            \"strip_path\": \"\",\n            \"url\": \"\"\n        }\n    },\n    {\n        \"id\": \"deletePet\",\n        \"version\": \"\",\n        \"description\": \"\",\n        \"match\": {\n            \"methods\": [\n                \"DELETE\"\n            ],\n            \"url\": \"\u003c(https://cerberauth\\\\.com/api/v3|http://swagger\\\\.io/api/v3)\u003e/pet/\u003c\\\\d+\u003e\"\n        },\n        \"authenticators\": [\n            {\n                \"handler\": \"jwt\",\n                \"config\": {\n                    \"required_scope\": [\n                        \"write:pets\",\n                        \"read:pets\"\n                    ]\n                }\n            }\n        ],\n        \"authorizer\": {\n            \"handler\": \"allow\",\n            \"config\": null\n        },\n        \"mutators\": null,\n        \"errors\": null,\n        \"upstream\": {\n            \"preserve_host\": false,\n            \"strip_path\": \"\",\n            \"url\": \"\"\n        }\n    },\n    {\n        \"id\": \"deleteUser\",\n        \"version\": \"\",\n        \"description\": \"This can only be done by the logged in user.\",\n        \"match\": {\n            \"methods\": [\n                \"DELETE\"\n            ],\n            \"url\": \"\u003c(https://cerberauth\\\\.com/api/v3|http://swagger\\\\.io/api/v3)\u003e/user/\u003c.+\u003e\"\n        },\n        \"authenticators\": [\n            {\n                \"handler\": \"noop\",\n                \"config\": null\n            }\n        ],\n        \"authorizer\": {\n            \"handler\": \"allow\",\n            \"config\": null\n        },\n        \"mutators\": null,\n        \"errors\": null,\n        \"upstream\": {\n            \"preserve_host\": false,\n            \"strip_path\": \"\",\n            \"url\": \"\"\n        }\n    },\n    {\n        \"id\": \"findPetsByStatus\",\n        \"version\": \"\",\n        \"description\": \"Multiple status values can be provided with comma separated strings\",\n        \"match\": {\n            \"methods\": [\n                \"GET\"\n            ],\n            \"url\": \"\u003c(https://cerberauth\\\\.com/api/v3|http://swagger\\\\.io/api/v3)\u003e/pet/findByStatus\"\n        },\n        \"authenticators\": [\n            {\n                \"handler\": \"jwt\",\n                \"config\": {\n                    \"required_scope\": [\n                        \"write:pets\",\n                        \"read:pets\"\n                    ]\n                }\n            }\n        ],\n        \"authorizer\": {\n            \"handler\": \"allow\",\n            \"config\": null\n        },\n        \"mutators\": null,\n        \"errors\": null,\n        \"upstream\": {\n            \"preserve_host\": false,\n            \"strip_path\": \"\",\n            \"url\": \"\"\n        }\n    },\n    {\n        \"id\": \"findPetsByTags\",\n        \"version\": \"\",\n        \"description\": \"Multiple tags can be provided with comma separated strings. Use tag1, tag2, tag3 for testing.\",\n        \"match\": {\n            \"methods\": [\n                \"GET\"\n            ],\n            \"url\": \"\u003c(https://cerberauth\\\\.com/api/v3|http://swagger\\\\.io/api/v3)\u003e/pet/findByTags\"\n        },\n        \"authenticators\": [\n            {\n                \"handler\": \"jwt\",\n                \"config\": {\n                    \"required_scope\": [\n                        \"write:pets\",\n                        \"read:pets\"\n                    ]\n                }\n            }\n        ],\n        \"authorizer\": {\n            \"handler\": \"allow\",\n            \"config\": null\n        },\n        \"mutators\": null,\n        \"errors\": null,\n        \"upstream\": {\n            \"preserve_host\": false,\n            \"strip_path\": \"\",\n            \"url\": \"\"\n        }\n    },\n    {\n        \"id\": \"getInventory\",\n        \"version\": \"\",\n        \"description\": \"Returns a map of status codes to quantities\",\n        \"match\": {\n            \"methods\": [\n                \"GET\"\n            ],\n            \"url\": \"\u003c(https://cerberauth\\\\.com/api/v3|http://swagger\\\\.io/api/v3)\u003e/store/inventory\"\n        },\n        \"authenticators\": [\n            {\n                \"handler\": \"noop\",\n                \"config\": null\n            }\n        ],\n        \"authorizer\": {\n            \"handler\": \"allow\",\n            \"config\": null\n        },\n        \"mutators\": null,\n        \"errors\": null,\n        \"upstream\": {\n            \"preserve_host\": false,\n            \"strip_path\": \"\",\n            \"url\": \"\"\n        }\n    },\n    {\n        \"id\": \"getOrderById\",\n        \"version\": \"\",\n        \"description\": \"For valid response try integer IDs with value \u003c= 5 or \u003e 10. Other values will generate exceptions.\",\n        \"match\": {\n            \"methods\": [\n                \"GET\"\n            ],\n            \"url\": \"\u003c(https://cerberauth\\\\.com/api/v3|http://swagger\\\\.io/api/v3)\u003e/store/order/\u003c\\\\d+\u003e\"\n        },\n        \"authenticators\": [\n            {\n                \"handler\": \"noop\",\n                \"config\": null\n            }\n        ],\n        \"authorizer\": {\n            \"handler\": \"allow\",\n            \"config\": null\n        },\n        \"mutators\": null,\n        \"errors\": null,\n        \"upstream\": {\n            \"preserve_host\": false,\n            \"strip_path\": \"\",\n            \"url\": \"\"\n        }\n    },\n    {\n        \"id\": \"getPetById\",\n        \"version\": \"\",\n        \"description\": \"Returns a single pet\",\n        \"match\": {\n            \"methods\": [\n                \"GET\"\n            ],\n            \"url\": \"\u003c(https://cerberauth\\\\.com/api/v3|http://swagger\\\\.io/api/v3)\u003e/pet/\u003c\\\\d+\u003e\"\n        },\n        \"authenticators\": [\n            {\n                \"handler\": \"jwt\",\n                \"config\": {\n                    \"required_scope\": [\n                        \"write:pets\",\n                        \"read:pets\"\n                    ]\n                }\n            }\n        ],\n        \"authorizer\": {\n            \"handler\": \"allow\",\n            \"config\": null\n        },\n        \"mutators\": null,\n        \"errors\": null,\n        \"upstream\": {\n            \"preserve_host\": false,\n            \"strip_path\": \"\",\n            \"url\": \"\"\n        }\n    },\n    {\n        \"id\": \"getUserByName\",\n        \"version\": \"\",\n        \"description\": \"\",\n        \"match\": {\n            \"methods\": [\n                \"GET\"\n            ],\n            \"url\": \"\u003c(https://cerberauth\\\\.com/api/v3|http://swagger\\\\.io/api/v3)\u003e/user/\u003c.+\u003e\"\n        },\n        \"authenticators\": [\n            {\n                \"handler\": \"noop\",\n                \"config\": null\n            }\n        ],\n        \"authorizer\": {\n            \"handler\": \"allow\",\n            \"config\": null\n        },\n        \"mutators\": null,\n        \"errors\": null,\n        \"upstream\": {\n            \"preserve_host\": false,\n            \"strip_path\": \"\",\n            \"url\": \"\"\n        }\n    },\n    {\n        \"id\": \"loginUser\",\n        \"version\": \"\",\n        \"description\": \"\",\n        \"match\": {\n            \"methods\": [\n                \"GET\"\n            ],\n            \"url\": \"\u003c(https://cerberauth\\\\.com/api/v3|http://swagger\\\\.io/api/v3)\u003e/user/login\"\n        },\n        \"authenticators\": [\n            {\n                \"handler\": \"noop\",\n                \"config\": null\n            }\n        ],\n        \"authorizer\": {\n            \"handler\": \"allow\",\n            \"config\": null\n        },\n        \"mutators\": null,\n        \"errors\": null,\n        \"upstream\": {\n            \"preserve_host\": false,\n            \"strip_path\": \"\",\n            \"url\": \"\"\n        }\n    },\n    {\n        \"id\": \"logoutUser\",\n        \"version\": \"\",\n        \"description\": \"\",\n        \"match\": {\n            \"methods\": [\n                \"GET\"\n            ],\n            \"url\": \"\u003c(https://cerberauth\\\\.com/api/v3|http://swagger\\\\.io/api/v3)\u003e/user/logout\"\n        },\n        \"authenticators\": [\n            {\n                \"handler\": \"noop\",\n                \"config\": null\n            }\n        ],\n        \"authorizer\": {\n            \"handler\": \"allow\",\n            \"config\": null\n        },\n        \"mutators\": null,\n        \"errors\": null,\n        \"upstream\": {\n            \"preserve_host\": false,\n            \"strip_path\": \"\",\n            \"url\": \"\"\n        }\n    },\n    {\n        \"id\": \"placeOrder\",\n        \"version\": \"\",\n        \"description\": \"Place a new order in the store\",\n        \"match\": {\n            \"methods\": [\n                \"POST\"\n            ],\n            \"url\": \"\u003c(https://cerberauth\\\\.com/api/v3|http://swagger\\\\.io/api/v3)\u003e/store/order\"\n        },\n        \"authenticators\": [\n            {\n                \"handler\": \"noop\",\n                \"config\": null\n            }\n        ],\n        \"authorizer\": {\n            \"handler\": \"allow\",\n            \"config\": null\n        },\n        \"mutators\": null,\n        \"errors\": null,\n        \"upstream\": {\n            \"preserve_host\": false,\n            \"strip_path\": \"\",\n            \"url\": \"\"\n        }\n    },\n    {\n        \"id\": \"updatePet\",\n        \"version\": \"\",\n        \"description\": \"Update an existing pet by Id\",\n        \"match\": {\n            \"methods\": [\n                \"PUT\"\n            ],\n            \"url\": \"\u003c(https://cerberauth\\\\.com/api/v3|http://swagger\\\\.io/api/v3)\u003e/pet\"\n        },\n        \"authenticators\": [\n            {\n                \"handler\": \"jwt\",\n                \"config\": {\n                    \"required_scope\": [\n                        \"write:pets\",\n                        \"read:pets\"\n                    ]\n                }\n            }\n        ],\n        \"authorizer\": {\n            \"handler\": \"allow\",\n            \"config\": null\n        },\n        \"mutators\": null,\n        \"errors\": null,\n        \"upstream\": {\n            \"preserve_host\": false,\n            \"strip_path\": \"\",\n            \"url\": \"\"\n        }\n    },\n    {\n        \"id\": \"updatePetWithForm\",\n        \"version\": \"\",\n        \"description\": \"\",\n        \"match\": {\n            \"methods\": [\n                \"POST\"\n            ],\n            \"url\": \"\u003c(https://cerberauth\\\\.com/api/v3|http://swagger\\\\.io/api/v3)\u003e/pet/\u003c\\\\d+\u003e\"\n        },\n        \"authenticators\": [\n            {\n                \"handler\": \"jwt\",\n                \"config\": {\n                    \"required_scope\": [\n                        \"write:pets\",\n                        \"read:pets\"\n                    ]\n                }\n            }\n        ],\n        \"authorizer\": {\n            \"handler\": \"allow\",\n            \"config\": null\n        },\n        \"mutators\": null,\n        \"errors\": null,\n        \"upstream\": {\n            \"preserve_host\": false,\n            \"strip_path\": \"\",\n            \"url\": \"\"\n        }\n    },\n    {\n        \"id\": \"updateUser\",\n        \"version\": \"\",\n        \"description\": \"This can only be done by the logged in user.\",\n        \"match\": {\n            \"methods\": [\n                \"PUT\"\n            ],\n            \"url\": \"\u003c(https://cerberauth\\\\.com/api/v3|http://swagger\\\\.io/api/v3)\u003e/user/\u003c.+\u003e\"\n        },\n        \"authenticators\": [\n            {\n                \"handler\": \"noop\",\n                \"config\": null\n            }\n        ],\n        \"authorizer\": {\n            \"handler\": \"allow\",\n            \"config\": null\n        },\n        \"mutators\": null,\n        \"errors\": null,\n        \"upstream\": {\n            \"preserve_host\": false,\n            \"strip_path\": \"\",\n            \"url\": \"\"\n        }\n    },\n    {\n        \"id\": \"uploadFile\",\n        \"version\": \"\",\n        \"description\": \"\",\n        \"match\": {\n            \"methods\": [\n                \"POST\"\n            ],\n            \"url\": \"\u003c(https://cerberauth\\\\.com/api/v3|http://swagger\\\\.io/api/v3)\u003e/pet/\u003c\\\\d+\u003e/uploadImage\"\n        },\n        \"authenticators\": [\n            {\n                \"handler\": \"jwt\",\n                \"config\": {\n                    \"required_scope\": [\n                        \"write:pets\",\n                        \"read:pets\"\n                    ]\n                }\n            }\n        ],\n        \"authorizer\": {\n            \"handler\": \"allow\",\n            \"config\": null\n        },\n        \"mutators\": null,\n        \"errors\": null,\n        \"upstream\": {\n            \"preserve_host\": false,\n            \"strip_path\": \"\",\n            \"url\": \"\"\n        }\n    }\n]\n```\n\u003c/details\u003e\n\n## Configuration\n\nAs the authenticator rule may require additional information in order to make authorization and authentication working properly, additional information can be passed either by OpenAPI Extensions or configuration file.\n\n### Configuration File\n\nThe recommended approach involves using dedicated configuration files for your Oathkeeper rules. These configuration files provide a more flexible and user-friendly way of managing your security settings.\n\nEvery Oathkeeper rule property can be configured this way. Here are the available properties:\n\n| Field          | Type                                                                               | Key              |\n|----------------|------------------------------------------------------------------------------------|------------------|\n| Prefix         | string                                                                             | \"prefix\"         |\n| ServerUrls     | []string                                                                           | \"server_urls\"    |\n| Upstream       | [Upstream](https://www.ory.sh/docs/oathkeeper/api-access-rules#access-rule-format) | \"upstream\"       |\n| Authenticators | Map of [Authenticators](https://www.ory.sh/docs/oathkeeper/pipeline/authn)         | \"authenticators\" |\n| Authorizer     | [Authorization Handler](https://www.ory.sh/docs/oathkeeper/pipeline/authz)         | \"authorizer\"     |\n| Mutators       | Array [of Mutator Handlers](https://www.ory.sh/docs/oathkeeper/pipeline/mutator)   | \"mutators\"       |\n| Errors         | Array of [Error Handlers](https://www.ory.sh/docs/oathkeeper/pipeline/error)       | \"errors\"         |\n\nBelow is an example of a configuration file in YAML format:\n\n```yaml\nprefix: cerberauth\n\nserver_urls:\n  - https://www.cerberauth.com/api\n  - https://api.cerberauth.com/api\n\nauthenticators:\n  openidconnect:\n    handler: \"jwt\"\n    config:\n      target_audience:\n      - https://api.cerberauth.com\n```\n\nIn order to generate rules using the CLI, simply run the command in your terminal with the appropriate arguments.\n\n```shell\n./openapi-oathkeeper generate -c ./test/config/sample.yaml -f ./test/stub/sample.openapi.json\n```\n\n\u003cdetails\u003e\n  \u003csummary\u003eOathkeeper rules output\u003c/summary\u003e\n\n```json\n[\n    {\n        \"id\": \"cerberauth:getUserById\",\n        \"version\": \"\",\n        \"description\": \"\",\n        \"match\": {\n            \"methods\": [\n                \"GET\"\n            ],\n            \"url\": \"\u003c^(https://www\\\\.cerberauth\\\\.com/api|https://api\\\\.cerberauth\\\\.com/api)(/users/(?:[[:alnum:]]?\\\\x2D?=?\\\\??\u0026?_?)+/?)$\u003e\"\n        },\n        \"authenticators\": [\n            {\n                \"handler\": \"jwt\",\n                \"config\": {\n                    \"jwks_urls\": [\n                        \"https://console.ory.sh/.well-known/jwks.json\"\n                    ],\n                    \"required_scope\": [\n                        \"user:read\"\n                    ],\n                    \"target_audience\": [\n                        \"https://api.cerberauth.com\"\n                    ],\n                    \"trusted_issuers\": [\n                        \"https://console.ory.sh\"\n                    ]\n                }\n            }\n        ],\n        \"authorizer\": {\n            \"handler\": \"allow\",\n            \"config\": null\n        },\n        \"mutators\": [\n            {\n                \"handler\": \"noop\",\n                \"config\": null\n            }\n        ],\n        \"errors\": [\n            {\n                \"handler\": \"json\",\n                \"config\": null\n            }\n        ],\n        \"upstream\": {\n            \"preserve_host\": false,\n            \"strip_path\": \"\",\n            \"url\": \"\"\n        }\n    },\n    {\n        \"id\": \"cerberauth:updateUser\",\n        \"version\": \"\",\n        \"description\": \"This can only be done by the logged in user.\",\n        \"match\": {\n            \"methods\": [\n                \"PUT\"\n            ],\n            \"url\": \"\u003c^(https://www\\\\.cerberauth\\\\.com/api|https://api\\\\.cerberauth\\\\.com/api)(/users/(?:[[:alnum:]]?\\\\x2D?=?\\\\??\u0026?_?)+/?)$\u003e\"\n        },\n        \"authenticators\": [\n            {\n                \"handler\": \"jwt\",\n                \"config\": {\n                    \"jwks_urls\": [\n                        \"https://console.ory.sh/.well-known/jwks.json\"\n                    ],\n                    \"required_scope\": [\n                        \"user:write\"\n                    ],\n                    \"target_audience\": [\n                        \"https://api.cerberauth.com\"\n                    ],\n                    \"trusted_issuers\": [\n                        \"https://console.ory.sh\"\n                    ]\n                }\n            }\n        ],\n        \"authorizer\": {\n            \"handler\": \"allow\",\n            \"config\": null\n        },\n        \"mutators\": [\n            {\n                \"handler\": \"noop\",\n                \"config\": null\n            }\n        ],\n        \"errors\": [\n            {\n                \"handler\": \"json\",\n                \"config\": null\n            }\n        ],\n        \"upstream\": {\n            \"preserve_host\": false,\n            \"strip_path\": \"\",\n            \"url\": \"\"\n        }\n    }\n]\n```\n\u003c/details\u003e\n\n### OpenAPI Extension\n\nOpenAPI Extensions serve as an extension mechanism for the OpenAPI Specification (OAS). When using OpenAPI-Oathkeeper with OpenAPI Extensions, you can embed Oathkeeper-specific rules directly within your API documentation. This integration can be beneficial when you desire a unified source of truth for both API specifications and security rules.\n\nHere the available configurations:\n\n| Name     | Security Schemes                  | OpenAPI Extension Name     |\n|----------|-----------------------------------|----------------------------|\n| JWKS URI | `oauth2`, `http`                  | `x-authenticator-jwks-uri` |\n| Issuer   | `oauth2`, `http`                  | `x-authenticator-issuer`   |\n| Audience | `openIdConnect`, `oauth2`, `http` | `x-authenticator-audience` |\n\n### Example\n\nHere's an example of the same OpenAPI contract but in JSON format\n\n\u003cdetails\u003e\n  \u003csummary\u003eOpenAPI example using OpenAPI Extensions\u003c/summary\u003e\n\n```json sample.openapi.json\n{\n    \"openapi\": \"3.0.0\",\n    \"info\": {\n        \"title\": \"My API\",\n        \"version\": \"1.0.0\"\n    },\n    \"servers\": [\n        {\n            \"url\": \"https://api.example.com\",\n            \"description\": \"Production server\"\n        }\n    ],\n    \"paths\": {\n        \"/users/{id}\": {\n            \"get\": {\n                \"summary\": \"Get user by ID\",\n                \"operationId\": \"getUserById\",\n                \"parameters\": [\n                    {\n                        \"name\": \"id\",\n                        \"in\": \"path\",\n                        \"description\": \"The user id. \",\n                        \"required\": true,\n                        \"schema\": {\n                            \"type\": \"string\"\n                        }\n                    }\n                ],\n                \"responses\": {\n                    \"200\": {\n                        \"description\": \"Successful response\",\n                        \"content\": {\n                            \"application/json\": {\n                                \"schema\": {\n                                    \"type\": \"object\",\n                                    \"properties\": {\n                                        \"id\": {\n                                            \"type\": \"integer\"\n                                        },\n                                        \"email\": {\n                                            \"type\": \"string\"\n                                        }\n                                    }\n                                }\n                            }\n                        }\n                    }\n                },\n                \"security\": [\n                    {\n                        \"openidconnect\": [\n                            \"user:read\"\n                        ]\n                    }\n                ]\n            },\n            \"put\": {\n                \"tags\": [\n                    \"user\"\n                ],\n                \"summary\": \"Update user\",\n                \"description\": \"This can only be done by the logged in user.\",\n                \"operationId\": \"updateUser\",\n                \"parameters\": [\n                    {\n                        \"name\": \"id\",\n                        \"in\": \"path\",\n                        \"description\": \"user id that need to be updated\",\n                        \"required\": true,\n                        \"schema\": {\n                            \"type\": \"string\"\n                        }\n                    }\n                ],\n                \"requestBody\": {\n                    \"description\": \"Update an existent user in the store\",\n                    \"content\": {\n                        \"application/json\": {\n                            \"schema\": {\n                                \"$ref\": \"#/components/schemas/User\"\n                            }\n                        }\n                    }\n                },\n                \"responses\": {\n                    \"default\": {\n                        \"description\": \"successful operation\"\n                    }\n                },\n                \"security\": [\n                    {\n                        \"openidconnect\": [\n                            \"user:write\"\n                        ]\n                    }\n                ]\n            }\n        }\n    },\n    \"components\": {\n        \"schemas\": {\n            \"User\": {\n                \"type\": \"object\",\n                \"properties\": {\n                    \"id\": {\n                        \"type\": \"integer\",\n                        \"format\": \"int64\",\n                        \"example\": 10\n                    },\n                    \"email\": {\n                        \"type\": \"string\",\n                        \"example\": \"john@email.com\"\n                    }\n                }\n            }\n        },\n        \"securitySchemes\": {\n            \"openidconnect\": {\n                \"type\": \"openIdConnect\",\n                \"openIdConnectUrl\": \"https://project.console.ory.sh/.well-known/openid-configuration\"\n            }\n        }\n    }\n}\n```\n\u003c/details\u003e\n\n### Command line documentation\n\nThe documentation is available as markdown files in the [docs](./docs/openapi-oathkeeper.md) directory or by running `openapi-oathkeeper help`.\n\n## Telemetry\n\nThe scanner collects anonymous usage data to help improve the tool. This data includes the number of scans performed, number of detected vulnerabilities, and the severity of vulnerabilities. No sensitive information is collected. You can opt-out of telemetry by passing the `--sqa-opt-out` flag.\n\n## Roadmap\n\nPlease note that this tool is currently in beta stage and there may be limitations and bugs. Improvements and new features should come to make it more powerful and useful for developers. Any feedback or suggestions are greatly appreciated!\n\nYou can find the milestones and future enhancements planned for this tool on the project's [GitHub milestones page]((https://github.com/cerberauth/openapi-oathkeeper/milestones)).\n\n## Useful Links\n\n- [ORY Oathkeeper](https://github.com/ory/oathkeeper)\n- [OpenAPI 3.x Specification](https://swagger.io/specification/)\n\n## License\n\nMIT © [CerberAuth](https://www.cerberauth.com)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcerberauth%2Fopenapi-oathkeeper","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcerberauth%2Fopenapi-oathkeeper","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcerberauth%2Fopenapi-oathkeeper/lists"}