diff --git a/README.md b/README.md index 501a6d9..2d6c0fb 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,11 @@ -# wiki -An editable wiki for our projects +# An editable wiki for our projects + +## Pushing to romm.wiki +We use submodules to manage the wiki content. To push changes to the wiki, you need to commit and push changes in the submodule directory. + +```bash +cd romm.wiki +git add . +git commit -m "Update wiki content" +git push +``` diff --git a/romm.wiki/Environment-Variables.md b/romm.wiki/Environment-Variables.md index 1148d39..4e6de20 100644 --- a/romm.wiki/Environment-Variables.md +++ b/romm.wiki/Environment-Variables.md @@ -11,10 +11,22 @@ This is a complete list of available environment variables; required variables a |DB_NAME|Should match MYSQL_DATABASE in mariadb||`romm`| |DB_USER|Should match MYSQL_USER in mariadb|✓|| |DB_PASSWD|Should match MYSQL_PASSWORD in mariadb|✓|| +|REDIS_HOST|Host name of Redis instance||`127.0.0.1`| +|REDIS_PORT|Port number of Redis instance||`6379`| +|REDIS_PASSWORD|Password for Redis instance||| +|REDIS_USERNAME|Username for Redis instance||| +|REDIS_DB|Database number for Redis instance||`0`| +|REDIS_SSL|Enable SSL for Redis instance||`false`| |ROMM_AUTH_SECRET_KEY|Generate a key with `openssl rand -hex 32`|✓|| |ROMM_HOST|Host name of ROMM instance||`localhost`| +|OIDC_ENABLED|Enable OpenID Connect (OIDC) authentication||`false`| +|OIDC_CLIENT_ID|Client ID for OIDC authentication||| +|OIDC_CLIENT_SECRET|Client secret for OIDC authentication||| +|OIDC_REDIRECT_URI|Absolute redirect URI for OIDC authentication||| +|OIDC_SERVER_APPLICATION_URL|Absolute URL of the OIDC server application||| |DISABLE_CSRF_PROTECTION|Disables [CSRF protection](https://cheatsheetseries.owasp.org/cheatsheets/Cross-Site_Request_Forgery_Prevention_Cheat_Sheet.html) (not recommended)||`false`| |DISABLE_DOWNLOAD_ENDPOINT_AUTH|Disable auth on download endpoint (WebRcade, Tinfoil)||`false`| +|UPLOAD_TIMEOUT|Timeout for file uploads (in seconds)||`600`| |SCAN_TIMEOUT|Timeout for the background scan/rescan tasks (in seconds)||`14400`| |ENABLE_RESCAN_ON_FILESYSTEM_CHANGE|Enable rescanning of library when filesystem changes||`false`| |RESCAN_ON_FILESYSTEM_CHANGE_DELAY|Delay in minutes before rescanning library when filesystem changes||`5`| @@ -27,3 +39,8 @@ This is a complete list of available environment variables; required variables a |DISABLE_EMULATOR_JS|Disables playing in browser with [EmulatorJS](https://github.com/rommapp/romm/wiki/EmulatorJS-Player)||`false`| |DISABLE_RUFFLE_RS|Disables playing flash games with [RuffleRS](https://github.com/rommapp/romm/wiki/RuffleRS-Player)||`false`| |TZ|Sets the timezone||`UTC`| +|GUNICORN_WORKERS|Number of processes running the app||`2`| +|ROMM_BASE_PATH|Base folder path for library, resources and assets||`/romm`| +|LOGLEVEL|Logging level for the app||`INFO`| +|FORCE_COLOR|Forces color output||`false`| +|NO_COLOR|Disables color output||`false`| diff --git a/romm.wiki/OIDC-Setup-With-Authentik.md b/romm.wiki/OIDC-Setup-With-Authentik.md new file mode 100644 index 0000000..12d0687 --- /dev/null +++ b/romm.wiki/OIDC-Setup-With-Authentik.md @@ -0,0 +1,75 @@ +# OIDC Setup With Authentik + +## A quick rundown of the technologies + +### What is Authentik? +Authentik is an open-source identity provider (IdP) designed to manage authentication, authorization, and user management across applications. It supports modern authentication protocols and provides tools to simplify integration, including single sign-on (SSO), multi-factor authentication (MFA), and auditing capabilities. Authentik can be deployed alongside your other services to centralize identity management. + +### What is OAuth2? +OAuth2 (Open Authorization 2.0) is an industry-standard protocol for authorization. It allows applications (clients) to gain limited access to user accounts on an HTTP service without sharing the user’s credentials. Instead, it uses access tokens to facilitate secure interactions. OAuth2 is commonly used in scenarios where users need to authenticate via a third-party service. + +### What is OpenID Connect (OIDC)? +OIDC (OpenID Connect) is an identity layer built on top of OAuth2. While OAuth2 primarily handles authorization, OIDC adds authentication, enabling applications to verify a user’s identity and obtain profile information. This makes OIDC suitable for SSO solutions, where user identity is central to access management. + +## Setting up a Provider and Application in Authentik + +### Step 1: Install and Configure Authentik +Before setting up a provider and app, ensure that Authentik is installed and running by following the [official installation guide.](https://docs.goauthentik.io/docs/install-config/install/docker-compose). + +1. Access Authentik via its web interface. +2. Log in as an administrator. +3. Navigate to the “Admin Interface” to configure the necessary components. + +![Authentik user dashboard](https://raw.githubusercontent.com/rommapp/wiki/refs/heads/main/romm.wiki/resources/authentik/1-user-dashboard.png) + +### Step 2: Create a Provider +A provider in Authentik acts as the bridge between RomM and Authentik. + +1. **Navigate to Providers**: + - Go to the "Providers" section in the Authentik admin interface. +2. **Create a New Provider**: + - Click on “Create” and choose the protocol (e.g., “OIDC Provider”). +![Create a new provider](https://raw.githubusercontent.com/rommapp/wiki/refs/heads/main/romm.wiki/resources/authentik/2-create-provider.png) +3. **Select "OAuth2/OpenID Provider"** +![Select OAuth2 provider](https://raw.githubusercontent.com/rommapp/wiki/refs/heads/main/romm.wiki/resources/authentik/3-new-provider.png) +4. **Configure Provider Settings**: + - **Name**: Assign a unique name to the provider (e.g., "RomM OIDC Provider"). + - **Authorization flow**: Select __implicit consent__. + - **Redirect URIs**: Add your RomM instance's URL + `/api/oauth/openid` (e.g., `http://romm.host.local/api/oauth/openid`). +5. **Copy the Client ID and Secret**: + - You'll need these to set `OIDC_CLIENT_ID` and `OIDC_CLIENT_SECRET` in your RomM instance. +![Provider settings](https://raw.githubusercontent.com/rommapp/wiki/refs/heads/main/romm.wiki/resources/authentik/4-provider-secrets.png) +6. **Click Create**. + +### Step 3: Register an Application +An app in Authentik represents the external service (in our case RomM) that will use the provider for authentication. + +1. **Navigate to Applications**: + - Go to the "Applications" section in the admin interface. +![Applications](https://raw.githubusercontent.com/rommapp/wiki/refs/heads/main/romm.wiki/resources/authentik/5-applications.png) +2. **Create a New Application**: + - Click on “Create” and configure the app settings: + - **Name**: Provide a recognizable name (e.g., "RomM"). + - **Slug**: Create a unique identifier for the app (e.g., "romm"). + - **Provider**: Link the app to the previously created provider, "RomM OIDC Provider". +![New application](https://raw.githubusercontent.com/rommapp/wiki/refs/heads/main/romm.wiki/resources/authentik/6-new-application.png) +6. **Click Create**. + +### Step 4: Configure RomM Environment Variables +To enable OIDC authentication in RomM, you need to set the following environment variables: + +- `OIDC_ENABLED`: Set to `true` to enable OIDC authentication. +- `OIDC_CLIENT_ID`: The client ID copied from the Authentik application. +- `OIDC_CLIENT_SECRET`: The client secret copied from the Authentik application. +- `OIDC_REDIRECT_URI`: The redirect URI configured in the Authentik provider, in the format `http://romm.host.local/api/oauth/openid`. +- `OIDC_SERVER_APPLICATION_URL`: The URL of the Authentik application, e.g., `http://authentik.host.local/application/o/romm`. + +### Step 5: Set your Email in RomM +In RomM, open your user profile and set your email address. This email **has to match** your user email in Authentik. + +![Set email](https://raw.githubusercontent.com/rommapp/wiki/refs/heads/main/romm.wiki/resources/authentik/7-user-profile.png) + +### Step 6: Test the Integration +After configuring the environment variables, restart (or stop and remove) your RomM instance and navigate to the login page. You should see an option to log in using OIDC. Click on the OIDC button, and you'll be redirected to Authentik for authentication. Once authenticated, you'll be redirected back to RomM. + +![Login with OIDC](https://raw.githubusercontent.com/rommapp/wiki/refs/heads/main/romm.wiki/resources/authentik/8-romm-login.png) diff --git a/romm.wiki/Tinfoil-Integration.md b/romm.wiki/Tinfoil-Integration.md index 8dc2e58..73028d1 100644 --- a/romm.wiki/Tinfoil-Integration.md +++ b/romm.wiki/Tinfoil-Integration.md @@ -42,7 +42,7 @@ Now it's time to configure your switch - Please follow the steps, this will assu Now you will be able to see the files in "New Games" tab of Tinfoil OR you can access it within the "File Browser" section that you setup earlier. -![Image of Tinfoil](./romm.wiki/resources/tinfoilscreen.jpg) +![Image of Tinfoil](https://raw.githubusercontent.com/rommapp/wiki/refs/heads/main/romm.wiki/resources/tinfoil/tinfoilscreen.jpg) ## Additional @@ -52,6 +52,6 @@ It didn't pull anything through to "New Games" and has not parsed any informatio That would be becasue the filename it has tried to pull had no TitleID (Improvement to RomM coming soon :tm:) Make sure the filename has the TitleID within the title like this: -![TitleID](h./romm.wiki/resources/titleid.jpg) +![TitleID](https://raw.githubusercontent.com/rommapp/wiki/refs/heads/main/romm.wiki/resources/tinfoil/titleid.jpg) Once this is done, the next time Tinfoil is opened it is always parsed and re-scanned. diff --git a/romm.wiki/resources/authentik/1-user-dashboard.png b/romm.wiki/resources/authentik/1-user-dashboard.png new file mode 100644 index 0000000..1c911f5 Binary files /dev/null and b/romm.wiki/resources/authentik/1-user-dashboard.png differ diff --git a/romm.wiki/resources/authentik/2-create-provider.png b/romm.wiki/resources/authentik/2-create-provider.png new file mode 100644 index 0000000..356f030 Binary files /dev/null and b/romm.wiki/resources/authentik/2-create-provider.png differ diff --git a/romm.wiki/resources/authentik/3-new-provider.png b/romm.wiki/resources/authentik/3-new-provider.png new file mode 100644 index 0000000..13e1fa0 Binary files /dev/null and b/romm.wiki/resources/authentik/3-new-provider.png differ diff --git a/romm.wiki/resources/authentik/4-provider-secrets.png b/romm.wiki/resources/authentik/4-provider-secrets.png new file mode 100644 index 0000000..911760b Binary files /dev/null and b/romm.wiki/resources/authentik/4-provider-secrets.png differ diff --git a/romm.wiki/resources/authentik/5-applications.png b/romm.wiki/resources/authentik/5-applications.png new file mode 100644 index 0000000..1c949d9 Binary files /dev/null and b/romm.wiki/resources/authentik/5-applications.png differ diff --git a/romm.wiki/resources/authentik/6-new-application.png b/romm.wiki/resources/authentik/6-new-application.png new file mode 100644 index 0000000..40ba081 Binary files /dev/null and b/romm.wiki/resources/authentik/6-new-application.png differ diff --git a/romm.wiki/resources/authentik/7-user-profile.png b/romm.wiki/resources/authentik/7-user-profile.png new file mode 100644 index 0000000..9e90c4b Binary files /dev/null and b/romm.wiki/resources/authentik/7-user-profile.png differ diff --git a/romm.wiki/resources/authentik/8-romm-login.png b/romm.wiki/resources/authentik/8-romm-login.png new file mode 100644 index 0000000..2b9079d Binary files /dev/null and b/romm.wiki/resources/authentik/8-romm-login.png differ diff --git a/romm.wiki/resources/tinfoilscreen.jpg b/romm.wiki/resources/tinfoil/tinfoilscreen.jpg similarity index 100% rename from romm.wiki/resources/tinfoilscreen.jpg rename to romm.wiki/resources/tinfoil/tinfoilscreen.jpg diff --git a/romm.wiki/resources/titleid.jpg b/romm.wiki/resources/tinfoil/titleid.jpg similarity index 100% rename from romm.wiki/resources/titleid.jpg rename to romm.wiki/resources/tinfoil/titleid.jpg