Install on Azure

This guide walks through the azure/examples/enterprise example in the Materialize Terraform repository, which extends the base Install on Azure walkthrough with the advanced SSO stack on AKS.

If Materialize is already running, see Add to an existing installation instead.

Self-managed Materialize requires: a Kubernetes (v1.31+) cluster; PostgreSQL as a metadata database; blob storage; and a license key. This example layers the Ory stack (Kratos, Hydra, the selfservice UI, and optional Polis) on top so that the Materialize Console authenticates users through OIDC, with SAML and SCIM available when Polis is enabled. The example wires these modules together as a reference; the individual modules are designed to be composed into your own Terraform rather than used only through the example.

What Gets Created

This example provisions everything from the base Install on Azure guide, plus the additions below.

Networking

Database

Kubernetes Add-ons

Materialize

Azure-Specific Requirements

Cross-cutting requirements (license key with the ory entitlement, DNS hostnames, cert-manager strategy, required tools) are covered on the shared Prerequisites page. This section only lists the Azure-specific bits.

An active Azure subscription with permission to create:

• Resource groups
• Virtual networks, subnets, and NAT gateways
• AKS clusters and node pools
• Azure Database for PostgreSQL Flexible Servers
• Storage accounts
• Managed identities and role assignments

Getting Started: Advanced SSO Example

Step 1: Set Up the Environment

1. Open a terminal window.

2. Clone the Materialize Terraform repository and go to the azure/examples/enterprise directory:

   git clone https://github.com/MaterializeInc/materialize-terraform-self-managed.git
   cd materialize-terraform-self-managed/azure/examples/enterprise
   

3. Sign in to Azure and select the subscription you’ll deploy into:

   az login
   az account set --subscription <your-subscription-id>
   

Step 2: Configure Terraform Variables

1. Create a terraform.tfvars file with the required variables:

   • subscription_id: Azure subscription ID
   • resource_group_name: Name of the resource group to create
   • name_prefix: Prefix for all resource names
   • location: Azure region
   • license_key: Materialize license key JWT with the ory entitlement
   • k8s_apiserver_authorized_networks: CIDRs allowed to reach the AKS API server (required, no default)
   • ory_hydra_fqdn, ory_ui_fqdn, ory_kratos_fqdn, materialize_console_fqdn, materialize_balancerd_fqdn: Hostnames for the browser-facing services
   • internal_load_balancer: Defaults to true, which gives every load balancer a private address. Set it to false to reach the endpoints from outside the VPC. SCIM from a cloud IdP such as Okta requires this, because the IdP must reach Polis
   • ingress_cidr_blocks: CIDRs allowed to reach the load balancers when internal_load_balancer = false (defaults to 0.0.0.0/0, tighten for production)
   • tags: Map of tags to apply to resources

   subscription_id     = "12345678-1234-1234-1234-123456789012"
   resource_group_name = "materialize-enterprise-rg"
   name_prefix         = "mz-enterprise"
   location            = "westus2"
   license_key         = "your-materialize-license-key"
   
   k8s_apiserver_authorized_networks = ["0.0.0.0/0"]   # tighten for production
   
   ory_hydra_fqdn             = "hydra.example.com"
   ory_ui_fqdn                = "auth.example.com"
   ory_kratos_fqdn            = "kratos.example.com"
   materialize_console_fqdn   = "console.example.com"
   materialize_balancerd_fqdn = "balancerd.example.com"
   
   tags = {
     environment = "demo"
   }
   

To enable Polis (SAML and SCIM):

enable_polis   = true
ory_polis_fqdn = "polis.example.com"

To bring your own cert-manager ClusterIssuer for the browser-facing TLS certs (Hydra, Kratos, the selfservice UI, Polis, the Materialize console, and balancerd):

cert_issuer_ref = {
  name = "letsencrypt-prod"
  kind = "ClusterIssuer"
}

If you want a Let’s Encrypt issuer signed via DNS-01, the example’s README ships a starter letsencrypt.tf snippet for Cloudflare, Route 53, Azure DNS, and Google Cloud DNS. Drop it next to main.tf, set your DNS provider API token, and point cert_issuer_ref at it.

To federate logins through one or more upstream OIDC providers (Okta, Google Workspace, Auth0, Entra), add an upstream_identity_providers list. Each entry renders as a “Sign in with …” button on the selfservice UI:

upstream_identity_providers = [
  {
    id            = "okta"
    provider      = "generic"
    client_id     = "<from your IdP>"
    client_secret = "<from your IdP>"
    issuer_url    = "https://your-org.okta.com"
    scope         = ["openid", "email", "profile"]
    label         = "Sign in with Okta"
  },
]

Register the redirect URI https://<ory_kratos_fqdn>/self-service/methods/oidc/callback/<id> at the upstream IdP. See Configure identity providers for SAML and SCIM setup once the stack is up.

Step 3: Apply the Terraform

1. Initialize the Terraform directory:

   terraform init
   

2. Apply the Terraform configuration:

   terraform apply
   

   Expect 30 to 45 minutes for the full apply. The slowest parts are AKS provisioning, the two Flexible Server instances, and the Materialize instance reaching ready.

3. Configure kubectl against the new cluster:

   az aks get-credentials \
     --resource-group $(terraform output -raw resource_group_name) \
     --name $(terraform output -raw aks_cluster_name)
   

Step 4: Create DNS Records

After terraform apply, read the load balancer addresses from the Terraform outputs:

# Ory endpoints (all clouds)
terraform output ory_lb_addresses

# Console and balancerd, Azure and GCP
terraform output console_load_balancer_ip
terraform output balancerd_load_balancer_ip

# Console and balancerd, AWS (one NLB hostname serves both)
terraform output nlb_dns_name

Create DNS records pointing the browser-facing hostnames at those addresses: an A record for an IP (Azure, GCP), a CNAME for a hostname (AWS):

cert-manager issues TLS certs as soon as DNS resolves. Wait for all Certificates to report READY=True:

kubectl get certificate -A -w

The first certificate issuance typically takes 1 to 3 minutes per cert when using ACME (Let’s Encrypt DNS-01); in-cluster self-signed certs issue near-instantly.

Step 5: Verify the Deployment

Smoke-test each browser-facing endpoint. These commands assume a publicly trusted issuer (cert_issuer_ref set). With the default self-signed issuer, fetch its CA first and pass --cacert ca.crt to each curl:

kubectl -n cert-manager get secret <name_prefix>-root-ca -o jsonpath='{.data.ca\.crt}' | base64 -d > ca.crt

# Hydra OIDC discovery (issuer should match ory_hydra_fqdn)
curl -fsSL https://hydra.example.com/.well-known/openid-configuration | jq .issuer

# Kratos health
curl -fsSL https://kratos.example.com/health/ready

# Selfservice UI health
curl -fsSL https://auth.example.com/health/alive

# Polis health (only when enable_polis = true)
curl -fsSL https://polis.example.com/api/health

# Materialize console (expect HTTP 200)
curl -fsSL -o /dev/null -w "%{http_code}\n" https://console.example.com

Then sign in end to end, which is what proves SSO works:

1. Open https://console.example.com. You are redirected to the selfservice UI at auth.example.com, with one button per upstream_identity_providers entry and per saml_providers entry. Each button’s text comes from that entry’s label; see Configure identity providers.
2. Sign in through one of them. You should land back in the Console as that user.
3. Run SELECT current_user;. It should return the user’s email.

If you haven’t configured an identity provider yet, see Configure identity providers.

Customizing Your Deployment

You can override module inputs independently. For details on the per-cloud modules, see the top-level README and the Azure-specific README.

Notes specific to Azure:

• PostgreSQL version: The example targets PostgreSQL 18 on Azure Database for PostgreSQL Flexible Server. The azurerm provider declaration in versions.tf is pinned at >= 4.55.0 to support PG 18.
• AKS API server access: k8s_apiserver_authorized_networks has no default. Production deployments should pin a tight allowlist instead of 0.0.0.0/0.
• VM sizes: Default node pool uses Standard_D4ps_v6 (arm64). The Materialize node pool uses Standard_E* instances. Adjust via materialize_nodepool and the default pool size variables.

Cleanup

terraform destroy

kubectl patch oauth2client materialize-oauth2-client -n ory \
  --type=json -p='[{"op":"remove","path":"/metadata/finalizers"}]'

See Also

• Configure identity providers
• Operations
• Troubleshooting
• Install on Azure (base Materialize stack)