Authenticating With an OpenID Provider

danger

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 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

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:

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:

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

Once you click Start using OpenID a modal will be presented.

Instructions

Fill all the required field for the selected provider.

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.

danger

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:

After Setup:

When setup is done, you will be redirected to the login page:

tip

Configuring the OpenID provider from options supports discovery; otherwise, use file configuration