Access controls

Tinyauth supports basic access controls with either Docker labels or environment variables. These labels (or environment variables) can restrict or allow access to applications.

Proxy configuration matters

Tinyauth relies on the X-Forwarded-Host header (set by your reverse proxy) to determine which app’s access controls apply to a given request. If your proxy doesn’t overwrite this header, or if Tinyauth is directly reachable on the network without going through the proxy, a user could send a request with a spoofed host that doesn’t match any configured app. When no app matches, Tinyauth treats the request as having no restrictions and allows any authenticated user through.

To avoid this, make sure your reverse proxy always sets X-Forwarded-Host itself and doesn’t pass through client-supplied values. Traefik and Caddy do this by default. For Nginx, use proxy_set_header X-Forwarded-Host $host; in your location block. You should also make sure Tinyauth is not directly accessible from the network — only your reverse proxy should be able to reach it.

It is also recommended (and required for IP address ACLs) that your proxy sets correctly the X-Forwarded-For and X-Real-IP headers so Tinyauth can get the correct client IP and perform ACLs. You will also need to configure the TINYAUTH_AUTH_TRUSTEDPROXIES environment variable (--auth.trustedproxies for CLI flags and auth.trustedProxies for YAML) to point to your proxy IP. In case your proxy runs in Docker, you will most likely need to run it with network_mode: host.

Modifying the Tinyauth Container

Note

You can skip this step if you’re using environment variables.

To enable access controls, add the following volume to the Tinyauth container:

services:
  tinyauth:
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock

Restart Tinyauth after setting the volume.

Note

For increased security, use a Docker socket proxy like Tecnativa’s. Configure Tinyauth to use the proxy by adding the following environment variable:

services:
  tinyauth:
    environment:
      DOCKER_HOST: tcp://docker-socket-proxy:2375

Ensure Tinyauth can reach the Docker socket proxy container.

If you like, you can also restrict Tinyauth’s access to the Docker socket using the following labels:

services:
  tinyauth:
    labels:
        socket-proxy.allow.get: /v1\..*/(version|containers/.*|events.*)|/_ping
        socket-proxy.allow.head: /_ping

Thank you @dombyte for the suggestion.

Access Controls Structure

Access control labels follow this structure:

tinyauth.apps.[app].[key]: [value]

Similarly environment variables follow this structure:

TINYAUTH_APPS_[APP]_[KEY]=[VALUE]

Where [app] is the name of the app to protect. This app ID must be unique for each protected app.

Access Controls Discovery

Tinyauth uses the app ID in labels (or environment variables) and the request subdomain to match the configuration with the app. For example, a request to app1.example.com triggers Tinyauth to search for containers with the tinyauth.apps.app1.foo: bar label or the TINYAUTH_APPS_APP1_FOO=bar environment variable. To use the domain instead, add the following label:

tinyauth.apps.myapp.config.domain: myapp.example.com

Or the following environment variable:

TINYAUTH_APPS_MYAPP_CONFIG_DOMAIN=myapp.example.com

Tinyauth will now use the domain to match the configuration instead of the app ID.

Note

Labels can be set either on the Tinyauth container or the app. However, if you use multiple hosts and the app is running on a different host than Tinyauth, labels must be set on the Tinyauth container.

Caution

Labels are dynamic and can be updated at runtime, environment variables are not and require a restart of Tinyauth to take effect.

Access Control Policy

Tinyauth supports both an allow-by-default and a deny-by-default approach in access controls. The policy can be defined using the TINYAUTH_AUTH_ACLS_POLICY environment variable or the --auth.acls.policy CLI flag. The configuration option supports either deny or allow. The default policy is allow.

In both examples we have the following ACLs defined as Docker labels.

tinyauth.apps.myapp.config.domain: myapp.example.com

Allow-by-default example

In this example we have TINYAUTH_AUTH_ACLS_POLICY=allow.

With this config, every user you define in Tinyauth will be allowed unless you set up a user allow or block list.

Deny-by-default example

In this example we have TINYAUTH_AUTH_ACLS_POLICY=deny.

With this config, every user you define in Tinyauth will be denied access to the app unless you manually allow them with a whitelist.

Caution

Due to the setup-specific nature of the IP and OAuth Group access controls, they are excluded from the deny-by-default policy and are only applied if you manually specify a blocklist.

User ACLs

Going forward, the guide will use the labels format but everything mentioned also applies to environment variables.

To restrict access to specific users, use the users.allow label:

tinyauth.apps.myapp.users.allow: user1

Only user1 will be able to access the app. To block specific users, use the users.block label:

tinyauth.apps.myapp.users.block: user2

Note

Both users.allow and users.block labels can accept a comma-separated list of users or a regex string (enclosed with /).

Note

These labels also apply to LDAP users.

OAuth Whitelist

To restrict access to specific OAuth users, use the oauth.whitelist label:

tinyauth.apps.myapp.oauth.whitelist: user1@example.com

Only user1@example.com will be able to access the app.

Note

The oauth.whitelist label can accept a comma-separated list of users or a regex string (enclosed with /).

Path ACLs

To skip authentication for specific paths, use the path.allow label:

tinyauth.apps.myapp.path.allow: ^\/api

To block access to specific paths, use the path.block label:

tinyauth.apps.myapp.path.block: ^\/admin

Caution

Path labels use regex strings. For example, ^\/api matches paths starting with /api, while ^\/ping$ matches the exact path /ping.

IP-Based Access Controls

To allow access based on IP addresses or CIDRs, use the ip.allow label:

tinyauth.apps.myapp.ip.allow: 10.10.5.5,10.10.10.0/24

To block specific IPs or subnets, use the ip.block label:

tinyauth.apps.myapp.ip.block: 192.168.1.1,192.168.0.0/16

Bypassing Authentication for IPs

To disable authentication for specific IPs or subnets, use the ip.bypass label:

tinyauth.apps.myapp.ip.bypass: 10.10.5.5,10.10.10.0/24

Access Controls Using OIDC Groups

Some OIDC servers, like Pocket ID, support user groups in the OIDC response. To use groups, ensure the groups scope is included in the OAuth provider configuration. Then, add the oauth.groups label:

tinyauth.apps.myapp.oauth.groups: admin

Only users in the admin group will be allowed to access the app.

Caution

The oauth.groups label is only supported for custom OAuth providers, not for Google or GitHub.

Access Controls Using LDAP Groups

Tinyauth also supports fetching the user’s groups from the LDAP server and using them for access control. To use LDAP groups, add the ldap.groups label:

tinyauth.apps.myapp.ldap.groups: admin

Only users in the admin group will be allowed to access the app.

Note

For performance reasons, LDAP groups are not fetched for every request. Instead, they are fetched periodically and cached. By default, the cache is refreshed every 15 minutes. If you need to refresh the cache more frequently you can change the TINYAUTH_LDAP_GROUPCACHETTL environment variable (accepts interval in seconds).