diff --git a/auth.rst b/auth.rst index 6ae84a0aa..0d1f84214 100644 --- a/auth.rst +++ b/auth.rst @@ -26,13 +26,13 @@ Here are the technical details. We use `JSON Web Tokens `_ to au When a request contains a valid JWT with a role claim PostgREST will switch to the database role with that name for the duration of the HTTP request. -.. code:: postgres +.. code:: sql SET LOCAL ROLE user123; Note that the database administrator must allow the authenticator role to switch into this user by previously executing -.. code:: postgres +.. code:: sql GRANT user123 TO authenticator; @@ -50,7 +50,7 @@ PostgREST can accommodate either viewpoint. If you treat a role as a single user You can use row-level security to flexibly restrict visibility and access for the current user. Here is an `example `_ from Tomas Vondra, a chat table storing messages sent between users. Users can insert rows into it to send messages to other users, and query it to see messages sent to them by other users. -.. code:: postgres +.. code:: sql CREATE TABLE chat ( message_uuid UUID PRIMARY KEY DEFAULT uuid_generate_v4(), @@ -65,7 +65,7 @@ We want to enforce a policy that ensures a user can see only those messages sent PostgreSQL (9.5 and later) allows us to set this policy with row-level security: -.. code:: postgres +.. code:: sql CREATE POLICY chat_policy ON chat USING ((message_to = current_user) OR (message_from = current_user)) @@ -87,7 +87,7 @@ Alternately database roles can represent groups instead of (or in addition to) i SQL code can access claims through GUC variables set by PostgREST per request. For instance to get the email claim, call this function: -.. code:: postgres +.. code:: sql current_setting('request.jwt.claim.email') @@ -97,7 +97,7 @@ This allows JWT generation services to include extra information and your databa The current_setting function raises an exception if the setting in question is not present, as when a claim is missing from the JWT. Your SQL functions can either catch the exception, or you can set a default value for the database like this. - .. code:: postgres + .. code:: sql -- Prevent current_setting('request.jwt.claim.email') from raising -- an exception if the setting is not present. Default it to ''. @@ -105,7 +105,7 @@ This allows JWT generation services to include extra information and your databa If you are unable to issue an ALTER DATABASE statement (for instance on Amazon RDS), you can create a helper function to read environment variables and swallow exceptions. - .. code:: plpgsql + .. code:: sql create function env_var(v text) returns text as $$ declare @@ -130,7 +130,7 @@ Hybrid User-Group Roles There is no performance penalty for having many database roles, although roles are namespaced per-cluster rather than per-database so may be prone to collision within the database. You are free to assign a new role for every user in a web application if desired. You can mix the group and individual role policies. For instance we could still have a webuser role and individual users which inherit from it: -.. code:: postgres +.. code:: sql CREATE ROLE webuser NOLOGIN; -- grant this role access to certain tables etc @@ -158,7 +158,7 @@ Here's an example. In the config file specify a stored procedure: In the function you can run arbitrary code to check the request and raise an exception to block it if desired. -.. code:: postgres +.. code:: sql CREATE OR REPLACE FUNCTION check_user() RETURNS void LANGUAGE plpgsql @@ -193,7 +193,7 @@ You can create JWT tokens in SQL using the `pgjwt extension