02 ‐ Authentication

VoucherVault is built using the Django framework. Per default, local authentication is enabled.

VoucherVault provides two login areas:

a regular one at /accounts/login for all user accounts (typically low-priv).
an admin panel at /admin for administrative superuser accounts only.

Default Login

VoucherVault creates an admin user automatically during first start. The corresponding password is auto-generated and displayed in the container logs once.

Please ensure to note down this password, as it will not be shown again after container restarts.

# inspect container logs to retrieve admin password
docker compose -f docker-compose-sqlite.yml logs -f

Create Normal Users

You can log into VoucherVault using your superuser admin account and create new users in the admin panel.

Create Admin Users

Via the HTTP admin portal or via CLI.

Warning

If you create a new superuser via the HTTP admin portal, ensure to enable Staff status as well as Superuser status.

https://docs.djangoproject.com/en/5.0/topics/auth/default/#creating-superusers

# exec into container
docker exec -it vouchervault bash

# create new superuser
python manage.py createsuperuser

Change User Passwords

In user profile settings for regular users or via the HTTP admin portal as superuser. Alternatively, using the CLI.

Warning

Only affects non-OIDC users. OIDC users can only authenticate via the OIDC login flow (except of superusers).

https://docs.djangoproject.com/en/5.0/topics/auth/default/#changing-passwords

# exec into container
docker exec -it vouchervault bash

# create new superuser
python manage.py changepassword <username>

OIDC Authentication

Caution

For OIDC to work, your VoucherVault instance must be run behind a reverse proxy with TLS enabled.

The reasons for this are security and strict HTTPS callback URLs of your IdP.

You can enable OIDC SSO by setting the environment variable OIDC_ENABLED to True. Also define all other relevant OIDC env variables properly according to your Identity Provider setup. Once OIDC is enabled, the local authentication for regular user accounts is replaced by a single OIDC login button. Then, only superadmins are allowed to use local authentication via the /admin portal.

PoC

Users authenticating via OIDC SSO are automatically onboarded as low-priv user accounts on VoucherVault.

You can change this behaviour by setting the environment variable OIDC_CREATE_USER to False. If disabled, OIDC authentication will only work for user accounts that were created by a superadmin beforehand manually. The important claim is the user account's email address. Note that OIDC users cannot change their password on VoucherVault as the password will never be used for authentication.

If you want to grant superuser privileges to an OIDC SSO user, let the SSO user authenticate against VoucherVault, which will onboard the user account automatically. Then, manually log in as superuser at /admin and assign the Superuser status and Staff status for the account.

Tip

If errors occur and you want to troubleshoot, may set the env variable DEBUG to True.

This way, you will receive detailed debug error messages within the browser.

Authentik Setup

The OIDC setup was tested against Authentik IdP:

Create Provider

Log into Authentik as admin
Create a new Provider at /if/admin/#/core/providers
1. Choose client type confident
2. Choose client id vauchervault
3. Add the redirect url https://<FQDN>/oidc/callback/. Replace <FQDN> with your VoucherVault instance's domain name.
4. Select Authentik's self-signed certificate as signing key, if you want to use RSA256. If you leave the signing key field empty, the algorithm HS256 is used instead. Your selection must be reflected later in the OIDC_RP_SIGN_ALGO environment variable of the docker-compose.yml file. If RSA256 was chosen, you must either define OIDC_RP_IDP_SIGN_KEY or OIDC_OP_JWKS_ENDPOINT as environment variable. I recommend using RS256 and setting the JKWS URL as env.
Make note of the client id and client secret; reflect those in the VoucherVault compose env variables
Safe the Provider

Create Application

Log into Authentik as admin
Create a new Application at if/admin/#/core/applications
1. Choose slug name vouchervault
Select the previously created Provider at interfaces
Safe the Application

Adjust VoucherVault Envs

Now reflect the client secret and Authentik's OIDC URLs in VoucherVault's docker-compose.yml.

Those are defined via environment variables as follows:

    environment:
      # ------- OPTIONAL OIDC AUTH --------
      # Set to 'True' to enable OIDC authentication
      #- OIDC_ENABLED=True
      # Set to 'True' to allow the creation of new users through OIDC
      #- OIDC_CREATE_USER=True
      # The signing algorithm used by the OIDC provider (e.g., RS256, HS256)
      #- OIDC_RP_SIGN_ALGO=RS256
      # URL of the JWKS endpoint for the OIDC provider
      #- OIDC_OP_JWKS_ENDPOINT=https://authentik.example.com/application/o/vouchervault/jwks/
      # Client ID for your OIDC RP
      #- OIDC_RP_CLIENT_ID=vouchervault
      # Client secret for your OIDC RP
      #- OIDC_RP_CLIENT_SECRET=<YOUR-CLIENT-SECRET-FROM-AUTHENTIK>
      # Authorization endpoint URL of the OIDC provider
      #- OIDC_OP_AUTHORIZATION_ENDPOINT=https://authentik.example.com/application/o/authorize/
      # Token endpoint URL of the OIDC provider
      #- OIDC_OP_TOKEN_ENDPOINT=https://authentik.example.com/application/o/token/
      # User info endpoint URL of the OIDC provider
      #- OIDC_OP_USER_ENDPOINT=https://authentik.example.com/application/o/userinfo/

Afterwards, please restart the VoucherVault container to enable the new OIDC authentication configuration.

Enjoy using OIDC SSO!

Authelia Setup

Authelia is configured via a configuration.yml file.

Visiting Authelia's public OIDC documentation, we can obtain an example configuration. Within this example configuration, there are multiple parameters that either require a secret value or a certificate.

Those must be securely generated prior adjusting the configuration. Therefore, let's generate those things!

Create RSA Certificate

Authelia requires you to define a certificate (private key) via key and a certificate chain (public key) via certificate_chain.

You can generate both via the following command:

docker run --rm authelia/authelia sh -c "authelia crypto certificate rsa generate --common-name authelia.example.com && cat public.crt && cat private.pem"

Warning

Please adjust the certificate's common name to your FQDN

Create Client Secret

Authelia requires you to define a secure client secret.

You can generate it via the following command:

# create client secret
docker run authelia/authelia:latest authelia crypto hash generate pbkdf2 --variant sha512 --random --random.length 72 --random.charset rfc3986

Please note down the cleartext password as well as the $pbkdf2 password hash for later use.

Add Identity Provider

Now go ahead and add the following to the end of Authelia's configuration.yml file:

identity_providers:
  oidc:
    hmac_secret: 'my-secure-hmac-secret-key-to-change'
    jwks:
      - key_id: 'authelia'
        algorithm: 'RS256'
        use: 'sig'
        certificate_chain: |
          -----BEGIN CERTIFICATE-----
          <PASTE-HERE-YOUR-PUBLIC-KEY-DATA>
          -----END CERTIFICATE-----
        key: |
          -----BEGIN PRIVATE KEY-----
          <PASTE-HERE-YOUR-PRIVATE-KEY-DATA>
          -----END PRIVATE KEY-----
    enable_client_debug_messages: false
    minimum_parameter_entropy: 8
    enforce_pkce: 'public_clients_only'
    enable_pkce_plain_challenge: false
    enable_jwt_access_token_stateless_introspection: false
    discovery_signed_response_alg: 'none'
    discovery_signed_response_key_id: ''
    require_pushed_authorization_requests: false
    lifespans:
      access_token: '1h'
      authorize_code: '1m'
      id_token: '1h'
      refresh_token: '90m'
    cors:
      endpoints:
        - 'authorization'
        - 'token'
        - 'revocation'
        - 'introspection'
      allowed_origins:
        - 'https://vouchervault.example.com'
      allowed_origins_from_client_redirect_uris: false
    clients:
      - client_id: vouchervault
        client_name: VoucherVault OIDC
        client_secret: '$pbkdf2-<YOUR-GENERATED-SECRET-HASH_DATA-HERE>'
        public: false
        authorization_policy: one_factor # or two_factor to require MFA
        consent_mode: pre-configured
        token_endpoint_auth_method: "client_secret_post"
        pre_configured_consent_duration: 1w
        scopes:
          - openid
          - groups
          - email
          - profile
        redirect_uris:
          - https://vouchervault.example.com/oidc/callback/
        grant_types:
          - refresh_token
          - authorization_code
        response_types:
          - code
        response_modes:
          - form_post
          - query
          - fragment

Please adjust the following directives to your domain and secret values:

hmac_secret
certificate_chain
key
redirect_uris
client_secret

Warning

Ensure to properly paste the public and private keys to the correct directives. Ensure to provide the $pbkdf2 value of the generated client secret - not the password itself!

Afterwards, please restart Authelia to activate the new configuration.

Adjust VoucherVault Envs

Now reflect the client secret password and Authelia's OIDC URLs in VoucherVault's docker-compose.yml.

Those are defined via environment variables as follows:

    environment:
      # ------- OPTIONAL OIDC AUTH --------
      # Set to 'True' to enable OIDC authentication
      - OIDC_ENABLED=True
      # Set to 'True' to allow the creation of new users through OIDC
      - OIDC_CREATE_USER=True
      # The signing algorithm used by the OIDC provider (e.g., RS256, HS256)
      - OIDC_RP_SIGN_ALGO=RS256
      # URL of the JWKS endpoint for the OIDC provider
      - OIDC_OP_JWKS_ENDPOINT=https://authelia.example.com/jwks.json
      # Client ID for your OIDC RP
      - OIDC_RP_CLIENT_ID=vouchervault
      # Client secret for your OIDC RP
      - OIDC_RP_CLIENT_SECRET=<YOUR-GENERATED-CLIENT-SECRET-PASSWORD-CLEARTEXT>
      # Authorization endpoint URL of the OIDC provider
      - OIDC_OP_AUTHORIZATION_ENDPOINT=https://authelia.example.com/api/oidc/authorization
      # Token endpoint URL of the OIDC provider
      - OIDC_OP_TOKEN_ENDPOINT=https://authelia.example.com/api/oidc/token
      # User info endpoint URL of the OIDC provider
      - OIDC_OP_USER_ENDPOINT=https://authelia.example.com/api/oidc/userinfo

Warning

Ensure to change authelia.example.com to the FQDN of your Authelia instance. Ensure to provide the cleartext client secret password and not the $pbkdf2 hash value. Only holds true if you have defined a $pbkdf2 password hash in Authelia's configuration file. If not, just paste the same secret string value.

Afterwards, please restart the VoucherVault container to enable the new OIDC authentication configuration.

Enjoy using OIDC SSO!

2FA Authentication

Multi-Factor-Authentication (MFA or 2FA) is only available for OIDC SSO.

You can configure this in your Identity Provider like Authelia or Authentik.

Otherwise, if you use regular authentication via username and password, no MFA/2FA is supported.

API Authentication

Since VoucherVault v1.7 an API endpoint is available at /en/api/get/stats.

The endpoints requires Bearer authentication. An API token can be created within the Django admin interface.

More information within this wiki at API-Endpoints.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

02 ‐ Authentication

Default Login

Create Normal Users

Create Admin Users

Change User Passwords

OIDC Authentication

Authentik Setup

Create Provider

Create Application

Adjust VoucherVault Envs

Authelia Setup

Create RSA Certificate

Create Client Secret

Add Identity Provider

Adjust VoucherVault Envs

2FA Authentication

API Authentication

Clone this wiki locally