The ORY Oathkeeper HTTP serve process
oathkeeper serve opens two ports
- reverse proxy
- REST API which serves the Access Control Decision API as well as other API endpoints such as health checks, JSON Web Key Sets, and a list of available rules.
For this guide we are using Docker. ORY Oathkeeper however can be installed in a variety of ways.
ORY Oathkeeper can be configured via the filesystem as well as environment variables. For more information on mapping the keys to environment variables please head over to the configuration chapter.
First, create an empty directory and
cd into it:
Create a file called
config.yaml with the following content:
This configuration file will run the proxy at port 4455, the api at port 4456, and enable the anonymous authenticator, the allow and deny authorizers, and the noop and id_token mutators.
We will be using httpbin.org as the upstream server. The service echoes incoming HTTP Requests and is perfect for seeing how ORY Oathkeeper works. Let's define three rules:
- An access rule that allowing anonymous access to
https://httpbin.org/anything/headerand using the
- An access rule denying every access to
https://httpbin.org/anything/deny. If the request header has
Accept: application/json, we will receive a JSON response. If however the accept header has
Accept: text/*, a HTTP Redirect will be sent (to
https://www.ory.sh/docsas configured above).
- An access rule allowing anonymous access to
id_token mutator creates a signed JSON Web Token. For that to work, a
public/private key is required. Luckily, ORY Oathkeeper can assist you in
creating such keys. All common JWT algorithms are supported (RS256, ES256,
HS256, ...). Let's generate a key for the RS256 algorithm that will be used by
the id_token mutator:
Next we will be creating a custom Docker Image that adds these configuration files to the image:
We are doing this for demonstration purposes only. In a production environment you would separate these configuration values from the build artifact itself. In Kuberentes, it would make most sense to provide the JSON Web Keys as a Kubernetes Secret mounted as in a directory, for example.
We encourage you to check out our helm charts which apply these best practices.
Before building the Docker Image, we need to make sure that the local ORY Oathkeeper Docker Image is on the most recent version:
Next we will build our custom Docker Image
and run it
Let's open a new terminal and check if it is alive:
Let's also check if the rules have been imported properly:
Everything is up and running and configured! Let's make some requests:
That's it! You can now clean up the demo using:
Oathkeeper provides an endpoint for Prometheus to scrape as a target. This endpoint can be accessed by default at: http://localhost:9000/metrics:
You can adjust the settings within Oathkeeper's config.
Prometheus can easily be run as a docker container. More information are available on https://github.com/prometheus/prometheus. Start with setting up a prometheus configuration:
Then start the prometheus server and access it on http://localhost:9090.
Now where you have a basic monitoring setup running you can extend it by building up nice visualizations eg. using Grafana. More information are available on https://prometheus.io/docs/visualization/grafana/.
We have a pre built Dashboard which you can use to get started quickly: Oathkeeper-Dashboard.json.