cerberauth/openapi-oathkeeper repository overview

⁠Ory Oathkeeper rules from OpenAPI

This CLI generates secure and consistent OathKeeper rules that enforce authentication and authorization policies for each API endpoint from an OpenAPI contrat.

This project automate the generation of Ory 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.

⁠Ory Oathkeeper

If you're not yet familiar with Ory Oathkeeper, Oathkeeper is an Identity & 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⁠.

⁠Get Started

To use this tool, follow the bellow instructions:

1. Pull cerberauth/openapi-oathkeeper image.
2. Provides the path to your OpenAPI contract file.
3. Then run the following command:

docker run -v ./openapi.json:/tmp/openapi.json cerberauth/openapi-oathkeeper generate -f ./openapi.json

Once 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.

⁠Configuration

As 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.

⁠Configuration File

The 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.

Every Oathkeeper rule property can be configured this way. Here are the available properties:

Below is an example of a configuration file in YAML format:

prefix: cerberauth

server_urls:
  - https://www.cerberauth.com/api
  - https://api.cerberauth.com/api

authenticators:
  openidconnect:
    handler: "jwt"
    config:
      target_audience:
      - https://api.cerberauth.com

In order to generate rules using the CLI, simply run the command in your terminal with the appropriate arguments.

docker run -v ./test:/tmp/test cerberauth/openapi-oathkeeper generate -c /tmp/test/config/sample.yaml -f /tmp/test/stub/sample.openapi.json

[
    {
        "id": "cerberauth:getUserById",
        "version": "",
        "description": "",
        "match": {
            "methods": [
                "GET"
            ],
            "url": "<^(https://www\\.cerberauth\\.com/api|https://api\\.cerberauth\\.com/api)(/users/(?:[[:alnum:]]?\\x2D?=?\\??&?_?)+/?)$>"
        },
        "authenticators": [
            {
                "handler": "jwt",
                "config": {
                    "jwks_urls": [
                        "https://console.ory.sh/.well-known/jwks.json"
                    ],
                    "required_scope": [
                        "user:read"
                    ],
                    "target_audience": [
                        "https://api.cerberauth.com"
                    ],
                    "trusted_issuers": [
                        "https://console.ory.sh"
                    ]
                }
            }
        ],
        "authorizer": {
            "handler": "allow",
            "config": null
        },
        "mutators": [
            {
                "handler": "noop",
                "config": null
            }
        ],
        "errors": [
            {
                "handler": "json",
                "config": null
            }
        ],
        "upstream": {
            "preserve_host": false,
            "strip_path": "",
            "url": ""
        }
    },
    {
        "id": "cerberauth:updateUser",
        "version": "",
        "description": "This can only be done by the logged in user.",
        "match": {
            "methods": [
                "PUT"
            ],
            "url": "<^(https://www\\.cerberauth\\.com/api|https://api\\.cerberauth\\.com/api)(/users/(?:[[:alnum:]]?\\x2D?=?\\??&?_?)+/?)$>"
        },
        "authenticators": [
            {
                "handler": "jwt",
                "config": {
                    "jwks_urls": [
                        "https://console.ory.sh/.well-known/jwks.json"
                    ],
                    "required_scope": [
                        "user:write"
                    ],
                    "target_audience": [
                        "https://api.cerberauth.com"
                    ],
                    "trusted_issuers": [
                        "https://console.ory.sh"
                    ]
                }
            }
        ],
        "authorizer": {
            "handler": "allow",
            "config": null
        },
        "mutators": [
            {
                "handler": "noop",
                "config": null
            }
        ],
        "errors": [
            {
                "handler": "json",
                "config": null
            }
        ],
        "upstream": {
            "preserve_host": false,
            "strip_path": "",
            "url": ""
        }
    }
]

⁠OpenAPI Extension

OpenAPI 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.

Here the available configurations:

⁠Command line documentation

The documentation is available as markdown files in the docs⁠ directory or by running docker run cerberauth/openapi-oathkeeper help.

⁠Roadmap

Please 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!

You can find the milestones and future enhancements planned for this tool on the project's GitHub milestones page⁠.

⁠Useful Links

• ORY Oathkeeper⁠
• OpenAPI 3.x Specification⁠

⁠License

MIT © CerberAuth⁠