From d00bb026b6e3bcf13cdb4746d4877f19cace0f01 Mon Sep 17 00:00:00 2001
From: Joe Nelson <cred+github@begriffs.com>
Date: Sat, 15 Oct 2016 18:14:50 -0700
Subject: [PATCH] pre-request function docs

---
 auth.rst | 52 +++++++++++++++++++++++++++++++++++++++++++++-------
 1 file changed, 45 insertions(+), 7 deletions(-)

diff --git a/auth.rst b/auth.rst
index 9ddbc23a6..cce349238 100644
--- a/auth.rst
+++ b/auth.rst
@@ -3,11 +3,11 @@ Overview of Role System
 
 PostgREST is designed to keep the database at the center of API security. All authorization happens through database roles and permissions. It is PostgREST's job to authenticate requests -- i.e. verify that a client is who they say they are -- and then let the database authorize client actions.
 
-There are three *types* of roles used by PostgREST, the **authenticator**, **anonymous** and **user** roles. The database administrator creates these roles and configures PostgREST to use them.
+There are three types of roles used by PostgREST, the **authenticator**, **anonymous** and **user** roles. The database administrator creates these roles and configures PostgREST to use them.
 
 .. image:: _static/security-roles.png
 
-The authenticator should be configured in the db to have very limited access. It is a chameleon whose job is to "become" other users to service authenticated HTTP requests. The picture below shows how the server handles authentication. If auth succeeds, it switches into the user role specified by the request, otherwise it switches into the anonymous role.
+The authenticator should be configured in the database to have very limited access. It is a chameleon whose job is to "become" other users to service authenticated HTTP requests. The picture below shows how the server handles authentication. If auth succeeds, it switches into the user role specified by the request, otherwise it switches into the anonymous role.
 
 .. image:: _static/security-anon-choice.png
 
@@ -31,17 +31,55 @@ Note that the database administrator must allow the authenticator role to switch
 
   GRANT user123 TO authenticator;
 
-If the client included no JWT (or one without a role claim) then PostgREST switches into the anonymous role whos actual database-specific name, like that of with the authenticator role, is specified in the PostgREST server configuration file.
+If the client included no JWT (or one without a role claim) then PostgREST switches into the anonymous role whos actual database-specific name, like that of with the authenticator role, is specified in the PostgREST server configuration file. The database administrator must set anonymous role permissions correctly to prevent anonymous users from seeing or changing things they shouldn't.
+
+Custom Authentication
+---------------------
+
+PostgREST honors the `exp` claim for token expiration, rejecting expired tokens. However it does not enforce any extra constraints. An example of an extra constraint would be to immediately revoke access for a certain user. The configuration file paramter `pre-request` specifies a stored procedure to call immediately after the authenticator switches into a new role and before the main query itself runs.
+
+Here's an example. In the config file specify a stored procedure:
+
+.. code::
+
+  pre-request = "public.check_user"
+
+In the function you can run arbitrary code to check the request and raise an exception to block it if desired.
+
+.. code:: sql
+
+  CREATE OR REPLACE FUNCTION check_user() RETURNS void
+    LANGUAGE plpgsql
+    AS $$
+  BEGIN
+    IF current_role = 'evil_user' THEN
+      RAISE EXCEPTION 'No, you are evil'
+        USING HINT = 'Stop being so evil and maybe you can log in';
+    END IF;
+  END
+  $$;
+
+Client Auth
+===========
+
+To make an authenticated request the client must include an `Authorization` HTTP header with the value `Bearer <jwt>`. For instance:
+
+.. code:: http
+
+  GET /foo
+  Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyb2xlIjoiamRvZSIsImV4cCI6MTQ3NTUxNjI1MH0.GYDZV3yM0gqvuEtJmfpplLBXSGYnke_Pvnl0tbKAjB4
+
+JWT Generation
+==============
 
-JSON Web Tokens
-===============
 
-Internal Generation
--------------------
 
 External Generation
 -------------------
 
+Internal Generation
+-------------------
+
 SSL
 ===