Document long jwt secrets as required (#109)
* Use long jwt secrets as required * Fix spelling and adjust custom dictionary
This commit is contained in:
Joe Nelson
@@ -116,7 +116,7 @@ Next we apply the zone to certain routes, like a hypothetical stored procedure c
|
||||
|
||||
The burst argument tells Nginx to start dropping requests if more than five queue up from a specific IP.
|
||||
|
||||
Nginx rate limiting is general and indescriminate. To rate limit each authenticated request individually you will need to add logic in a :ref:`Custom Validation <custom_validation>` function.
|
||||
Nginx rate limiting is general and indiscriminate. To rate limit each authenticated request individually you will need to add logic in a :ref:`Custom Validation <custom_validation>` function.
|
||||
|
||||
Debugging
|
||||
=========
|
||||
|
||||
@@ -47,9 +47,9 @@ Complex logic can also be applied:
|
||||
|
||||
These operators are available:
|
||||
|
||||
============ =============================================== ===================
|
||||
Abbreviation Meaning Postgres Equivalent
|
||||
============ =============================================== ===================
|
||||
============ =============================================== =====================
|
||||
Abbreviation Meaning PostgreSQL Equivalent
|
||||
============ =============================================== =====================
|
||||
eq equals :code:`=`
|
||||
gt greater than :code:`>`
|
||||
gte greater than or equal :code:`>=`
|
||||
@@ -75,7 +75,7 @@ nxr does not extend to the right of, :code:`&<`
|
||||
nxl does not extend to the left of :code:`&>`
|
||||
adj is adjacent to, e.g. :code:`?range=adj.(1,10)` :code:`-|-`
|
||||
not negates another operator, see below :code:`NOT`
|
||||
============ =============================================== ===================
|
||||
============ =============================================== =====================
|
||||
|
||||
.. note::
|
||||
|
||||
@@ -131,7 +131,7 @@ Using phrase search mode requires PostgreSQL of version at least 9.6 and will ra
|
||||
Vertical Filtering (Columns)
|
||||
----------------------------
|
||||
|
||||
When certain columns are wide (such as those holding binary data), it is more efficient for the server to withold them in a response. The client can specify which columns are required using the :sql:`select` parameter.
|
||||
When certain columns are wide (such as those holding binary data), it is more efficient for the server to withhold them in a response. The client can specify which columns are required using the :sql:`select` parameter.
|
||||
|
||||
.. code-block:: http
|
||||
|
||||
@@ -434,7 +434,7 @@ Which would return
|
||||
]
|
||||
|
||||
The primary key of the table of the resource being embedded must be specified,
|
||||
either explicitly, like in the example above, or implicitly through a wildcard.
|
||||
either explicitly, like in the example above, or implicitly through a wild card.
|
||||
|
||||
In this example, since the relationship is a forward relationship, there is
|
||||
only one director associated with a film. As the table name is plural it might
|
||||
@@ -487,7 +487,7 @@ The PostgREST URL grammar limits the kinds of queries clients can perform. It pr
|
||||
|
||||
* Table unions
|
||||
* More complicated joins than those provided by `Resource Embedding`_
|
||||
* Geospatial queries that require an argument, like "points near (lat,lon)"
|
||||
* Geo-spatial queries that require an argument, like "points near (lat,lon)"
|
||||
* More sophisticated full-text search than a simple use of the :sql:`fts` filter
|
||||
|
||||
Stored Procedures
|
||||
@@ -635,7 +635,7 @@ Updates also support :code:`Prefer: return=representation` plus :ref:`v_filter`.
|
||||
Bulk Insert
|
||||
-----------
|
||||
|
||||
Bulk insert works exactly like single row insert except that you provide either a JSON array of objects having uniform keys, or lines in CSV format. This not only minimizes the HTTP requests required but uses a single INSERT statement on the backend for efficiency. Note that using CSV requires less parsing on the server and is much faster.
|
||||
Bulk insert works exactly like single row insert except that you provide either a JSON array of objects having uniform keys, or lines in CSV format. This not only minimizes the HTTP requests required but uses a single INSERT statement on the back-end for efficiency. Note that using CSV requires less parsing on the server and is much faster.
|
||||
|
||||
To bulk insert CSV simply post to a table route with :code:`Content-Type: text/csv` and include the names of the columns as the first row. For instance
|
||||
|
||||
@@ -726,7 +726,7 @@ PostgREST translates `PostgreSQL error codes <https://www.postgresql.org/docs/cu
|
||||
+--------------------------+-------------------------+---------------------------------+
|
||||
| 54* | 413 | too complex |
|
||||
+--------------------------+-------------------------+---------------------------------+
|
||||
| 55* | 500 | obj not in prereq state |
|
||||
| 55* | 500 | obj not in prerequisite state |
|
||||
+--------------------------+-------------------------+---------------------------------+
|
||||
| 57* | 500 | operator intervention |
|
||||
+--------------------------+-------------------------+---------------------------------+
|
||||
@@ -746,7 +746,8 @@ PostgREST translates `PostgreSQL error codes <https://www.postgresql.org/docs/cu
|
||||
+--------------------------+-------------------------+---------------------------------+
|
||||
| 42P01 | 404 | undefined table |
|
||||
+--------------------------+-------------------------+---------------------------------+
|
||||
| 42501 | if authed 403, else 401 | insufficient privileges |
|
||||
| 42501 | | if authenticated 403, | insufficient privileges |
|
||||
| | | else 401 | |
|
||||
+--------------------------+-------------------------+---------------------------------+
|
||||
| other | 500 | |
|
||||
+--------------------------+-------------------------+---------------------------------+
|
||||
|
||||
@@ -171,7 +171,7 @@ Next write a stored procedure that returns the token. The one below returns a to
|
||||
LANGUAGE sql
|
||||
AS $$
|
||||
SELECT sign(
|
||||
row_to_json(r), 'mysecret'
|
||||
row_to_json(r), 'reallyreallyreallyreallyverysafe'
|
||||
) AS token
|
||||
FROM (
|
||||
SELECT
|
||||
@@ -189,7 +189,7 @@ PostgREST exposes this function to clients via a POST request to `/rpc/jwt_test`
|
||||
.. code-block:: postgres
|
||||
|
||||
-- run this once
|
||||
ALTER DATABASE mydb SET "app.jwt_secret" TO '!!secret!!';
|
||||
ALTER DATABASE mydb SET "app.jwt_secret" TO 'reallyreallyreallyreallyverysafe';
|
||||
|
||||
-- then all functions can refer to app.jwt_secret
|
||||
SELECT sign(
|
||||
@@ -364,7 +364,7 @@ In the previous section we created an internal table to store user information.
|
||||
Logins
|
||||
~~~~~~
|
||||
|
||||
As described in `JWT from SQL`_, we'll create a JWT inside our login function. Note that you'll need to adjust the secret key which is hard-coded in this example to a secure secret of your choosing.
|
||||
As described in `JWT from SQL`_, we'll create a JWT inside our login function. Note that you'll need to adjust the secret key which is hard-coded in this example to a secure (at least thirty-two character) secret of your choosing.
|
||||
|
||||
.. code:: plpgsql
|
||||
|
||||
@@ -383,7 +383,7 @@ As described in `JWT from SQL`_, we'll create a JWT inside our login function. N
|
||||
end if;
|
||||
|
||||
select sign(
|
||||
row_to_json(r), 'mysecret'
|
||||
row_to_json(r), 'reallyreallyreallyreallyverysafe'
|
||||
) as token
|
||||
from (
|
||||
select _role as role, login.email as email,
|
||||
@@ -402,12 +402,12 @@ An API request to call this function would look like:
|
||||
|
||||
{ "email": "foo@bar.com", "pass": "foobar" }
|
||||
|
||||
The response would look like the snippet below. Try decoding the token at `jwt.io <https://jwt.io/>`_. (It was encoded with a secret of :code:`mysecret` as specified in the SQL code above. You'll want to change this secret in your app!)
|
||||
The response would look like the snippet below. Try decoding the token at `jwt.io <https://jwt.io/>`_. (It was encoded with a secret of :code:`reallyreallyreallyreallyverysafe` as specified in the SQL code above. You'll want to change this secret in your app!)
|
||||
|
||||
.. code:: json
|
||||
|
||||
{
|
||||
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJlbWFpbCI6ImZvb0BiYXIuY29tIiwicm9sZSI6ImF1dGhvciJ9.fpf3_ERi5qbWOE5NPzvauJgvulm0zkIG9xSm2w5zmdw"
|
||||
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJlbWFpbCI6ImZvb0BiYXIuY29tIiwicGFzcyI6ImZvb2JhciJ9.37066TTRlh-1hXhnA9oO9Pj6lgL6zFuJU0iCHhuCFno"
|
||||
}
|
||||
|
||||
Permissions
|
||||
|
||||
+8
-8
@@ -3,7 +3,7 @@ Binary Release
|
||||
|
||||
[ `Download from release page <https://github.com/begriffs/postgrest/releases/latest>`_ ]
|
||||
|
||||
The release page has precompiled binaries for Mac OS X, Windows, and several Linux distros. Extract the tarball and run the binary inside with the :code:`--help` flag to see usage instructions:
|
||||
The release page has pre-compiled binaries for Mac OS X, Windows, and several Linux distributions. Extract the tarball and run the binary inside with the :code:`--help` flag to see usage instructions:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
@@ -122,7 +122,7 @@ server-proxy-uri
|
||||
}
|
||||
|
||||
jwt-secret
|
||||
The secret or `JSON Web Key (JWK) <https://tools.ietf.org/html/rfc7517>`_ used to decode JWT tokens clients provide for authentication. If this parameter is not specified then PostgREST refuses authentication requests. Choosing a value for this parameter beginning with the at sign such as :code:`@filename` loads the secret out of an external file. This is useful for automating deployments. Note that any binary secrets must be base64 encoded.
|
||||
The secret or `JSON Web Key (JWK) <https://tools.ietf.org/html/rfc7517>`_ used to decode JWT tokens clients provide for authentication. For security the key must be at least thirty-two characters long. If this parameter is not specified then PostgREST refuses authentication requests. Choosing a value for this parameter beginning with the at sign such as :code:`@filename` loads the secret out of an external file. This is useful for automating deployments. Note that any binary secrets must be base64 encoded.
|
||||
jwt-aud
|
||||
Specifies the `JWT audience claim <https://tools.ietf.org/html/rfc7519#section-4.1.3>`_. If this claim is present in the client provided JWT then you must set this to the same value as in the JWT, otherwise verifying the JWT will fail.
|
||||
secret-is-base64
|
||||
@@ -135,7 +135,7 @@ pre-request
|
||||
Running the Server
|
||||
------------------
|
||||
|
||||
PostgREST outputs basic request logging to stdout. When running it in an SSH session you must detach it from stdout or it will be terminated when the session closes. The easiest technique is redirecting the output to a logfile or to the syslog:
|
||||
PostgREST outputs basic request logging to stdout. When running it in an SSH session you must detach it from stdout or it will be terminated when the session closes. The easiest technique is redirecting the output to a log file or to the syslog:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
@@ -276,7 +276,7 @@ The script expects the following parameters:
|
||||
|
||||
test/create_test_db connection_uri database_name [test_db_user] [test_db_user_password]
|
||||
|
||||
Use the `connection URI <https://www.postgresql.org/docs/current/static/libpq-connect.html#AEN45347>`_ to specify the user, password, host, and port. Do not provide the database in the connection URI. The Postgres role you are using to connect must be capable of creating new databases.
|
||||
Use the `connection URI <https://www.postgresql.org/docs/current/static/libpq-connect.html#AEN45347>`_ to specify the user, password, host, and port. Do not provide the database in the connection URI. The PostgreSQL role you are using to connect must be capable of creating new databases.
|
||||
|
||||
The :code:`database_name` is the name of the database that :code:`stack test` will connect to. If the database of the same name already exists on the server, the script will first drop it and then re-create it.
|
||||
|
||||
@@ -288,7 +288,7 @@ Optionally, if specifying an existing user to be used for the test connection, o
|
||||
|
||||
The script will return the db uri to use in the tests--this uri corresponds to the :code:`db-uri` parameter in the configuration file that one would use in production.
|
||||
|
||||
Generating the user and the password allows one to create the database and run the tests against any postgres server without any modifications to the server. (Such as allowing accounts without a passoword or setting up trust authentication, or requiring the server to be on the same localhost the tests are run from).
|
||||
Generating the user and the password allows one to create the database and run the tests against any PostgreSQL server without any modifications to the server. (Such as allowing accounts without a password or setting up trust authentication, or requiring the server to be on the same localhost the tests are run from).
|
||||
|
||||
Running the Tests
|
||||
~~~~~~~~~~~~~~~~~
|
||||
@@ -321,7 +321,7 @@ This connection assumes the test server on the :code:`localhost:code:` with the
|
||||
Destroying the Database
|
||||
~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The test database will remain after the test, together with four new roles created on the postgres server. To permanently erase the created database and the roles, run the script :code:`test/delete_test_database`, using the same superuser role used for creating the database:
|
||||
The test database will remain after the test, together with four new roles created on the PostgreSQL server. To permanently erase the created database and the roles, run the script :code:`test/delete_test_database`, using the same superuser role used for creating the database:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
@@ -339,7 +339,7 @@ For example, if local development is on a mac with Docker for Mac installed:
|
||||
$ docker run --name db-scripting-test -e POSTGRES_PASSWORD=pwd -p 5434:5432 -d postgres
|
||||
$ POSTGREST_TEST_CONNECTION=$(test/create_test_db "postgres://postgres:pwd@localhost:5434" test_db) stack test
|
||||
|
||||
Additionally, if one creates a docker container to run stack test (this is necessary on MacOS Sierra with GHC below 8.0.1, where :code:`stack test` fails), one can run PostgreSQL in a separate linked container, or use the locally installed Postgres.app.
|
||||
Additionally, if one creates a docker container to run stack test (this is necessary on Mac OS Sierra with GHC below 8.0.1, where :code:`stack test` fails), one can run PostgreSQL in a separate linked container, or use the locally installed PostgreSQL app.
|
||||
|
||||
Build the test container with :code:`test/Dockerfile.test`:
|
||||
|
||||
@@ -357,7 +357,7 @@ Linked containers:
|
||||
$ docker run --name pg -e POSTGRES_PASSWORD=pwd -d postgres
|
||||
$ docker run --rm -it -v `pwd`:`pwd` -v ~/.stack-linux:/root/.stack --link pg:pg -w="`pwd`" -v `pwd`/.stack-work-docker:`pwd`/.stack-work pgst-test bash -c "POSTGREST_TEST_CONNECTION=$(test/create_test_db "postgres://postgres:pwd@pg" test_db) stack test"
|
||||
|
||||
Stack test in Docker for Mac, Postgres.app on mac:
|
||||
Stack test in Docker for Mac, PostgreSQL app on mac:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
|
||||
@@ -81,7 +81,7 @@ Example Apps
|
||||
* `tyrchen/goodfilm <https://github.com/tyrchen/goodfilm>`_ - example film api
|
||||
* `begriffs/postgrest-example <https://github.com/begriffs/postgrest-example>`_ - sqitch versioning for API
|
||||
* `SMRxT/postgrest-demo <https://github.com/SMRxT/postgrest-demo>`_ - multi-tenant logging system
|
||||
* `PierreRochard/postgrest-boilerplate <https://github.com/PierreRochard/postgrest-boilerplate>`_ - example auth backend
|
||||
* `PierreRochard/postgrest-boilerplate <https://github.com/PierreRochard/postgrest-boilerplate>`_ - example auth back-end
|
||||
|
||||
In Production
|
||||
-------------
|
||||
|
||||
@@ -1,13 +1,19 @@
|
||||
personal_ws-1.1 en 0 utf-8
|
||||
AMQP
|
||||
Auth
|
||||
Bool
|
||||
CSV
|
||||
Codd
|
||||
DDL
|
||||
DoS
|
||||
GHC
|
||||
GUC
|
||||
Github
|
||||
Google
|
||||
GraphQL
|
||||
HMAC
|
||||
HTTPS
|
||||
HV
|
||||
Haskell
|
||||
Heroku
|
||||
Homebrew
|
||||
@@ -33,53 +39,87 @@ PostgreSQL's
|
||||
RDS
|
||||
RESTful
|
||||
RLS
|
||||
RSA
|
||||
RabbitMQ
|
||||
RestSharp
|
||||
SHA
|
||||
SIGHUP
|
||||
SNS
|
||||
SQL
|
||||
SSL
|
||||
Sencha
|
||||
SuperAgent
|
||||
Tcl
|
||||
TypeScript
|
||||
UI
|
||||
Vondra
|
||||
WAI
|
||||
Websockets
|
||||
ZeroMQ
|
||||
api
|
||||
aud
|
||||
auth
|
||||
authenticator
|
||||
balancer
|
||||
cd
|
||||
centric
|
||||
conf
|
||||
config
|
||||
cryptographically
|
||||
csv
|
||||
disjoined
|
||||
eq
|
||||
fts
|
||||
grantor
|
||||
gte
|
||||
http
|
||||
ilike
|
||||
json
|
||||
jwt
|
||||
localhost
|
||||
login
|
||||
logins
|
||||
lon
|
||||
lt
|
||||
lte
|
||||
middleware
|
||||
multi
|
||||
namespaced
|
||||
neq
|
||||
ngrep
|
||||
nullsfirst
|
||||
nullslast
|
||||
nxl
|
||||
nxr
|
||||
openapi
|
||||
ov
|
||||
param
|
||||
params
|
||||
passphrase
|
||||
postgrest
|
||||
pgSQL
|
||||
pgcrypto
|
||||
pgjwt
|
||||
pre
|
||||
refactor
|
||||
requester's
|
||||
savepoint
|
||||
schemas
|
||||
signup
|
||||
sl
|
||||
sqitch
|
||||
sql
|
||||
sr
|
||||
startup
|
||||
stateful
|
||||
stdout
|
||||
syslog
|
||||
tsquery
|
||||
unicode
|
||||
uri
|
||||
url
|
||||
urls
|
||||
verifier
|
||||
versioning
|
||||
webuser
|
||||
wildcard
|
||||
|
||||
Reference in New Issue
Block a user