The Quickstart covers a basic set up that uses client-side
SecureApp to forward requests to ORY Kratos.
Systems that have more than a few components often use reverse proxies such as Nginx, Envoy, or Kong to route and authorize traffic to applications. ORY Kratos works very well in such environments. The purpose of this guide is to clarify how to use an IAP (Identity and Access Proxy) to authorize incoming requests. In this tutorial we will be using ORY Oathkeeper to achieve this.
This guide expects that you have familiarized yourself with ORY Kratos' concepts introduced in the Quickstart.
To ensure that no one can access the dashboard without prior authentication, we
are making use of our reverse proxy
(ORY Oathkeeper) denying all
unauthenticated traffic to
http://secure-app/dashboard and redirecting the
user to the login page at
http://secure-app/auth/login. Further, we will
configure access to
http://secure-app/auth/login in such a way that access
only works if one is not yet authenticated.
Running ORY Kratos and the ORY Oathkeeper Identity and Access Proxy
Clone the ORY Kratos repository and fetch the latest images:
Next, run the quickstart and add the ORY Oathkeeper config:
This might take a minute or two. Once the output slows down and logs indicate a healthy system you're ready to roll! A healthy system will show something along the lines of (the order of messages might be reversed):
There are two important factors to get a fully functional system:
- You need to make sure that ports
- Make sure to always use
127.0.0.1as the hostname; never use
localhost! This is important because browsers treat these two as separate domains and will therefore have issues with setting and using the right cookies.
This demo makes use of several services:
- Public ("Browser") API (port 4433)
- Admin API (port 4434) - This is made public only so we can test via the CLI.
- An example application written in NodeJS that implements the login, registration, logout, dashboard, and other UIs. Because we are accessing this via a proxy, its port (4435) is not publicly exposed.
- Reverse proxy (port 4455) - a reverse proxy to protect the SecureApp.
- API (port 4456) - Oathkeeper's API. This is made public only so we can test via the CLI.
- Public (port 4436) - a development SMTP server with which ORY Kratos sends emails.
To better understand the application architecture, let's take a look at the network configuration. This assumes that you have at least some understanding of how Docker networks work:
As you can see, all requests except for our demo mail server are proxied through ORY Oathkeeper.
The next diagram shows how we've configured the routes in ORY Oathkeeper:
In order to avoid common cross-domain issues with cookies, we're using ORY Oathkeeper to proxy requests to ORY Kratos' Public API so that all requests come from the same hostname.
Perform Registration, Login, and Logout
Enough theory! Let's start by opening the dashboard: go to 127.0.0.1:4455/dashboard.
Check the Quickstart for the other flows!
ORY Oathkeeper: Identity and Access Proxy
We define several configuration options for ORY Oathkeeper such as the port for the proxy and where to load the access rules from.
Cookie Session Authenticator
It's doing what the
needsLogin function did in the
The Anonymous Authenticator is useful for endpoints that do not need login, such as the registration screen:
The Allowed Authenticator simply allows all users to access the URL. Since we don't have Role-based access control (RBAC) or an Access Control list (ACL) in place for this example, this will be enough.
ID Token Mutator
ID Token Mutator
takes all the available session information and puts it into a JSON Web Token
(JWT). The protected
SecureApp will now receive
Authorization: bearer <jwt...>
in the HTTP Header instead of
The JWT is signed using a RS256 key. To verify the JWT we can use the public key provided by ORY Oathkeeper's JWKS API:
You can generate the RS256 key yourself by running
oathkeeper credentials generate --alg RS256 > id_token.jwks.json.
We also enabled the NoOp Mutator for the various other endpoints such as login and registration:
You could obviously also use other mutators such as the
Header Mutator and
use headers such as
X-User-ID instead of the JWT.
We configure the error handling in such a way that a missing or invalid login
session (when accessed from a browser) redirects to
We use glob matching to match the HTTP requests for our access rules:
access-rules.yml we define three rules. The first rule forwards all traffic
http://127.0.0.1:4455/.ory/kratos/public/ to ORY Kratos' Public API:
The second rule allows anonymous requests to the error page, website assets, login, registration, and the page for resending the verification email:
The final rule requires a valid session before allowing requests to the dashboard and user settings:
Cleaning up Docker
To clean everything up, you need to bring down the Docker Compose environment and remove all mounted volumes.