Geoshop Backend

Requirements

• PostgreSQL >= 11 + PostGIS
• Python >= 3.9
• GDAL

Getting started

Fork and clone this repository. Make a copy of default_settings.py and .env.sample file and adapt it to your environment settings:

cp default_settings.py settings.py
cp .env.sample .env

.env will vary depending on the environements you're targetting. settings.py will get the specific config of your project.

Database

Create a geoshop user if not existing yet, set your password according to your env.local:

CREATE ROLE geoshop WITH LOGIN PASSWORD <password>;

Then, set up a database:

CREATE DATABASE geoshop OWNER geoshop;
REVOKE ALL ON DATABASE geoshop FROM PUBLIC;

Then connect to the geoshop database and create extensions:

CREATE EXTENSION postgis;
CREATE EXTENSION unaccent;
CREATE EXTENSION "uuid-ossp";
CREATE SCHEMA geoshop AUTHORIZATION geoshop;

-- TODO: Only if french is needed
CREATE TEXT SEARCH CONFIGURATION fr (COPY = simple);
ALTER TEXT SEARCH CONFIGURATION fr ALTER MAPPING FOR hword, hword_part, word
WITH unaccent, simple;

Now that the database is ready, you can start backend either with Docker or not.

Testing data

python manage.py seed

Will seed your database with testing users, contracts and other sample data.

Run dev server without docker on Windows

You'll need to configure 3 paths to your GDAL installation according to .env.sample.

Then, we're going to:

• Run migrations
• Collect static files for the admin interface
• Generate translations for your langage
• Add minimal users to database

python manage.py migrate
python manage.py collectstatic
python manage.py compilemessages --locale=fr
python manage.py fixturize

Finally, you can run the server:

python manage.py runserver

Run tests

python manage.py test

Customize

custom.js in api/templates/gis/admin

OIDC authentication

Glossary

• OpenID is an open standard and decentralized authentication protocol.
• OAuth or Open Authorization is an authorization standard and protocol.
• OIDC or OpenID Connect is an authentication protocol based on OAuth2.0 standard, a third generation of an OpenID technology.
• Zitadel - authentication management service, a single point to configure permissions for our services.

For OpenID authentication, Geoshop uses mozilla-django-oidc library, published under Mozilla Public License 2.0.

Django configuration

.env variables are usually enough:

OIDC_ENABLED = True|False # Toggle Zitadel authentication globally.
OIDC_OP_BASE_URL = "..." # Your Zitadel instance url (something like https://geoshop-demo-abcdef.zitadel.cloud)
OIDC_REDIRECT_BASE_URL = "http://localhost:8000" # Where the service lives, different for local server or docker container
ZITADEL_PROJECT = "..."
OIDC_RP_CLIENT_ID = "..." # Zitadel Client ID
OIDC_RP_CLIENT_SECRET = "..." # Not needed in PKCE mode

Extended description

urls.py - special configuration required because Zitadel strips out trailing slashes in the redirect URLs, but Mozilla OIDC urls.py requires them.

...
    path("oidc/callback", OIDCCallbackClass.as_view(), name="oidc_authentication_callback"),
    path("oidc/authenticate/",  OIDCAuthenticateClass.as_view(), name="oidc_authentication_init"),
    path("oidc/logout", OIDCLogoutView.as_view(), name="oidc_logout"),
...

settings.py - extra app, middleware and authentication backend

INSTALLED_APPS=[
    ...
    'mozilla_django_oidc',
    ...
]

MIDDLEWARE=[
    ...
    'mozilla_django_oidc.middleware.SessionRefresh',
    ...
]

AUTHENTICATION_BACKENDS = (
    ...
    "oidc.PermissionBackend",
    ...
)

Zitadel side

Zitadel Django Tutorial

An overview

1. level is "Organization" - that part is mostly about configuring your Zitadel users, permissions and billing.
2. level is "Instance" - place where you configure your services and your service users, permissions and other authorization parameters. There could be multiple (e.g. -dev, -prod)
3. level is "Project" - users and roles here. Each project is your service that can authenticate and authorize users defined on the "Instance" level
4. level is "Application" - authorization and authentication tokens and methods,

Roles and permissions

Zitadel roles and their Geoshop equivalents:

Zitadel role	Geoshop
admin	superuser
staff	staff