From 2f231c508f3a8fe3d7fe38123cee9bd8902be709 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Yunier=20Rojas=20Garc=C3=ADa?= <yunier.rojas@gmail.com>
Date: Thu, 7 Mar 2024 21:33:12 +0100
Subject: [PATCH] feat: add docs for delegate authenticator

https://github.com/ory/oathkeeper/pull/1153 implements
a new authenticator to allow authn/authz delegation
to upstream services.

Relates to https://github.com/ory/oathkeeper/issues/1152
---
 .../oathkeeper/oathkeeper/oathkeeper.yml      |  3 +
 docs/oathkeeper/pipeline/authn.md             | 57 +++++++++++++++++--
 2 files changed, 55 insertions(+), 5 deletions(-)

diff --git a/code-examples/oathkeeper/oathkeeper/oathkeeper.yml b/code-examples/oathkeeper/oathkeeper/oathkeeper.yml
index 8e376ac78..91eb17072 100644
--- a/code-examples/oathkeeper/oathkeeper/oathkeeper.yml
+++ b/code-examples/oathkeeper/oathkeeper/oathkeeper.yml
@@ -68,6 +68,9 @@ authenticators:
   noop:
     enabled: true
 
+  delegate:
+    enabled: true
+
 authorizers:
   allow:
     enabled: true
diff --git a/docs/oathkeeper/pipeline/authn.md b/docs/oathkeeper/pipeline/authn.md
index 54d39aba7..c9ce9bb4d 100644
--- a/docs/oathkeeper/pipeline/authn.md
+++ b/docs/oathkeeper/pipeline/authn.md
@@ -54,12 +54,9 @@ are valid! If a handler encounters invalid credentials, then other handlers will
 
 ## `noop`
 
-The `noop` handler tells Ory Oathkeeper to bypass authentication, authorization, and mutation. This implies that no authorization
-will be executed and no credentials will be issued. It's basically a pass-all authenticator that allows any request to be
-forwarded to the upstream URL.
+The `noop` handler always authenticate the user, no questions asked. It applies authorization, and mutation.
 
-> Using this handler is basically an allow-all configuration. It makes sense when the upstream handles access control itself or
-> doesn't need any type of access control.
+> Using this handler is basically an allow-all configuration.
 
 ### `noop` configuration
 
@@ -215,6 +212,56 @@ The request isn't authorized because credentials have been provided but only the
 authenticator is enabled for this URL.
 ```
 
+## `delegate`
+
+The `delegate` handler tells Ory Oathkeeper to bypass authentication, authorization, and mutation. This implies that no
+authorization will be executed and no credentials will be issued. It's basically a pass-all authenticator that allows any request
+to be forwarded to the upstream URL.
+
+> Using this handler is basically an allow-all configuration. It makes sense when the upstream handles access control itself or
+> doesn't need any type of access control.
+
+### `delegate` configuration
+
+This handler isn't configurable.
+
+To enable this handler, set:
+
+```yaml
+# Global configuration file oathkeeper.yml
+authenticators:
+  delegate:
+    # Set enabled to true if the authenticator should be enabled and false to disable the authenticator. Defaults to false.
+    enabled: true
+```
+
+### `delegate` access rule example
+
+```sh
+cat ./rules.json
+
+[{
+  "id": "some-id",
+  "upstream": {
+    "url": "http://my-backend-service"
+  },
+  "match": {
+    "url": "http://my-app/some-route",
+    "methods": [
+      "GET"
+    ]
+  },
+  "authenticators": [{
+    "handler": "delegate"
+  }]
+}]
+
+curl -X GET http://my-app/some-route
+
+HTTP/1.0 200 Status OK
+The request has been allowed!
+```
+
 ## `cookie_session`
 
 The `cookie_session` authenticator will forward the request method, path and headers to a session store. If the session store