Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.siderolabs.com/llms.txt

Use this file to discover all available pages before exploring further.

Tailscale provides seamless OIDC authentication through tsidp. When accessing Omni through Tailscale, you can make use of this through the following steps.

​
Prerequisites

You will need a Tailscale account with the MagicDNS and HTTPS certificates features enabled.

​
Tailscale setup

Browse to https://login.tailscale.com/admin/acls/file to edit the access controls for your tailnet, and add the following JSON to the grants section:
tsidp-grant.json
  "grants": [
    {
      "src": ["*"],
      "dst": ["*"],
      "app": {
        "tailscale.com/cap/tsidp": [
          {
            "users": ["*"],
            "resources": ["*"],
            "allow_admin_ui": true,
            "allow_dcr": true,
            "extraClaims": {
              "email_verified": true
            },
            "includeInUserInfo": true
          }
        ]
      }
    }
  ]
On https://login.tailscale.com/admin/settings/keys, generate a new auth key. Make sure to select Reusable so it can be used for both tsidp and the Tailscale reverse proxy used for Omni. Finally, go to https://login.tailscale.com/admin/dns and note your Tailnet DNS name.

​
Prepare deployment

Before proceeding, set your Tailnet DNS name as a variable, it is referenced throughout the steps below: 
export TAILNET_DNS=<your-tailnet.ts.net>
Step 1: Set up your environment Create a .env file with your Tailscale auth key and the tsidp issuer URL: 
cat <<EOF > .env
TS_AUTHKEY=<your-generated-key>
OIDC_ISSUER_URL=https://tsidp.${TAILNET_DNS}
EOF
Step 2: Generate the Omni encryption key Generate a GPG key used to encrypt data written to etcd at rest. Copy the fingerprint printed by --list-secret-keys and paste it into the --quick-add-key command: 
gpg --quick-generate-key "Omni (Used for etcd data encryption) how-to-guide@siderolabs.com" rsa4096 cert never
gpg --list-secret-keys
gpg --quick-add-key <fingerprint> rsa4096 encr never
gpg --export-secret-key --armor how-to-guide@siderolabs.com > omni.asc
Step 3: Configure the Tailscale reverse proxy Create serve-config.json. This tells the Tailscale sidecar which ports to expose over HTTPS and where to forward incoming traffic: 
cat <<EOF > serve-config.json
{
  "TCP": {
    "443": {
      "HTTPS": true
    },
    "8090": {
      "HTTPS": true
    },
    "8100": {
      "HTTPS": true
    }
  },
  "Web": {
    "omni.${TAILNET_DNS}:443": {
      "Handlers": {
        "/": {
          "Proxy": "http://omni:8080"
        }
      }
    },
    "omni.${TAILNET_DNS}:8090": {
      "Handlers": {
        "/": {
          "Proxy": "http://omni:8090"
        }
      }
    },
    "omni.${TAILNET_DNS}:8100": {
      "Handlers": {
        "/": {
          "Proxy": "http://omni:8100"
        }
      }
    }
  }
}
EOF
Step 4: Define the service stack Create docker-compose.yml. This defines three services: tsidp as the OIDC provider, omni-tailscale as the Tailscale reverse proxy, and omni itself. Replace <your-admin-email> with the email address of the first Omni admin. 
cat <<EOF > docker-compose.yml
services:
  tsidp:
    image: ghcr.io/tailscale/tsidp:latest
    environment:
      - TAILSCALE_USE_WIP_CODE=1
      - TS_HOSTNAME=tsidp
    volumes:
      - tsidp-data:/var/lib/tsidp
    env_file:
      - .env
    command:
      - "--dir=/var/lib/tsidp"

  omni-tailscale:
    image: tailscale/tailscale:latest
    environment:
      - TS_SERVE_CONFIG=/config/serve.json
      - TS_HOSTNAME=omni
      - TS_STATE_DIR=/var/lib/tailscale
    env_file:
      - .env
    volumes:
      - ./serve-config.json:/config/serve.json:ro
      - ts-state:/var/lib/tailscale

  omni:
    image: ghcr.io/siderolabs/omni:latest
    volumes:
      - omni-data:/_out/etcd
      - ./omni.asc:/omni.asc:ro
      - /dev/net/tun:/dev/net/tun
    cap_add:
      - NET_ADMIN
    command:
      - --private-key-source=file:///omni.asc
      - --advertised-api-url=https://omni.${TAILNET_DNS}/
      - --machine-api-advertised-url=https://omni.${TAILNET_DNS}:8090/
      - --advertised-kubernetes-proxy-url=https://omni.${TAILNET_DNS}:8100/
      - --siderolink-wireguard-advertised-addr=omni.${TAILNET_DNS}:50180
      - --auth-oidc-enabled
      - --auth-oidc-provider-url=\${OIDC_ISSUER_URL}
      - --auth-oidc-client-id=\${OIDC_CLIENT_ID}
      - --auth-oidc-client-secret=\${OIDC_CLIENT_SECRET}
      - --auth-oidc-scopes=openid
      - --auth-oidc-scopes=profile
      - --auth-oidc-scopes=email
      - --initial-users=<your-admin-email>

volumes:
  tsidp-data:
  ts-state:
  omni-data:
EOF
Alternatively, you can configure the OIDC authentication flags above using a configuration file instead. See OIDC in the Omni Configuration Examples.

​
OIDC client setup

At this point all that’s left to do is register Omni as an OIDC client in tsidp. Start up only tsidp first: 
docker compose up tsidp
Browse to https://tsidp.${TAILNET_DNS} and create a new client. For the redirect URI, use https://omni.${TAILNET_DNS}/oidc/consume. Copy the client ID and secret that tsidp generates, then append them to your .env file: 
cat <<EOF >> .env
OIDC_CLIENT_ID=<paste-client-id-here>
OIDC_CLIENT_SECRET=<paste-secret-here>
EOF
Now start up the complete stack: 
docker compose up
Browse to https://omni.${TAILNET_DNS}/. You should be prompted to log in with your Tailscale user and then taken to the Omni UI. If login fails, you may need to update the --initial-users value in docker-compose.yml to match the email address displayed on the login screen.