Skip to content

Omni variable #108

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Omni variable #108

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
13f45cb
docs: add docs on auth
Iheanacho-ai Oct 23, 2025
1b3adea
docs: add omni variable
Iheanacho-ai Oct 24, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
106 changes: 14 additions & 92 deletions public/omni/infrastructure-and-extensions/self-hosted/deploy-omni-on-prem.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,8 @@
title: Deploy Omni on Prem
---

import { omni_release } from '/snippets/custom-variables.mdx';

This guide shows you how to deploy Omni on-prem. This guide assumes that Omni will be deployed on an Ubuntu machine. Small differences should be expected when using a different OS.

For SAML integration sections, this guide assumes Azure AD will be the provider for SAML.
Expand Down Expand Up @@ -151,36 +153,9 @@ There are two easy ways to run Omni: docker-compose and a simple `docker run`. W

#### Auth0

```bash
docker run \
--net=host \
--cap-add=NET_ADMIN \
--device /dev/net/tun \
-v $PWD/etcd:/_out/etcd \
-v <path to TLS certificate>:/tls.crt \
-v <path to TLS key>:/tls.key \
-v $PWD/omni.asc:/omni.asc \
ghcr.io/siderolabs/omni:<tag> \
--account-id=$(uuidgen) \
--name=onprem-omni \
--cert=/tls.crt \
--key=/tls.key \
--siderolink-api-cert=/tls.crt \
--siderolink-api-key=/tls.key \
--private-key-source=file:///omni.asc \
--event-sink-port=8091 \
--bind-addr=0.0.0.0:443 \
--siderolink-api-bind-addr=0.0.0.0:8090 \
--k8s-proxy-bind-addr=0.0.0.0:8100 \
--advertised-api-url=https://<domain name for onprem omni>/ \
--siderolink-api-advertised-url=https://<domain name for onprem omni>:8090/ \
--siderolink-wireguard-advertised-addr=<ip address of the host running Omni>:50180 \
--advertised-kubernetes-proxy-url=https://<domain name for onprem omni>:8100/ \
--auth-auth0-enabled=true \
--auth-auth0-domain=<Auth0 domain> \
--auth-auth0-client-id=<Auth0 client ID> \
--initial-users=<email address>
```
<CodeBlock lang="sh">
Copy link
Member

@rothgar rothgar Oct 24, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This block is really gross. Do we have to write it that way or can we keep line breaks? It'll be easier to maintain.

Copy link
Member Author

@Iheanacho-ai Iheanacho-ai Oct 24, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, apparently if I don’t format it this way, Mintlify adds extra indentation that messes up the code block. I asked Edward, and he suggested manually adding each line break and tab so it renders cleaner on the docs page.

Copy link
Member Author

@Iheanacho-ai Iheanacho-ai Oct 24, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

But ill look for another way

Copy link
Member

@rothgar rothgar Oct 24, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That's horrible 😠 If we have to do it this way that's fine but we should open an issue with mintlify to see if they can support standard line breaks when the render the blocks

{`docker run \\\n --net=host \\\n --cap-add=NET_ADMIN \\\n --device /dev/net/tun \\\n -v $PWD/etcd:/_out/etcd \\\n -v <path to TLS certificate>:/tls.crt \\\n -v <path to TLS key>:/tls.key \\\n -v $PWD/omni.asc:/omni.asc \\\n ghcr.io/siderolabs/omni:${omni_release} \\\n --account-id=$(uuidgen) \\\n --name=onprem-omni \\\n --cert=/tls.crt \\\n --key=/tls.key \\\n --siderolink-api-cert=/tls.crt \\\n --siderolink-api-key=/tls.key \\\n --private-key-source=file:///omni.asc \\\n --event-sink-port=8091 \\\n --bind-addr=0.0.0.0:443 \\\n --siderolink-api-bind-addr=0.0.0.0:8090 \\\n --k8s-proxy-bind-addr=0.0.0.0:8100 \\\n --advertised-api-url=https://<domain name for onprem omni>/ \\\n --siderolink-api-advertised-url=https://<domain name for onprem omni>:8090/ \\\n --siderolink-wireguard-advertised-addr=<ip address of the host running Omni>:50180 \\\n --advertised-kubernetes-proxy-url=https://<domain name for onprem omni>:8100/ \\\n --auth-auth0-enabled=true \\\n --auth-auth0-domain=<Auth0 domain> \\\n --auth-auth0-client-id=<Auth0 client ID> \\\n --initial-users=<email address>`}
</CodeBlock>

**Note:** The `siderolink-wireguard-advertised-addr` **must** point to an IP, not the domain name.

Expand All @@ -190,75 +165,22 @@ There are two easy ways to run Omni: docker-compose and a simple `docker run`. W

#### SAML

```bash
docker run \
--net=host \
--cap-add=NET_ADMIN \
--device /dev/net/tun \
-v $PWD/etcd:/_out/etcd \
-v <path to full chain TLS certificate>:/tls.crt \
-v <path to TLS key>:/tls.key \
-v $PWD/omni.asc:/omni.asc \
ghcr.io/siderolabs/omni:<tag> \
--account-id=$(uuidgen) \
--name=onprem-omni \
--cert=/tls.crt \
--key=/tls.key \
--siderolink-api-cert=/tls.crt \
--siderolink-api-key=/tls.key \
--private-key-source=file:///omni.asc \
--event-sink-port=8091 \
--bind-addr=0.0.0.0:443 \
--siderolink-api-bind-addr=0.0.0.0:8090 \
--k8s-proxy-bind-addr=0.0.0.0:8100 \
--advertised-api-url=https://<domain name for onprem omni>/ \
--siderolink-api-advertised-url=https://<domain name for onprem omni>:8090/ \
--siderolink-wireguard-advertised-addr=<ip address of the host running Omni>:50180 \
--advertised-kubernetes-proxy-url=https://<domain name for onprem omni>:8100/ \
--auth-saml-enabled=true \
--auth-saml-url=<app federation metadata url copied during Azure AD setup>
```
<CodeBlock lang="sh">
{`docker run \\\n --net=host \\\n --cap-add=NET_ADMIN \\\n --device /dev/net/tun \\\n -v $PWD/etcd:/_out/etcd \\\n -v <path to full chain TLS certificate>:/tls.crt \\\n -v <path to TLS key>:/tls.key \\\n -v $PWD/omni.asc:/omni.asc \\\n ghcr.io/siderolabs/omni:${omni_release} \\\n --account-id=$(uuidgen) \\\n --name=onprem-omni \\\n --cert=/tls.crt \\\n --key=/tls.key \\\n --siderolink-api-cert=/tls.crt \\\n --siderolink-api-key=/tls.key \\\n --private-key-source=file:///omni.asc \\\n --event-sink-port=8091 \\\n --bind-addr=0.0.0.0:443 \\\n --siderolink-api-bind-addr=0.0.0.0:8090 \\\n --k8s-proxy-bind-addr=0.0.0.0:8100 \\\n --advertised-api-url=https://<domain name for onprem omni>/ \\\n --siderolink-api-advertised-url=https://<domain name for onprem omni>:8090/ \\\n --siderolink-wireguard-advertised-addr=<ip address of the host running Omni>:50180 \\\n --advertised-kubernetes-proxy-url=https://<domain name for onprem omni>:8100/ \\\n --auth-saml-enabled=true \\\n --auth-saml-url=<app federation metadata url copied during Azure AD setup>
`}
</CodeBlock>

**Note**

In a default setup, the first user that logs in via SAML will be the “admin”. All subsequent users will receive a read-only role and may need to be granted additional access by the admin user from the “Users” tab in Omni.

#### OIDC

```bash
docker run \
--net=host \
--cap-add=NET_ADMIN \
--device /dev/net/tun \
-v $PWD/etcd:/_out/etcd \
-v <path to full chain TLS certificate>:/tls.crt \
-v <path to TLS key>:/tls.key \
-v $PWD/omni.asc:/omni.asc \
ghcr.io/siderolabs/omni:<tag> \
--account-id=$(uuidgen) \
--name=onprem-omni \
--cert=/tls.crt \
--key=/tls.key \
--siderolink-api-cert=/tls.crt \
--siderolink-api-key=/tls.key \
--private-key-source=file:///omni.asc \
--event-sink-port=8091 \
--bind-addr=0.0.0.0:443 \
--siderolink-api-bind-addr=0.0.0.0:8090 \
--k8s-proxy-bind-addr=0.0.0.0:8100 \
--advertised-api-url=https://<domain name for onprem omni>/ \
--siderolink-api-advertised-url=https://<domain name for onprem omni>:8090/ \
--siderolink-wireguard-advertised-addr=<ip address of the host running Omni>:50180 \
--advertised-kubernetes-proxy-url=https://<domain name for onprem omni>:8100/ \
--auth-oidc-enabled \
--auth-oidc-provider-url <URL of the OIDC provider> \
--auth-oidc-client-id <id copied from the OIDC provider> \
--auth-oidc-client-secret <secret copied from the OIDC provider> \
--auth-oidc-logout-url <logout URL, optional, copied from the OIDC provider> \
--auth-oidc-scopes openid \
--auth-oidc-scopes profile \
--auth-oidc-scopes email
```
<CodeBlock lang="sh">
{`
docker run \\\n --net=host \\\n --cap-add=NET_ADMIN \\\n --device /dev/net/tun \\\n -v $PWD/etcd:/_out/etcd \\\n -v <path to full chain TLS certificate>:/tls.crt \\\n -v <path to TLS key>:/tls.key \\\n -v $PWD/omni.asc:/omni.asc \\\n ghcr.io/siderolabs/omni:${omni_release} \\\n --account-id=$(uuidgen) \\\n --name=onprem-omni \\\n --cert=/tls.crt \\\n --key=/tls.key \\\n --siderolink-api-cert=/tls.crt \\\n --siderolink-api-key=/tls.key \\\n --private-key-source=file:///omni.asc \\\n --event-sink-port=8091 \\\n --bind-addr=0.0.0.0:443 \\\n --siderolink-api-bind-addr=0.0.0.0:8090 \\\n --k8s-proxy-bind-addr=0.0.0.0:8100 \\\n --advertised-api-url=https://<domain name for onprem omni>/ \\\n --siderolink-api-advertised-url=https://<domain name for onprem omni>:8090/ \\\n --siderolink-wireguard-advertised-addr=<ip address of the host running Omni>:50180 \\\n --advertised-kubernetes-proxy-url=https://<domain name for onprem omni>:8100/ \\\n --auth-oidc-enabled \\\n --auth-oidc-provider-url <URL of the OIDC provider> \\\n --auth-oidc-client-id <id copied from the OIDC provider> \\\n --auth-oidc-client-secret <secret copied from the OIDC provider> \\\n --auth-oidc-logout-url <logout URL, optional, copied from the OIDC provider> \\\n --auth-oidc-scopes openid \\\n --auth-oidc-scopes profile \\\n --auth-oidc-scopes email
`}
</CodeBlock>

**Note**

Expand Down
42 changes: 26 additions & 16 deletions public/omni/security-and-authentication/authentication-and-authorization.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,28 +2,38 @@
title: Authentication and Authorization
---

### Auth0
Omni integrates with several identity providers to authenticate users securely. This page provides an overview of supported authentication methods and how they affect user and role management.

#### Github
## Auth0

In order to login with GitHub you must use your primary verified email.
Omni supports authentication via Auth0.

### OIDC
### GitHub

OpenID Connect (OIDC) is an identity layer built on top of the OAuth 2.0 protocol that provides user authentication and basic profile information for web and mobile applications.
When logging in with GitHub, you must use your primary verified email address.

### SAML
## OIDC

Security Assertion Markup Language (SAML) is an open standard that allows identity providers (IdP) to pass authorization credentials to service providers (SP). Omni plays the role of service provider.
OpenID Connect (OIDC) is an identity layer built on top of the OAuth 2.0 protocol. It provides user authentication and basic profile information for web and mobile applications. Omni can be configured to use OIDC providers to authenticate users.

To enable SAML on your account please submit a ticket in [Zendesk](https://sidero.zendesk.com/). Or reach out to us in the #omni channel in [Slack](https://slack.dev.talos-systems.io/).
## SAML

SAML alters Omni user management:
Security Assertion Markup Language (SAML) is an open standard that enables identity providers (IdPs) to pass authentication and authorization information to service providers (SPs). In this workflow, Omni acts as the service provider.

* Users are automatically created on the first login into Omni:
* the first user gets `Admin` role;
* any subsequently created user gets `None` role.
* `Admin` can change other users' roles.
* Creating or deleting a user is not possible from within Omni - only within the IdP.
* Omni gets the user attributes from the SAML assertion and adds them as labels to `Identity` resource with `saml.omni.sidero.dev/` prefix.
* ACL can be used to adjust fine grained permissions instead of changing the user roles.
To enable SAML for your account, please submit a ticket through [Zendesk](https://sidero.zendesk.com/) or contact us in the `#omni` channel on [Slack](https://slack.dev.talos-systems.io/).

Using SAML changes how user identities are managed in Omni:

* Users are created automatically on their first login to Omni.
* The first user created is assigned the `Admin` role.
* All subsequent users are assigned the `None` role.
* An `Admin` can modify the roles of other users.
* User creation and removal must be performed in the IdP — not in Omni.
* Attributes from the SAML assertion are added to the user’s `Identity` resource with the prefix `saml.omni.sidero.dev/`.
* Access Control Lists (ACLs) can be used to grant fine-grained permissions beyond roles.

## Authentication for Automation

In addition to interactive login, `omnictl` can also be used in automation. When using user authentication in non-interactive workflows, Omni issues short-lived credentials that expire after a limited time. User tokens can remain valid for up to eight hours, and Omni-generated user public keys currently expire after four hours. These limits are not configurable.

Because of this, long-running automation or CI/CD pipelines that rely on user authentication may fail when credentials expire. To ensure uninterrupted access for automation, scripts, and other non-interactive use cases, we recommend using Omni Service Accounts instead of user authentication.
3 changes: 3 additions & 0 deletions public/snippets/custom-variables.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,9 @@
{/* latest Kubernetes release version */}
export const k8s_prev_release = '1.33.0'
export const k8s_release = '1.34.0'

{/* latest Omni release version */}
export const omni_release = 'v1.2.1'

{/* latest Talos release version */}
export const release = 'v1.11.0'
Expand Down