v5.0.0

# Tinyauth v5.0.0

> [!WARNING]
> This is a breaking release, please refer to the [documentation](https://tinyauth.app/docs/breaking-updates/4-to-5) for migration instructions.

> [!WARNING]
> This release contains security fixes. Updating as soon as possible is recommended.

Hello everyone,

Today I am thrilled to announce the release of Tinyauth v5, the OIDC release. This version has been in the making for almost 4 months and we can now confidently say that Tinyauth is the tiniest authentication and ***authorization*** server! Let's dive into the most exciting new features.

## Overview

### Unified Config

The main reason this release is a breaking one is the complete configuration overhaul. In previous versions, CLI configuration differed from environment variables causing confusion. Additionally, the code handling the parsing of dynamic config (like the OAuth providers) was fragile and prone to issues. In v5, Tinyauth switched to Traefik's well tested [paerser](https://github.com/traefik/paerser) library which allows the configuration to be much more robust. From now on, you can have configuration with environment variables which will look like:

```sh
TINYAUTH_AUTH_LOGINTIMEOUT=bar
TINYAUTH_OAUTH_PROVIDERS_MYPROVIDER_CLIENTID=foo
```

Or CLI flags:

```sh
--auth.loginTimeout=bar
--oauth.providers.myprovider.clientId=foo
```

Or even a YAML configuration:

```yaml
auth:
  loginTimeout: bar

oauth:
  providers:
    myprovider:
      clientId: foo
```

Unfortunately, this means that all previous means of configuration are deprecated and are no longer supported. Please migrate your configuration to the new configuration options as described in the [documentation](https://beta.tinyauth.app/docs/reference/configuration). Migration may be inconvenient, but this unifies configuration permanently and prevents future breaking changes.

### Non-Docker Access Controls 

A much requested feature for a long time was the ability to configure access controls when not using Docker. The reason this was not possible was the fragile configuration parsing code. Now with the new parser, you can configure ACLs as normal configuration options following the new configuration convention. For example, let's allow only `user1` in the `foo` app:

```sh
TINYAUTH_APPS_FOO_USERS_ALLOW=user1
```

Restart Tinyauth and you are done. Prefer CLI flags? Sure thing:

```sh
--apps.foo.users.allow=user1
```

### OIDC Server

Tinyauth now includes an OIDC implementation (core and discovery) that can either bridge your existing authentication methods (multiple OAuth providers, LDAP) into a single source of truth or act as the authentication gateway for all of your self-hosted apps eliminating the need to configure multiple authentication mechanisms per application.

Following the project's base idea, the OIDC implementation is mostly stateless[^1] but, unfortunately some persistent storage is required for the app's public and private keys. Fortunately, the keys live in the same directory as your session database so you should already be set. In case you don't have an existing volume, you will need to add one[^2]:

```yaml
services:
  tinyauth:
    volumes:
      - ./data:/data
```

As with the rest of the configuration, clients can be configured with environment variables (or CLI flags):

```sh
TINYAUTH_OIDC_CLIENTS_MYCLIENT_CLIENTID=replace-me-with-a-random-string
TINYAUTH_OIDC_CLIENTS_MYCLIENT_CLIENTSECRET=replace-me-with-a-random-string
TINYAUTH_OIDC_CLIENTS_MYCLIENT_TRUSTEDREDIRECTURIS=https://myapp.example.com/callback
TINYAUTH_OIDC_CLIENTS_MYCLIENT_NAME=My Awesome App
```

Finally, you can use your client ID and secret in your app's OIDC configuration alongside with the following URLs:

| URL | Description |
| - | - |
| `https://tinyauth.example.com/authorize`  | Authorize endpoint |
| `https://tinyauth.example.com/api/oidc/token` | Token endpoint |
| `https://tinyauth.example.com/api/oidc/userinfo` | Userinfo token |

Restart Tinyauth and enjoy!

[^1]: Some compromises had to be made for the server to remain stateless. For more information please consult the [documentation](https://tinyauth.app/docs/guides/oidc/#limitations).

[^2]: The volume is only required if you need the OIDC server, otherwise you can safely omit it.

### Automatic Session Refresh

Sometimes, you may be working with an application that doesn't make as frequent requests and results in your session expiring before you can finish your work. Tinyauth now addresses this issue by monitoring the requests and refreshing your session when it's close to expiring but you are still working on something. The max session lifetime and the refresh time are also user-configurable. 

### LDAP Groups ACLs

If you are running an LDAP server as a source for your Tinyauth users, you may already have user groups in place to manage your users. With v5, Tinyauth can extract the groups from your users and apply them to ACLs. For instance, you can have the `foo` app only allow users that are in the `trusted` group in your LDAP server.

```yaml
services:
  foo:
    labels:
      tinyauth.apps.foo.ldap.groups: trusted
```

As long as the user is in the `trusted` group, you are in.

For all of this to happen, I would like to say a big thank you to the community for providing ideas, feedback, pull requests and coffee : ).

As always, below are the full release notes.

## New Features

- Experimental config file support
- Add support for Envoy proxy @pushpinderbal
- Refresh session cookie whilst session is active
- Forward `sub` claim from OAuth providers in the `Remote-Sub` header
- Support for ACLs using environment variables/CLI flags/config file
- Add mTLS / client certificate authentication support in LDAP @plaes
- Add support for global IP filters
- Configurable component-level logging @pushpinderbal
- LDAP group ACLs
- Auto submit TOTP code when it gets typed in
- OIDC server

## Improvements

- Auto create database directory if it doesn't exist @modrin
- Use one unified config format for environment variables, CLI flags and config file
- Improve frontend performance by minimizing use-effect calls and chunk size @nicotsx

## Fixes

- Fix language detection storing incorrect code in local storage
- Add rate-limiting in the forward auth endpoint to prevent brute-force attacks using basic auth @offw0rld
- Hide username provider when no users are configured @pushpinderbal
- Set Gin mode in code rather than environment variables
- Improve redirect validation to prevent open redirect edge cases

## Technical

- Bump dependencies
- Update translations
- Fix [CVE-2025-55182](https://github.com/advisories/GHSA-fv66-9v8q-g76r "CVE-2025-55182") in React @d3vv3
- Split app bootstrap into smaller jobs for better readability and maintainability
- Use correct module name - Tinyauth now listed in [pkg.go.dev](https://pkg.go.dev/github.com/steveiliop56/tinyauth)
- Replace GORM with vanilla SQL and SQLC for smaller size and more maintainable code
- Add a `Makefile` to simplify development
- Simplify user parsing logic since we can offload things to paerser

## New Contributors

* @d3vv3 made their first contribution in https://github.com/steveiliop56/tinyauth/pull/507
* @modrin made their first contribution in https://github.com/steveiliop56/tinyauth/pull/510
* @exenza made their first contribution in https://github.com/steveiliop56/tinyauth/pull/525
* @pushpinderbal made their first contribution in https://github.com/steveiliop56/tinyauth/pull/551
* @plaes made their first contribution in https://github.com/steveiliop56/tinyauth/pull/509
* @andreribeiro87 made their first contribution in https://github.com/steveiliop56/tinyauth/pull/599
* @nicotsx made their first contribution in https://github.com/steveiliop56/tinyauth/pull/641

Please let me know of any issues so as I can fix them as soon as possible.