Quickstart

This quickstart guide will walk through the process of self-hosting magiclinksdev on your local machine.

The quickstart configuration will use a no-operation email sender and robots will not be prevented from following magic links. For details on how to do more advanced configuration, please visit the Configuration docs.

Prerequisites

This example requires Go, Git, and Docker to be installed on your machine.

Please note, earlier versions of Docker Compose used the command docker-compose rather than docker compose. If you are using an older version, please translate the commands accordingly.

The following Docker images will be pulled by Docker Compose automatically.

micahparks/magiclinksdevnop:latest
postgres:15

Step 1: Clone the repository

The files and directories used in this quickstart are:

docker-compose.quickstart.yml
docker-compose.override.yml
config.quickstart.json
storage/postgres/startup.sql
examples/client/send_link/

git clone https://github.com/MicahParks/magiclinksdev.git
cd magiclinksdev

Step 2: Use Docker Compose

Launch the service and its database in the background using Docker Compose.

docker compose up -d

Step 3: Create a magic link

The example from the repository in examples/client/send_link/ will request a magic link from the service. This magic link should redirect to jwtdebug.micahparks.com with a URL query parameter jwt containing a JWT.

go run examples/client/send_link/main.go

The output should look similar to this:

{
  "linkCreateResults": {
    "magicLink": "http://localhost:8080/redirect/?secret=66af8a5d-7e8d-4f9f-9729-161e214c7d1c",
    "secret": "66af8a5d-7e8d-4f9f-9729-161e214c7d1c"
  },
  "requestMetadata": {
    "uuid": "b56640e4-242d-4bbf-a7b5-1c678502eb5d"
  }
}

Step 4: Use the magic link

By default, the link will only be valid for 5 minutes. Copy the magic link and open it in a browser. You should be redirected to jwtdebug.micahparks.com with a signed JWT in a URL query parameter. This website is a slimmed down version of the jsonwebtoken.github.io GitHub project.

Header:

{
  "alg": "EdDSA",
  "kid": "526ff60f-9c8b-4a73-ba74-cc8962494873",
  "typ": "JWT"
}

Payload:

{
  "foo": "bar",
  "iss": "http://localhost:8080",
  "aud": [
    "ad9e9d84-92ea-4f07-bac9-5d898d59c83b"
  ],
  "exp": 1673815954,
  "nbf": 1673815654,
  "iat": 1673815654,
  "jti": "1a1e2abe-b467-4bf6-9194-c4a60c54745b"
}

Every API client needs to validate the aud claim in the JWT. This is essential to prevent a malicious service account from requesting a signed JWT for a different service. Every service account has at least one aud given on creation. The iss claims should be checked too. The iss claim is specific to the configuration of the magiclinksdev service, typically the URL.

Step 5: Cleanup

Stop the service and the database from running in the background.

docker compose down

Disclaimer

Please note that the quickstart configuration should not be used in production. It is essential to regenerate all UUIDs, especially the admin API key. Additionally, a new storage AES-256-GCM key should be generated.

Any UUIDs and storage AES-256-GCM keys should be generated with sufficient entropy. On Linux systems the following commands can accomplish this:

Generate a random UUID on Linux

uuidgen --random

Generate a AES-256-GCM key on Linux

openssl rand -base64 32

Conclusion

You have successfully self-hosted magiclinksdev on your local machine! You can now configure the service for your use case and request magic links for your own applications. See the Configuration reference for more information.

Want to say thanks for writing up the docs? Support the project financially? Consider becoming a GitHub Sponsor.