Auth server is standalone microservice that provides authentication capabilities, and it is used as default authentication service for Papermerge DMS.
Following authentication methods are supported:
- database - authenticate against user credentials from the database's core_user table
- oidc - authenticate against OIDC provider
- ldap - authenticate with LDAP
When authentication succeeds, auth server responds with a valid cryptographically signed JWT access token.
JWT token is delivered to the client as http response payload (json format) and as cookie.
Auth-server is configured only via environment variables. The only required parameter you need to provide it secret key (used to sign tokens):
version: "3.9"
services:
web:
image: papermerge/auth-server
ports:
- "7000:80"
environment:
PAPERMERGE__SECURITY__SECRET_KEY: <your secret string>
If no other settings are provided, it will be assumed authentication against credentials stored in database. Default database is "sqlite:////db/db.sqlite3". Optionally you can choose to store credentials in PostgreSQL database:
version: "3.9"
services:
web:
image: papermerge/auth-server
ports:
- "7000:80"
environment:
PAPERMERGE__SECURITY__SECRET_KEY: <your secret string>
PAPERMERGE__DATABASE__URL: postgresql://postgres:123@db:5432/postgres
depends_on:
- db
db:
image: bitnami/postgresql:14.4.0
volumes:
- postgres_data:/var/lib/postgresql/data/
environment:
- POSTGRES_PASSWORD=123
volumes:
postgres_data:
For MySql/MariaDB use mysql
scheme. For example:
PAPERMERGE__DATABASE__URL: mysql://user:[email protected]:3306/mydatabase
And docker compose file would look like:
version: "3.9"
services:
web:
image: papermerge/auth-server
ports:
- "7000:80"
environment:
PAPERMERGE__SECURITY__SECRET_KEY: <your secret string>
PAPERMERGE__DATABASE__URL: mysql://user:[email protected]:3306/mydatabase
depends_on:
- db
db:
image: mariadb:11.2
volumes:
- maria:/var/lib/mysql
environment:
MYSQL_ROOT_PASSWORD: password
MYSQL_DATABASE: mydatabase
MYSQL_USER: user
MYSQL_PASSWORD: password
ports:
- 3306:3306
volumes:
maria:
In order to enable authentication via OIDC provider you need to provide following environment variables:
PAPERMERGE__AUTH__OIDC_CLIENT_SECRET
PAPERMERGE__AUTH__OIDC_CLIENT_ID
PAPERMERGE__AUTH__OIDC_ACCESS_TOKEN_URL
PAPERMERGE__AUTH__OIDC_USER_INFO_URL
PAPERMERGE__AUTH__OIDC_INTROSPECT_URL
You need to provider all five values.
PAPERMERGE__AUTH__OIDC_REDIRECT_URI
should be:
<http|https>://<your domain>/oidc/callback
Above value should be same as in field "Authorized redirect URI" when registering oauth2 client.
You can also start the auth server with poetry:
$ poetry run uvicorn auth_server.main:app \
--host 0.0.0.0 \
--port 8000 \
--reload \
--log-config etc/logging.yml
--log-level info
Application providers one single endpoint POST /token
which return jwt access
token. There two valid options for using POST /token
endpoint:
- non-empty request body with user credentials (application/json)
- empty request body, but non-empty valid request params
In case 1. application will authenticate again user credentials in database (TBD: or againt LDAP credentials, if LDAP configurations are present). Here is an example of POST request with user credentials:
$ curl -v -XPOST http://localhost:8000/token -H 'Content-Type: application/json' \
-d '{"username": "username", "password":"password"}'
In case 2. i.e. when POST body is empty, then application using information from request parameters will authenticate against one of the available OAuth 2.0 providers:
$ curl -v -XPOST "http://localhost:8000/token?provider=google&code=123 ..."
For documentation on request parameters see http://localhost:8000/docs
On successful login "access_token" will be provided in response body.
You can decode JWT payload with:
$ echo -n payload | base64 -d
This section lists all configuration environment variables.
PAPERMERGE__SECURITY__SECRET
(required)PAPERMERGE__SECURITY__TOKEN_ALGORITHM
default value "HS256"PAPERMERGE__SECURITY__TOKEN_EXPIRE_MINUTES
default value is 60
Possible values for token algorithm are:
- HS256
- HS384
- HS512
- RS256
- RS384
- RS512
- ES256
- ES384
- ES512
PAPERMERGE__DATABASE__URL
(optional)
Default value is "sqlite:////db/db.sqlite3". PostgreSql and MySql/MariaDB are
supported as well. For PostgreSql scheme is postgresql
and for MySql/MariaDB
scheme is mysql
.
Database URL should be as described in sql alchemy documentation Keep in mind that papermerge-core uses dj-database-url, which means that many scheme described in sqlalchemy docs will not work for papermerge-core.
PAPERMERGE__AUTH__OIDC_CLIENT_SECRET
PAPERMERGE__AUTH__OIDC_CLIENT_ID
PAPERMERGE__AUTH__OIDC_ACCESS_TOKEN_URL
PAPERMERGE__AUTH__OIDC_USER_INFO_URL
PAPERMERGE__AUTH__OIDC_INTROSPECT_URL