From 1532b2ace4bdfb81304ffc6d9b26def8c1da9541 Mon Sep 17 00:00:00 2001 From: DecDuck Date: Sun, 25 May 2025 18:29:46 +1000 Subject: [PATCH] feat: add auth docs --- README.md | 42 +------------------ docs/authentication/index.md | 6 +++ docs/authentication/oidc.md | 29 +++++++++++++ docs/authentication/simple.md | 15 +++++++ docs/guides/exposing.md | 4 +- docs/guides/quickstart.md | 20 ++++----- sidebars.ts | 5 +++ .../version-0.2.0/guides/exposing.md | 2 +- .../version-0.2.0/guides/quickstart.md | 6 +-- 9 files changed, 72 insertions(+), 57 deletions(-) create mode 100644 docs/authentication/index.md create mode 100644 docs/authentication/oidc.md create mode 100644 docs/authentication/simple.md diff --git a/README.md b/README.md index 0c6c2c2..b43b60e 100644 --- a/README.md +++ b/README.md @@ -1,41 +1,3 @@ -# Website +# drop-docs -This website is built using [Docusaurus](https://docusaurus.io/), a modern static website generator. - -### Installation - -``` -$ yarn -``` - -### Local Development - -``` -$ yarn start -``` - -This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server. - -### Build - -``` -$ yarn build -``` - -This command generates static content into the `build` directory and can be served using any static contents hosting service. - -### Deployment - -Using SSH: - -``` -$ USE_SSH=true yarn deploy -``` - -Not using SSH: - -``` -$ GIT_USER= yarn deploy -``` - -If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch. +The documentation. Check it out: https://docs.droposs.org/ diff --git a/docs/authentication/index.md b/docs/authentication/index.md new file mode 100644 index 0000000..aa9465e --- /dev/null +++ b/docs/authentication/index.md @@ -0,0 +1,6 @@ +# Authentication + +There are two options for authentication: + +- [Simple](/docs/authentication/simple.md) +- [OpenID Connect](/docs/authentication/oidc.md) diff --git a/docs/authentication/oidc.md b/docs/authentication/oidc.md new file mode 100644 index 0000000..43bd3a2 --- /dev/null +++ b/docs/authentication/oidc.md @@ -0,0 +1,29 @@ +# OpenID Connect + +OpenID Connect is a OAuth2 extension support by most identity providers. + +## Configure OpenID Connect + +To configure OIDC, you must set the following environment variables: + +| Variable | Usage | +| -------------------------------- | ------------------------------------------------------------------------------------------------- | +| `OIDC_CLIENT_ID` | Client ID from your identity provider. | +| `OIDC_CLIENT_SECRET` | Client secret from your identity provider. | +| `OIDC_ADMIN_GROUP` | Grant admin to users with this group configured in your identity provider. Tested with Authentik. | +| `DISABLE_SIMPLE_AUTH` (optional) | Disable simple auth | + +And then, you must configure **either**: + +#### `OIDC_WELLKNOWN`: A unprotected endpoint that returns a OIDC well-known JSON. Fetched on startup. + +--- + +#### Individual endpoints: + +| Variable | Usage | +| -------------------- | ------------------------------------------------------------------------- | +| `OIDC_AUTHORIZATION` | Authorization endpoint. Usually ends with `authorize`. | +| `OIDC_TOKEN` | Token endpoint. Usually ends with `token`. | +| `OIDC_USERINFO` | Userinfo endpoint. Usually ends with `userinfo`. | +| `OIDC_SCOPES` | Comma separated list of scopes. Requires, at least, `openid` and `email`. | diff --git a/docs/authentication/simple.md b/docs/authentication/simple.md new file mode 100644 index 0000000..84c5aed --- /dev/null +++ b/docs/authentication/simple.md @@ -0,0 +1,15 @@ +# Simple + +Simple authentication (or simple auth) is a basic username and password combination. It's the default for Drop, and is the fallback authentication mechanism if Drop is unable to initialise any others. + +Simple authentication works on a system of invites. + +## Creating an invite + +Head to your Drop Admin dashboard, and click on the 'Users' tab. Then, head to the authentication panel by clicking the 'Authentication →' button. + +Then, on the "Simple" auth, click the three-dot menu, and configure. Then, create an invite with the button and modal. + +## Disabling simple auth + +If you've configured another authentication mechanism, you can disable simple by setting the environment variable `DISABLE_SIMPLE_AUTH` to "true". diff --git a/docs/guides/exposing.md b/docs/guides/exposing.md index 41e970f..735a5d9 100644 --- a/docs/guides/exposing.md +++ b/docs/guides/exposing.md @@ -2,7 +2,7 @@ Exposing your instance allows it to be accessible from other computers than the one you're hosting it on. ## LAN -The `compose.yaml` provided in the [Quickstart guide](/guides/quickstart.md) already exposes the Drop instance on port 3000. If you're on the same LAN as your Drop instance, you can find it's IP and then use: +The `compose.yaml` provided in the [Quickstart guide](/docs/guides/quickstart.md) already exposes the Drop instance on port 3000. If you're on the same LAN as your Drop instance, you can find it's IP and then use: ``` http://[instance IP]:3000 ``` @@ -12,7 +12,7 @@ as the connection URL when setting up your Drop client. ## Reverse Proxy If you are unsure how to set up a reverse proxy, or even what one is, this guide isn't for you. There are far better guides out there, so follow them to set up your reverse proxy. -As of `v0.2.0-beta` there is no special configuration required to run Drop behind a reverse proxy. +There is no special configuration required to run Drop behind a reverse proxy. ## VPN If you are unsure how to setup a VPN for remote access, please find and follow a far better guide than this one. diff --git a/docs/guides/quickstart.md b/docs/guides/quickstart.md index 86a3500..c7be3d6 100644 --- a/docs/guides/quickstart.md +++ b/docs/guides/quickstart.md @@ -25,7 +25,7 @@ services: - POSTGRES_USER=drop - POSTGRES_DB=drop drop: - image: decduck/drop-oss:v0.2.0-beta + image: ghcr.io/drop-oss/drop:nightly depends_on: postgres: condition: service_healthy @@ -33,25 +33,23 @@ services: - 3000:3000 volumes: - ./library:/library - - ./certs:/certs - - ./objects:/objects + - ./data:/data environment: - DATABASE_URL=postgres://drop:drop@postgres:5432/drop - - FS_BACKEND_PATH=/objects - - CLIENT_CERTIFICATES=/certs + - DATA=/data - LIBRARY=/library - - GIANT_BOMB_API_KEY=REPLACE_WITH_YOUR_KEY ``` **The main things in this `compose.yaml` is the volumes attached to the `drop` service:** 1. `./library` is where you will put your games to be imported into Drop. See '[Structuring your library](/docs/library.md#structuring-your-library)' once you're set up. -2. `./certs` is where Drop will store cryptographic certificates relating to the function of Drop end clients and the connections between them. In order to make sure the traffic isn't being snooped on, keep this directory safe. -3. `./objects` is where Drop will store uploaded & downloaded files (from metadata providers) +2. `./data` is where Drop will store anything that's using the default file-system backed storage system. Typically, these are objects. **In addition, configure your chosen metadata provider:** -- [GiantBomb](/metadata/giantbomb.md) (only one supported as of v0.2.0-beta) +- [GiantBomb](/docs/metadata/giantbomb.md) +- [IGDB](/docs/metadata/igdb.md) +- [PCGamingWiki](/docs/metadata/pcgamingwiki.md) :::tip If you want to, you can generate a more secure PostgreSQL username & password. @@ -61,11 +59,11 @@ If you want to, you can generate a more secure PostgreSQL username & password. For security reasons, the Drop server and client's times need to be within 30 seconds of each other, otherwise authorization will fail. ::: -Once your instance is running, [create your admin account](/guides/create-admin-account.md). +Once your instance is running, [create your admin account](/docs/guides/create-admin-account.md). ## Setting up a client -To set up a client, your Drop instance will have to be accessible from it. See [Exposing your instance](/guides/exposing.md) for information on how to do that. +To set up a client, your Drop instance will have to be accessible from it. See [Exposing your instance](/docs/guides/exposing.md) for information on how to do that. First, download the latest client for your platform from [the GitHub releases page](https://github.com/Drop-OSS/drop-app/releases). Then, install it for your platform. If we don't have a binary available for your platform, please create an issue on [the Drop app repository](https://github.com/Drop-OSS/drop-app) and we'll investigate it. diff --git a/sidebars.ts b/sidebars.ts index a1dd2cd..7c6b599 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -35,6 +35,11 @@ const sidebars: SidebarsConfig = { label: "Metadata", items: ["metadata/giantbomb", "metadata/igdb", "metadata/pcgamingwiki"], }, + { + type: "category", + label: "Authentication", + items: ["authentication/simple", "authentication/oidc"], + }, { type: "category", label: "Advanced", diff --git a/versioned_docs/version-0.2.0/guides/exposing.md b/versioned_docs/version-0.2.0/guides/exposing.md index 41e970f..9c0ee74 100644 --- a/versioned_docs/version-0.2.0/guides/exposing.md +++ b/versioned_docs/version-0.2.0/guides/exposing.md @@ -2,7 +2,7 @@ Exposing your instance allows it to be accessible from other computers than the one you're hosting it on. ## LAN -The `compose.yaml` provided in the [Quickstart guide](/guides/quickstart.md) already exposes the Drop instance on port 3000. If you're on the same LAN as your Drop instance, you can find it's IP and then use: +The `compose.yaml` provided in the [Quickstart guide](/docs/guides/quickstart.md) already exposes the Drop instance on port 3000. If you're on the same LAN as your Drop instance, you can find it's IP and then use: ``` http://[instance IP]:3000 ``` diff --git a/versioned_docs/version-0.2.0/guides/quickstart.md b/versioned_docs/version-0.2.0/guides/quickstart.md index 86a3500..b3c21f8 100644 --- a/versioned_docs/version-0.2.0/guides/quickstart.md +++ b/versioned_docs/version-0.2.0/guides/quickstart.md @@ -51,7 +51,7 @@ services: **In addition, configure your chosen metadata provider:** -- [GiantBomb](/metadata/giantbomb.md) (only one supported as of v0.2.0-beta) +- [GiantBomb](/docs/metadata/giantbomb.md) (only one supported as of v0.2.0-beta) :::tip If you want to, you can generate a more secure PostgreSQL username & password. @@ -61,11 +61,11 @@ If you want to, you can generate a more secure PostgreSQL username & password. For security reasons, the Drop server and client's times need to be within 30 seconds of each other, otherwise authorization will fail. ::: -Once your instance is running, [create your admin account](/guides/create-admin-account.md). +Once your instance is running, [create your admin account](/docs/guides/create-admin-account.md). ## Setting up a client -To set up a client, your Drop instance will have to be accessible from it. See [Exposing your instance](/guides/exposing.md) for information on how to do that. +To set up a client, your Drop instance will have to be accessible from it. See [Exposing your instance](/docs/guides/exposing.md) for information on how to do that. First, download the latest client for your platform from [the GitHub releases page](https://github.com/Drop-OSS/drop-app/releases). Then, install it for your platform. If we don't have a binary available for your platform, please create an issue on [the Drop app repository](https://github.com/Drop-OSS/drop-app) and we'll investigate it.