# Authenticating With an OpenID Provider

## 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](/docs/config/) `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": {
        "discoveryURL": "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_

![](/img/oauth/start-using-options.webp)

Once you click _Start using OpenID_ a modal will be presented.

##### Instructions

Fill all the required field for the selected provider.

![Configuration from options](/img/oauth/modal.webp)

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

:::tip
When configuring your OpenID provider, be sure to register the following **redirect URI** with the provider: `https://<actual.myserver.com>/openid/callback`
:::

#### Tested Providers

- Auth0
- Authentik
- GitHub
- Google Accounts
- Keycloak
- Microsoft Entra
- Passwordless.id
- Pocket 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:

![](/img/oauth/provider-requirement.webp)
:::

#### After Setup

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

![](/img/oauth/first-login.webp)

### Environment Variables

#### `ACTUAL_OPENID_DISCOVERY_URL`

- **Purpose:** If your OpenID provider supports discovery, this is the URL where discovery metadata can be found.
  **Example Value:** `https://<openid-provider.com>/.well-known/openid-configuration`

#### `ACTUAL_OPENID_CLIENT_ID`

- **Purpose:** The client ID issued by your OpenID provider.
  **Example Value:** `my-actual-app`

#### `ACTUAL_OPENID_CLIENT_SECRET`

- **Purpose:** The client secret issued by your OpenID provider.
  **Example Value:** `super-secret-value`

#### `ACTUAL_OPENID_SERVER_HOSTNAME`

- **Purpose:** The public URL of your Actual Server, which the provider redirects to after authentication.
  **Example Value:** `https://<actual.myserver.com>`

#### `ACTUAL_OPENID_AUTHORIZATION_ENDPOINT`

- **Purpose:** Provider's authorization endpoint (for providers that don't support discovery).
  **Example Value:** `https://<openid-provider.com>/oauth2/authorize`

#### `ACTUAL_OPENID_TOKEN_ENDPOINT`

- **Purpose:** Provider's token endpoint (for providers that don't support discovery).
  **Example Value:** `https://<openid-provider.com>/oauth2/token`

#### `ACTUAL_OPENID_USERINFO_ENDPOINT`

- **Purpose:** Provider's user-info endpoint (for providers that don't support discovery).
  **Example Value:** `https://<openid-provider.com>/oauth2/userinfo`

#### `ACTUAL_OPENID_AUTH_METHOD`

- **Purpose:** Tells the server whether it should use the OpenID (OIDC) or a more general OAuth2 flow.
  **Possible Values:**
  - `openid` (default)
  - `oauth2`

:::tip
Use `oauth2` for providers like GitHub that don't fully support OpenID discovery.
:::

#### `ACTUAL_OPENID_ENFORCE`

- **Purpose:** Forces OpenID/OAuth2 authentication as the only allowed login method when set to `true`.
  **Example Value:** `true` or `false` (default is `false`)

#### `ACTUAL_TOKEN_EXPIRATION`

- **Purpose:** Controls how access tokens expire.
  **Possible Values:**
  - `"never"` (tokens never expire - **current default**)
  - `"openid-provider"` (tokens follow the expiration time from the OpenID provider)
  - A numeric value in seconds (e.g., `3600` for 1 hour)

:::tip
Configuring the OpenID provider from options supports discovery; otherwise, use [file configuration](oauth-auth#config-using-configuration-file)
:::
