Security¶

Security model for SigNoz covering OTLP ingestion authentication, ClickHouse security, SSO integration, API tokens, service accounts, and data retention. See also: observability/signoz/index, observability/signoz/architecture, observability/signoz/operations.

Security Architecture Overview¶

SigNoz uses a multi-layer security model with the SigNoz Query Service as the central authorization point. Data is stored in ClickHouse, and telemetry is ingested via OpenTelemetry Collectors (SigNoz Otel Collector).

flowchart TD
    subgraph "External"
        Apps[Instrumented Applications]
        Users[Browser / API Users]
        IdP[Identity Provider<br/>SAML / OIDC / Google]
    end

    subgraph "Ingestion Layer"
        Collector[SigNoz Otel Collector<br/>OTLP Receiver]
    end

    subgraph "SigNoz Platform"
        QS[Query Service<br/>Auth / RBAC / API]
        Frontend[Frontend UI]
    end

    subgraph "Data Store"
        CH[(ClickHouse<br/>Traces / Logs / Metrics)]
    end

    Apps -->|OTLP + ingestion key| Collector
    Collector -->|Write| CH
    Users -->|Login / SSO| Frontend
    Frontend --> QS
    QS -->|Validate auth| IdP
    QS -->|Read/Write| CH

OTLP Ingestion Authentication¶

Ingestion Keys¶

All telemetry data sent to SigNoz must include an ingestion key for authentication. Two header formats are supported:

SigNoz Cloud:

# OpenTelemetry Collector OTLP exporter
exporters:
  otlp:
    endpoint: "ingest.us.signoz.cloud:443"
    tls:
      insecure: false
    headers:
      "signoz-ingestion-key": "<your-ingestion-key>"

Self-hosted (via API key):

exporters:
  otlphttp:
    endpoint: https://signoz.YOUR_DOMAIN:443
    headers:
      signoz-access-token: "<your-api-key>"

Ingestion Key vs API Key

Ingestion keys grant write-only access to the data pipeline. API keys (used for management APIs) have broader permissions depending on the associated role. Use ingestion keys for collectors and API keys for management automation.

Query Service Authentication¶

The Query Service validates all API requests:

GET /api/v1/service_accounts/me
SIGNOZ-API-KEY: <your-service-account-key>

ClickHouse Security¶

Connection Security¶

SigNoz connects to ClickHouse using the native TCP protocol (port 9000) or HTTP interface (port 8123). Security hardening:

Dedicated user: Create a ClickHouse user specifically for SigNoz with access limited to signoz_metrics, signoz_logs, and signoz_traces databases.
Password authentication: Required by default; configure in the SigNoz ClickHouse connection settings.
TLS: Enable ClickHouse native TLS (<tcp_port_secure>9440</tcp_port_secure>) or HTTPS for the HTTP interface.

# ClickHouse user configuration
users:
  signoz:
    password: "<secure-password>"
    networks:
      ip:
        - "10.0.0.0/8"    # Restrict to internal network
        - "172.16.0.0/12"
    profile: default
    quota: default
    databases:
      signoz_metrics: ["SELECT", "INSERT", "CREATE", "ALTER"]
      signoz_logs: ["SELECT", "INSERT", "CREATE", "ALTER"]
      signoz_traces: ["SELECT", "INSERT", "CREATE", "ALTER"]

Schema Migrations¶

SigNoz manages ClickHouse schema through a migration system with three phases:

# Bootstrap migration (initial setup)
./signoz-otel-collector migrate bootstrap \
    --clickhouse-dsn="tcp://localhost:9000?password=password" \
    --clickhouse-replication=true

# Synchronous migration (schema changes)
./signoz-otel-collector migrate sync up \
    --clickhouse-dsn="tcp://localhost:9000?password=password" \
    --clickhouse-replication=true

# Asynchronous migration (data backfill)
./signoz-otel-collector migrate async up \
    --clickhouse-dsn="tcp://localhost:9000?password=password" \
    --clickhouse-replication=true

Migration Privileges

The migration system requires CREATE and ALTER permissions on the ClickHouse databases. For production, run migrations with an elevated user and use a restricted user for the Query Service's daily operations.

Distributed ClickHouse Security¶

For clustered deployments, secure inter-node communication:

# values.yaml for distributed ClickHouse
clickhouse:
  layout:
    shardsCount: 2
    replicasCount: 2
  zookeeper:
    replicaCount: 3
schemaMigrator:
  enableReplication: true

Enable TLS between ClickHouse nodes (<interserver_http_host> with HTTPS).
Secure ZooKeeper connections with TLS and digest authentication.
Restrict inter-node traffic to private network only.

SSO Integration¶

Supported SSO Methods¶

SigNoz supports three SSO protocols, available in both Cloud and self-hosted Enterprise:

Method	Protocol	IdP Examples
SAML 2.0	SAML	Okta, Azure AD, OneLogin, Keycloak, AWS SSO
OIDC	OpenID Connect	Okta, Azure AD, Auth0, Keycloak
Google Workspace	OAuth2	Google Workspace

SAML Configuration¶

SAML is configured per email domain. When a user from a registered domain logs in, SigNoz delegates authentication to the configured IdP.

Configuration fields: - Domain: Email domain to associate with the IdP (e.g., example.com). - SAML ACS URL / IDP URL: The assertion consumer service URL from the IdP. - SAML X.509 Certificate: Public certificate for signature verification. - SAML Entity ID: Unique identifier for the SigNoz service provider. - Skip AuthN Requests Signed: Whether to skip signing authn requests.

Domain: example.com
SAML ACS URL/SAML IDP URL: https://idp.YOUR_DOMAIN/saml/sso
SAML X.509 Certificate: <certificate-data>
SAML Entity ID: https://signoz.YOUR_DOMAIN
Skip AuthN Requests Signed: True

SSO Features¶

Just-in-Time provisioning: Users are automatically created on first SSO login.
Attribute mapping: IdP claims mapped to SigNoz user fields (name, email).
Role mapping: IdP group memberships or attributes automatically assigned to SigNoz roles.
Enforce SSO: Require all users from a domain to authenticate via SSO (disables password login).

API Authentication¶

Service Accounts¶

Service accounts enable automated workloads to interact with the SigNoz API:

GET /api/v1/service_accounts/me
SIGNOZ-API-KEY: <your-service-account-key>

Service accounts support: - Role assignment: Viewer, Editor, Admin roles control API access scope. - Multiple keys: Each service account can have multiple API keys. - Key rotation: Keys can be rotated without deleting the service account.

Terraform Provider¶

The SigNoz Terraform provider uses API keys for authentication:

provider "signoz" {
  endpoint     = "https://signoz.YOUR_DOMAIN"
  access_token = var.signoz_api_key
}

Best practice: store the access token in environment variables or a secrets manager rather than in plaintext:

export SIGNOZ_ACCESS_TOKEN="your-api-key"
export SIGNOZ_ENDPOINT="https://signoz.YOUR_DOMAIN"

Data Retention Policies¶

ClickHouse TTL¶

SigNoz manages data retention through ClickHouse table TTL. The Query Service configures TTL during schema migration:

Traces: Default retention configurable via SigNoz settings (typically 7-30 days).
Logs: Separate TTL per log pipeline.
Metrics: Tiered retention (raw data shorter, aggregated data longer).

Retention is enforced by ClickHouse's background TTL merge process. No manual data deletion is required.

Storage Encryption¶

ClickHouse supports encryption at rest for data files:

# ClickHouse server config
storage_configuration:
  disks:
    encrypted:
      type: encrypted
      disk: default
      key: "encryption-key-hex"
  policies:
    encrypted_policy:
      volumes:
        main:
          disk: encrypted

Alternatively, use filesystem-level encryption (LUKS) on the underlying EBS volumes.

Network Security¶

Component	Default Port	Purpose	Recommended Exposure
Otel Collector	4317 (gRPC), 4318 (HTTP)	OTLP ingestion	Behind load balancer
Query Service	8080	API server	Behind reverse proxy with TLS
Frontend	3301	Web UI	Via Query Service proxy
ClickHouse	9000 (TCP), 8123 (HTTP)	Data store	Internal only

Hardening Checklist¶

Area	Recommendation
Ingestion keys	Unique key per collector; rotate on compromise
ClickHouse user	Dedicated user with minimum database permissions
ClickHouse TLS	Enable native TLS for inter-node and client connections
ClickHouse network	Restrict to internal VPC only
SSO	Enforce SSO for all organizational email domains
API keys	Store in environment variables or Vault; never in code
Retention	Set appropriate TTLs per signal type
Encryption at rest	Use ClickHouse encrypted disks or LUKS on EBS
TLS termination	Deploy reverse proxy (Nginx/Caddy) for HTTPS
Schema migrations	Use elevated user for migrations; restricted user for runtime