Skip to content

Azure Private Link for Managed Keycloak

Azure Private Link exposes your Managed Keycloak cluster as a private endpoint inside your own Azure virtual network. Traffic between your workloads and Keycloak stays on the Microsoft network, and once public access is turned off the cluster has no public hostname at all.

  • An Enterprise plan.

  • A dedicated cluster on a site that supports Azure Private Link, and open to your workspace. List the sites you can use for a location:

    curl https://api.skycloak.io/cluster-locations/eu/sites \
      -H "API-Key: $SKYCLOAK_API_KEY" \
      -H "API-Version: 2026-06-01.beta"

    A private link call on a cluster whose site has no Azure Private Link answers 422.

  • The ID of each Azure subscription that will hold a private endpoint. Private endpoints from other subscriptions are not accepted.

  • An API key with the clusters:read, clusters:write, clusters:private-link:read and clusters:private-link:write scopes. See Authentication & Scopes.

  • Permission to create a private endpoint and a private DNS zone in your Azure subscription.

  1. Turn on private link and list your subscriptions.

    Send the Azure subscription IDs (GUIDs, at most 20) allowed to connect. At least one is required to enable private link. The list you send replaces the stored list.

    curl -X PUT https://api.skycloak.io/clusters/$CLUSTER_ID/private-link \
      -H "API-Key: $SKYCLOAK_API_KEY" \
      -H "API-Version: 2026-06-01.beta" \
      -H "Content-Type: application/json" \
      -d '{
        "enabled": true,
        "azure_subscription_ids": ["11111111-1111-1111-1111-111111111111"]
      }'

    The response carries the alias, the dns_name and the status.

  2. Read the alias.

    curl https://api.skycloak.io/clusters/$CLUSTER_ID/private-link \
      -H "API-Key: $SKYCLOAK_API_KEY" \
      -H "API-Version: 2026-06-01.beta"
    Field Meaning
    enabled Whether private link is on.
    azure_subscription_ids Subscriptions allowed to connect.
    alias The Private Link Service alias to use when creating the private endpoint. Present while private link is enabled.
    dns_name The private hostname to create in your private DNS zone. Present while private link is enabled.
    status disabled, waiting or connected.
    connections The state of each subscription’s private endpoint: waiting, connected or rejected.
  3. Create the private endpoint in Azure.

    In the Azure portal, open Private endpoints and choose Create. Use the subscription you listed in step 1. On the Resource tab, choose Connect to an Azure resource by resource ID or alias and paste the alias. Pick your virtual network and subnet, then create the endpoint.

    With the Azure CLI:

    az network private-endpoint create \
      --name skycloak-keycloak \
      --resource-group my-resource-group \
      --vnet-name my-vnet \
      --subnet my-subnet \
      --private-connection-resource-id "$ALIAS" \
      --connection-name skycloak-keycloak \
      --manual-request true
  4. Point your private DNS at the endpoint.

    Create a private DNS zone linked to your virtual network and add a record for the dns_name from step 2 that resolves to the private IP address of the endpoint. Workloads in the network then reach Keycloak by its private hostname.

  5. Wait for the connection.

    Read the private link again. status moves from waiting to connected once a private endpoint from a listed subscription connects. A subscription that is not on your list is not connected.

  6. Optional: turn public access off.

    Once private link is enabled and ready, serve the cluster only on its private hostname:

    curl -X PATCH https://api.skycloak.io/clusters/$CLUSTER_ID \
      -H "API-Key: $SKYCLOAK_API_KEY" \
      -H "API-Version: 2026-06-01.beta" \
      -H "Content-Type: application/json" \
      -d '{ "public_access": false }'
Call Answer Why
Private link or public_access change 403 The plan lacks private networking. It needs Enterprise.
Private link or public_access change 422 The cluster’s site has no Azure Private Link, or a subscription ID is not valid.
public_access: false 409 Private link is not enabled and ready. Enable it first.
Disable private link 409 Public access is off. Turn it back on first.

These refusals protect you from cutting a cluster off from its users. Setting public_access back to true is always allowed.

The Skycloak Terraform provider manages all of this. Use a provider release that includes skycloak_cluster_private_link and skycloak_cluster_public_access. The configuration below creates a private cluster end to end: a cluster on a site, private link, public access off, a realm served behind your own proxy and a custom theme.

terraform {
  required_providers {
    skycloak = {
      source = "sky-cloak/skycloak"
    }
  }
}

provider "skycloak" {
  # api_key is read from the SKYCLOAK_API_KEY environment variable.
}

# The site must support Azure private link and be open to your workspace.
resource "skycloak_cluster" "private" {
  name     = "private"
  type     = "keycloak"
  size     = "small"
  version  = "26.1"
  location = "eu"
  site     = "azure-north-europe"
}

resource "skycloak_cluster_private_link" "private" {
  cluster_id             = skycloak_cluster.private.id
  enabled                = true
  azure_subscription_ids = ["11111111-1111-1111-1111-111111111111"]
}

# Public access can only be turned off once the private link is enabled and
# ready, so it depends on the private link. On destroy, public access is turned
# back on before the private link is disabled.
resource "skycloak_cluster_public_access" "private" {
  cluster_id    = skycloak_cluster.private.id
  public_access = false

  depends_on = [skycloak_cluster_private_link.private]
}

resource "skycloak_realm" "app" {
  cluster_id   = skycloak_cluster.private.id
  name         = "app"
  display_name = "Application Realm"
  enabled      = true

  # The public URL the realm serves on, behind your own proxy.
  frontend_url = "https://login.example.com"
}

# Supply the theme JAR: build your own Keycloakify theme and place it
# at themes/corporate.jar next to this file, or change the source path.
resource "skycloak_custom_theme" "corporate" {
  cluster_id = skycloak_cluster.private.id
  name       = "corporate"
  version    = "1.0.0"
  source     = "${path.module}/themes/corporate.jar" # Keycloakify .jar
}

resource "skycloak_theme_assignment" "app" {
  cluster_id = skycloak_cluster.private.id
  realm_name = skycloak_realm.app.name
  login      = skycloak_custom_theme.corporate.id
}

output "private_link_alias" {
  value = skycloak_cluster_private_link.private.alias
}

Notes on the resources:

  • site is optional and computed. Leave it out for the location’s default site. Changing it replaces the cluster.
  • skycloak_cluster_private_link holds enabled, azure_subscription_ids and the computed alias. Use the alias in the Azure private endpoint, as in step 3. Destroying the resource disables private link and keeps the subscription IDs.
  • skycloak_cluster_public_access sets public_access. Destroying it turns public access back on, so the private link can be disabled afterwards.
  • Both resources can be imported with the cluster ID, for example terraform import skycloak_cluster_private_link.private <cluster_id>.
  • Terraform creates the cluster and the private link first. Create the Azure private endpoint with the alias output, then run terraform apply again so that public access can be turned off once the connection is ready.

To go back to public access, set public_access to true first, then disable private link:

curl -X PATCH https://api.skycloak.io/clusters/$CLUSTER_ID \
  -H "API-Key: $SKYCLOAK_API_KEY" \
  -H "API-Version: 2026-06-01.beta" \
  -H "Content-Type: application/json" \
  -d '{ "public_access": true }'

curl -X PUT https://api.skycloak.io/clusters/$CLUSTER_ID/private-link \
  -H "API-Key: $SKYCLOAK_API_KEY" \
  -H "API-Version: 2026-06-01.beta" \
  -H "Content-Type: application/json" \
  -d '{ "enabled": false }'

Omitting azure_subscription_ids keeps the stored list.