Multiuser and OpenId

.github/actions/spelling/expect.txt

@@ -57,3 +57,8 @@ VUB
 websecure
 WOR
 youngcw
+Authentik
+Entra
+Keycloak
+userinfo
+passwordless

docs-sidebar.js

@@ -227,6 +227,8 @@ const sidebars = {
           items: [
             'experimental/goal-templates',
             'experimental/monthly-cleanup',
+            'experimental/oauth-auth', 
+            'experimental/multi-user'
           ],
         },
         'getting-started/tips-tricks',

docs/experimental/multi-user.md

@@ -0,0 +1,49 @@
+# Managing Multi-User Support
+
+:::warning
+This is an **experimental feature**. That means we’re still working on finishing it. There may be bugs, missing functionality or incomplete documentation, and we may decide to remove the feature in a future release. If you have any feedback, please [open an issue](https://github.com/actualbudget/actual/issues) or post a message in the Discord.
+:::
+
+:::note
+Client Version 25.1.0 and
+Server Version 25.1.0 or higher are required for this feature.
+:::
+
+This feature is enabled by default when you setup an [OpenID Provider](oauth-auth). The usernames will be fetched from the provider.
+
+## User Directory
+
+Use this page to manage users who have access to the Actual Budget instance.
+
+To access the **User Directory** page, access the menu from the server:
+
+![](/static/img/multiuser/user-directory.png)
+
+Users can be added, disabled, enabled, removed from this page:
+
+![](/static/img/multiuser/user-directory-overview.png)
+
+There are two user roles _Basic_ or _Admin_.
+
+- The Basic role: 
+Users with the Basic role can create new budgets and collaborate on budgets made by others.
+This role is ideal for users who primarily need to manage and participate in shared budget activities.
+
+- The Admin role:
+This role can do everything the Basic user role can. It can also add new users to the user directory and allow all users to access budget files.
+The role can assign ownership of a budget to another person, ensuring efficient budget management.
+
+## User Access Management
+
+Use this page to manage user access to the current open budget file.
+
+:::info
+The **User Access Management** menu is only visible from within an open budget:
+
+![](/static/img/multiuser/user-access.png)
+
+:::
+
+This screen is where you assign, give and revoke budget access and transfer ownership:
+
+![](/static/img/multiuser/user-access-overview.png)

docs/experimental/oauth-auth.md

@@ -0,0 +1,120 @@
+# Authenticating With an OpenID Provider
+
+:::warning
+This is an **experimental feature**. That means we’re still working on finishing it. There may be bugs, missing functionality or incomplete documentation, and we may decide to remove the feature in a future release. If you have any feedback, please [open an issue](https://github.com/actualbudget/actual/issues) or post a message in the Discord.
+:::
+
+:::note
+Client Version 25.1.0 and
+Server Version 25.1.0 or higher are required for this feature.
+:::
+
+## Setup
+:::info
+This feature requires use of [Actual Server](../config/)
+:::
+
+If you require a more robust authentication method than a server password, it is recommended to use an OpenID provider. Most OpenID providers support multi-factor authentication, enhancing your application's security. Additionally, if you need support for multiple users, you must enable this feature.
+
+To enable this feature, you can use a configuration file `config.json` on the Actual server, or use the UI.
+
+### Configuration Using a Configuration File
+
+If your OpenID provider supports discovery, use the following configuration example:
+
+```json title="config.json"
+"openId": {
+        "issuer": "URL for the OpenID Provider",
+        "client_id": "client_id given by the provider",
+        "client_secret": "client_secret given by the provider",
+        "server_hostname": "your Actual Server URL (so the provider redirects you to this)",
+        "authMethod": "openid" // or "oauth2"
+    }
+```
+
+If your OpenID provider does not supports discovery, you have to configure each endpoint manually:
+
+```json title="config.json"
+"openId": {
+        "issuer": {
+            "name": "Friendly name for the issuer",
+            "authorization_endpoint": "Provider's authorize endpoint",
+            "token_endpoint": "Provider's access token endpoint",
+            "userinfo_endpoint": "Provider's user info endpoint"
+        },
+        "client_id": "client_id given by the provider",
+        "client_secret": "client_secret given by the provider",
+        "server_hostname": "your Actual Server URL (so the provider redirects you to this)",
+        "authMethod": "openid" // or "oauth2"
+    }
+```
+
+:::tip
+To use GitHub as an identity provider can only be achieved with configuration files using `"authMethod": "oauth2"`.
+:::
+
+### Configuration Using Environment Variables
+
+If your OpenID provider supports discovery, use the following variables:
+
+- `ACTUAL_OPENID_DISCOVERY_URL`: URL for the OpenID Provider
+- `ACTUAL_OPENID_CLIENT_ID`: client_id given by the provider
+- `ACTUAL_OPENID_CLIENT_SECRET`: client_secret given by the provider
+- `ACTUAL_OPENID_SERVER_HOSTNAME`: Your Actual Server URL (so the provider redirects you to this)
+
+If your OpenId provider does not supports discovery, use the following variables:
+
+- `ACTUAL_OPENID_AUTHORIZATION_ENDPOINT`: Provider's authorize endpoint
+- `ACTUAL_OPENID_TOKEN_ENDPOINT`: Provider's access token endpoint
+- `ACTUAL_OPENID_USERINFO_ENDPOINT`: Provider's user info endpoint
+- `ACTUAL_OPENID_CLIENT_ID`: client_id given by the provider
+- `ACTUAL_OPENID_CLIENT_SECRET`: client_secret given by the provider
+- `ACTUAL_OPENID_SERVER_HOSTNAME`: Your Actual Server URL (so the provider redirects you to this)
+
+### Configuring OpenID Using the UI
+
+Navigate into any Budget file, then in the Settings, click on _Start using OpenID_
+
+![](/static/img/oauth/start-using-options.png)
+
+Once you click _Start using OpenID_ a modal will be presented.
+
+##### Instructions
+Fill all the required field for the selected provider.
+
+![Configuration from options](/static/img/oauth/modal.png)
+
+Some providers does not require all fields to be filled out.
+
+As an example, the provider _passwordless.id_ does not need `client_secret`.
+
+When all settings are correctly filled out, click the 'OK' button, and you will be redirected to the login page.
+
+:::warning
+There are some basic configuration checks when clicking 'OK', but if you somehow type the wrong information and the data is saved, when you login for the first time using OpenID, you will have a chance to review the settings.
+:::
+
+#### Tested Providers
+- Auth0
+- Authentik
+- GitHub
+- Google Accounts
+- Keycloak
+- Microsoft Entra
+- Passwordless.id
+
+:::tip
+Each provider has different requirements. For example, for Auth0, the URL will be generated by default, but you have to change it with your own details:
+
+![](/static/img/oauth/provider-requirement.png)
+:::
+
+#### After Setup:
+
+When setup is done, you will be redirected to the _login_ page:
+
+![](/static/img/oauth/first-login.png)
+
+:::tip
+Configuring the OpenID provider from options supports discovery; otherwise, use [file configuration](oauth-auth#config-using-configuration-file)
+:::