SAML Settings Example¶

This example demonstrates how to configure SAML-based single sign-on (SSO) authentication on a Qumulo cluster.

Overview¶

The qumulo_saml_settings resource manages SAML authentication settings for integrating with external Identity Providers (IdP). This is a singleton resource (one per cluster).

Features¶

SAML 2.0 SSO: Integrate with any SAML 2.0 compliant Identity Provider
Flexible Authentication: Allow both SSO and password authentication, or enforce SSO-only
Multi-Cluster Support: Use for_each to configure SAML across multiple clusters

Important Warnings¶

`require_sso` Lockout Risk¶

When require_sso = true:

AD users cannot authenticate with passwords via Web UI, qq CLI, or REST API
Local users (like "admin") can still use password authentication
If Terraform uses AD credentials, it will be locked out after applying this setting

Only enable require_sso = true when: 1. Terraform authenticates with a local user account (not AD) 2. SSO has been fully tested and verified working 3. You have a local admin account as a backup

Destroy Behavior¶

When this resource is destroyed (terraform destroy), SAML is disabled on the cluster (enabled = false). If the cluster had SAML configured before Terraform management, destroying this resource will break existing SSO access.

Usage¶

Basic SAML Configuration (Recommended for Initial Setup)¶

resource "qumulo_saml_settings" "main" {
  connection_profile = "cluster1"

  enabled          = true
  idp_sso_url      = "https://idp.example.com/sso"
  idp_certificate  = file("${path.module}/idp-cert.pem")
  idp_entity_id    = "https://idp.example.com/entity"
  cluster_dns_name = "cluster.example.com"
  require_sso      = false  # Allow both SSO and password auth
}

Strict SSO Configuration (Advanced)¶

# WARNING: This will block password auth for AD users!
# Make sure Terraform uses a LOCAL user account.
resource "qumulo_saml_settings" "strict" {
  connection_profile = "cluster1"  # Profile must use a local user, NOT an AD user

  enabled          = true
  idp_sso_url      = "https://idp.example.com/sso"
  idp_certificate  = file("${path.module}/idp-cert.pem")
  idp_entity_id    = "https://idp.example.com/entity"
  cluster_dns_name = "cluster.example.com"
  require_sso      = true  # Blocks password auth for AD users
}

Multi-Cluster Configuration¶

variable "clusters" {
  type = map(object({
    endpoint         = string
    username         = string
    password         = string
    cluster_dns_name = string
  }))
}

provider "qumulo" {
  connection_profiles = [
    for name, config in var.clusters : {
      name     = name
      endpoint = config.endpoint
      username = config.username
      password = config.password
    }
  ]
}

resource "qumulo_saml_settings" "all" {
  for_each = var.clusters

  connection_profile = each.key

  enabled          = true
  idp_sso_url      = "https://idp.example.com/sso"
  idp_certificate  = file("${path.module}/idp-cert.pem")
  idp_entity_id    = "https://idp.example.com/entity"
  cluster_dns_name = each.value.cluster_dns_name
  require_sso      = false
}

Variables¶

Name	Description	Type	Default
`cluster_endpoint`	Qumulo cluster REST API endpoint	`string`	-
`cluster_username`	Qumulo cluster admin username	`string`	`"admin"`
`cluster_password`	Qumulo cluster admin password	`string`	-
`idp_sso_url`	Identity Provider SSO URL	`string`	-
`idp_certificate_file`	Path to IdP certificate file (PEM format)	`string`	-
`idp_entity_id`	IdP entity ID (URI)	`string`	-
`cluster_dns_name`	Cluster DNS name for SP metadata	`string`	-
`require_sso`	Require SSO for AD users	`bool`	`false`

Usage¶

Obtain your IdP certificate in PEM format and save it (e.g., idp-cert.pem)
Create a terraform.tfvars file:

cluster_endpoint     = "https://your-cluster:8000"
cluster_password     = "your-cluster-password"
idp_sso_url          = "https://your-idp.example.com/sso"
idp_certificate_file = "./idp-cert.pem"
idp_entity_id        = "https://your-idp.example.com/entity"
cluster_dns_name     = "your-cluster.example.com"
require_sso          = false

Initialize and apply:

terraform init -upgrade
terraform plan
terraform apply

Import¶

To import existing SAML settings:

terraform import qumulo_saml_settings.main "prod"

Identity Provider Setup¶

To configure your IdP, you'll need the Service Provider (SP) metadata from Qumulo:

SP Entity ID: https://<cluster_dns_name>:8000/saml/metadata
Assertion Consumer Service URL: https://<cluster_dns_name>:8000/saml/consume

Consult your IdP's documentation for specific setup instructions:

Notes¶

The idp_certificate is a public X.509 certificate used to validate SAML responses. It is marked as sensitive in Terraform to avoid cluttering plan output (it's a long multi-line string), not for security reasons.
SAML authentication is separate from Active Directory integration. You can have both AD and SAML configured.
When SAML is disabled, users who were only authenticated via SSO will need to use password authentication.

Full Configuration¶

# Example: Managing SAML Authentication Settings on a Qumulo Cluster
#
# This example demonstrates how to configure SAML-based single sign-on (SSO)
# authentication on a Qumulo cluster using the qumulo_saml_settings resource.
#
# The resource supports:
# - Integration with external Identity Providers (IdP)
# - SSO login via SAML 2.0
# - Optional enforcement of SSO for Active Directory users
#
# IMPORTANT: This is a singleton resource - there is only one SAML
# configuration per cluster.
#
# WARNING: Setting require_sso = true will block password-based authentication
# for Active Directory users. If Terraform uses AD credentials to manage this
# cluster, subsequent Terraform operations will fail.

terraform {
  required_providers {
    qumulo = {
      source  = "qumulo-terraform-registry.s3.us-east-1.amazonaws.com/qumulo/qumulo"
      version = "~> 1.0"
    }
  }
}

variable "cluster_endpoint" {
  description = "Qumulo cluster REST API endpoint (e.g., https://cluster:8000)"
  type        = string
}

variable "cluster_username" {
  description = "Qumulo cluster admin username"
  type        = string
  default     = "admin"
}

variable "cluster_password" {
  description = "Qumulo cluster admin password"
  type        = string
  sensitive   = true
}

# Variables for SAML configuration
variable "idp_sso_url" {
  description = "Identity Provider SSO URL where authentication requests are sent"
  type        = string
}

variable "idp_certificate_file" {
  description = "Path to the IdP X.509 certificate file (PEM format)"
  type        = string
}

variable "idp_entity_id" {
  description = "IdP entity ID (URI) that identifies the identity provider"
  type        = string
}

variable "cluster_dns_name" {
  description = "Cluster DNS name used for Service Provider entity ID (e.g., cluster.example.com)"
  type        = string
}

variable "require_sso" {
  description = "Require SSO for AD users (blocks password auth). WARNING: May lock out Terraform if using AD credentials!"
  type        = bool
  default     = false
}

# Define connection profile for the cluster
provider "qumulo" {
  connection_profiles = [
    {
      name                 = "cluster1"
      endpoint             = var.cluster_endpoint
      username             = var.cluster_username
      password             = var.cluster_password
      insecure_skip_verify = true # Required for clusters with self-signed certificates
    }
  ]
}

# ------------------------------------------------------------------------------
# Example 1: Basic SAML Configuration
# ------------------------------------------------------------------------------
# This enables SAML authentication while still allowing password-based login
# for AD users. This is the safest configuration for initial setup.

resource "qumulo_saml_settings" "basic" {
  count = var.require_sso ? 0 : 1

  connection_profile = "cluster1"

  # Enable SAML authentication
  enabled = true

  # Identity Provider configuration
  idp_sso_url     = var.idp_sso_url
  idp_certificate = file(var.idp_certificate_file)
  idp_entity_id   = var.idp_entity_id

  # Cluster DNS name for Service Provider metadata
  cluster_dns_name = var.cluster_dns_name

  # Allow both SSO and password authentication
  require_sso = false
}

# ------------------------------------------------------------------------------
# Example 2: Strict SSO Configuration
# ------------------------------------------------------------------------------
# This configuration enforces SSO for all Active Directory users.
#
# WARNING: When require_sso = true:
# - AD users cannot authenticate with passwords via Web UI, qq CLI, or REST API
# - Local users (like "admin") can still use password authentication
# - If Terraform uses AD credentials, it will be locked out after applying this
#
# ONLY use this configuration when:
# - Terraform authenticates with a LOCAL user account (not AD)
# - SSO has been fully tested and verified working
# - You have a local admin account as a backup

resource "qumulo_saml_settings" "strict" {
  count = var.require_sso ? 1 : 0

  connection_profile = "cluster1"

  # Enable SAML authentication
  enabled = true

  # Identity Provider configuration
  idp_sso_url     = var.idp_sso_url
  idp_certificate = file(var.idp_certificate_file)
  idp_entity_id   = var.idp_entity_id

  # Cluster DNS name for Service Provider metadata
  cluster_dns_name = var.cluster_dns_name

  # Require SSO - blocks password authentication for AD users
  require_sso = true
}

# Outputs
output "saml_enabled" {
  description = "Whether SAML authentication is enabled"
  value       = var.require_sso ? qumulo_saml_settings.strict[0].enabled : qumulo_saml_settings.basic[0].enabled
}

output "saml_require_sso" {
  description = "Whether SSO is required for AD users"
  value       = var.require_sso ? qumulo_saml_settings.strict[0].require_sso : qumulo_saml_settings.basic[0].require_sso
}

output "saml_idp_entity_id" {
  description = "Configured IdP entity ID"
  value       = var.require_sso ? qumulo_saml_settings.strict[0].idp_entity_id : qumulo_saml_settings.basic[0].idp_entity_id
}

output "saml_cluster_dns_name" {
  description = "Configured cluster DNS name for SP metadata"
  value       = var.require_sso ? qumulo_saml_settings.strict[0].cluster_dns_name : qumulo_saml_settings.basic[0].cluster_dns_name
}

SAML Settings Example¶

Overview¶

Features¶

Important Warnings¶

require_sso Lockout Risk¶

Destroy Behavior¶

Usage¶

Basic SAML Configuration (Recommended for Initial Setup)¶

Strict SSO Configuration (Advanced)¶

Multi-Cluster Configuration¶

Variables¶

Usage¶

Import¶

Identity Provider Setup¶

Notes¶

Full Configuration¶

`require_sso` Lockout Risk¶