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.

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.

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: [email protected]

Only [email protected] 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).