authentication

README

---

---

This is a quickstart document to test the project locally.

You can find the API documentation on the repository GitHub page.

Want to contribute? Check the contribution guidelines.

Use in a project

You can import this application as a docker image. Below is an example using podman compose.

services:
  postgres-authentication:
    image: docker.io/library/postgres:17
    networks:
      - api
    environment:
      POSTGRES_PASSWORD: postgres
      POSTGRES_USER: postgres
      POSTGRES_DB: authentication
      POSTGRES_HOST_AUTH_METHOD: scram-sha-256
      POSTGRES_INITDB_ARGS: --auth=scram-sha-256
    volumes:
      - postgres-auth-data:/var/lib/postgresql/data/

  # Runs the secret key rotation on every launch.
  # Keys are smartly rotated, meaning new keys are generated only when necessary
  # (eg: keys missing or last generated version is too old).
  # The container will exit by itself when the job is done.
  authentication-rotate-keys-job:
    image: ghcr.io/a-novel/authentication/jobs/rotatekeys:v0
    depends_on:
      - postgres-authentication
    environment:
      PORT: 4001
      ENV: local
      APP_NAME: authentication-service-rotate-keys-job
      DSN: postgres://postgres:postgres@postgres-authentication:5432/authentication?sslmode=disable
      # Dummy key used only for local environment. Consider using a secure, private key in production.
      # Note it MUST match the one used in the authentication service.
      MASTER_KEY: fec0681a2f57242211c559ca347721766f8a3acd8ed2e63b36b3768051c702ca
    networks:
      - api

  authentication-service:
    image: ghcr.io/a-novel/authentication/api:v0
    depends_on:
      - postgres-authentication
    ports:
      - "4001:4001"
    environment:
      PORT: 4001
      ENV: local
      APP_NAME: authentication-service
      DSN: postgres://postgres:postgres@postgres-authentication:5432/authentication?sslmode=disable
      # Dummy key used only for local environment. Consider using a secure, private key in production.
      # Note it MUST match the one used in the authentication keys rotation job.
      MASTER_KEY: fec0681a2f57242211c559ca347721766f8a3acd8ed2e63b36b3768051c702ca
      SMTP_PASSWORD: "${SMTP_PASSWORD}"
      AUTH_PLATFORM_URL_UPDATE_EMAIL: http://localhost:4001/update-email
      AUTH_PLATFORM_URL_UPDATE_PASSWORD: http://localhost:4001/update-password
      AUTH_PLATFORM_URL_REGISTER: http://localhost:4001/register
    networks:
      - api

networks:
  api: {}

volumes:
  postgres-auth-data:

Available tags includes:

• latest: latest versioned image
• vx: versioned images, pointing to a specific version. Partial versions are supported. When provided, the latest subversion is used.
  examples: v0, v0.1, v0.1.2
• branch: get the latest version pushed to a branch. Any valid branch name can be used.
  examples: master, fix/something

Run locally

Pre-requisites

• Golang

• Node.js

• Python

  • Install pipx to install command-line tools.

• Podman

  • Install podman-compose

    # Pipx
    pipx install podman-compose
    
    # Brew
    brew install podman-compose
    

• Make

  # Debian / Ubuntu
  sudo apt-get install build-essential
  
  # macOS
  brew install make
  

  For Windows, you can use Make for Windows

Setup environment

Create a .envrc file from the template:

cp .envrc.template .envrc

Then fill the missing secret variables. Once your file is ready:

source .envrc

You may use tools such as direnv, otherwise you'll need to source the env file on each new terminal session.

Install the external dependencies:

make install

Generate keys

You need to do this at least once, to have a set of keys ready to use for authentication.

It is recommended to run this regularly, otherwise keys will expire and authentication will fail.

make rotate_keys
# 9:07PM INF key generated app=authentication job=rotate-keys key_id=... usage=auth
# 9:07PM INF no key generated app=authentication job=rotate-keys usage=refresh
# 9:07PM INF rotation done app=authentication failed_keys=0 generated_keys=1 job=rotate-keys total_keys=2

Et Voilà!

make api
# 3:09PM INF starting application... app=authentication
# 3:09PM INF application started! address=:4001 app=authentication