These tokens can be used by other services (such as hirmeos/identifier_translation_service) to authenticate users via the
Authorization HTTP header (
Bearer type). To do so, one must share the private key used to issue the tokens with all the services that will use JWT.
The following environment variables may be set. If you're running the service using docker-compose, you may use different files to separate API-specific variables from database's. All variables must be set.
||Boolean flag to output debugging lines to the console.|
||An up to 255 bytes random key, shared with services requiring authentication|
||Number of seconds before a token expires.|
||Number of PBKDF2 iterations - the more the merrier.|
||The address of the host where the tokens database runs.|
||The name of the tokens database.|
||The user name of the tokens database.|
||The password of the tokens database.|
||String with a domain name to be included in CORS headers.|
Running with docker-compose
The easiest way to get a fully featured and functional setup is using a docker-compose file, since the API depends on the hirmeos/tokens_db database.
version: "3.5" services: tokens_db: image: openbookpublishers/tokens_db:1 container_name: "tokens_db" restart: unless-stopped volumes: - db:/var/lib/postgresql/data env_file: - ./config/db.env tokens_api: image: openbookpublishers/tokens_api:1 container_name: "tokens_api" restart: unless-stopped ports: - 8282:8080 environment: - DB_HOST=tokens_db env_file: - ./config/api.env - ./config/db.env depends_on: - tokens_db volumes: db:
- The example uses the docker images already built and used by Open Book Publishers. You may use the provded docker files to build your own, instead.
- You may of course use whatever port you like, and/or use a proxy server (e.g. nginx) to handle the API endpoint.
dbvolume ensure the contents of the database persist when restarting/deleting the container.
- In this example we use two sets of configuration files, one with database credentials shared with both containers, the other one with API configuration only available to the API container. You may use a single file with all environment variables.
Create the first user account
Account registration is only allowed via HTTP (
POST /accounts) after at least one account has been registered via CLI, i.e. HTTP registration requires a token, which are only issued to accounts.
The easiest way is to run python on the api container:
docker exec -it tokens_api python
Then call the
create_account() method in
from api import * accountctrl.AccountController.create_account("email@example.com", "secure_password", "acct:user@domain", "Name", "Surname", "admin")
The following methods are allowed:
||Log in - request a token.|
||Create an account.|
||Check whether a token is valid.|
POST /accounts parameters
When creating an account you must provide a JSON object with all of the following attributes:
|account_id||The unique identifier of this user, in URI format (e.g. 'acct:user@domain'). It doesn't need to match the email address.|
|The email address of the user. It is Email and password are the crendentials.|
|password||The password used to obtain tokens afterwards (along with the email address).|
|name||A concatenation of filters of type
|surname||A concatenation of filters of type
|authority||The user type (by default the database is populated with "admin", "user" and "guest").|
POST /tokens parameters
Tokens can be obtained making a POST request to
/tokens, providing "email" and "password" with values equal to those used in account creation.
|The email address of the user authenticating.|
|password||The password used to authenticate this user.|
You may set env variable
True in order to enable debugging