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.
Before you start
Section titled “Before you start”-
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:readandclusters:private-link:writescopes. See Authentication & Scopes. -
Permission to create a private endpoint and a private DNS zone in your Azure subscription.
Set it up
Section titled “Set it up”-
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, thedns_nameand thestatus. -
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 enabledWhether private link is on. azure_subscription_idsSubscriptions allowed to connect. aliasThe Private Link Service alias to use when creating the private endpoint. Present while private link is enabled. dns_nameThe private hostname to create in your private DNS zone. Present while private link is enabled. statusdisabled,waitingorconnected.connectionsThe state of each subscription’s private endpoint: waiting,connectedorrejected. -
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 -
Point your private DNS at the endpoint.
Create a private DNS zone linked to your virtual network and add a record for the
dns_namefrom step 2 that resolves to the private IP address of the endpoint. Workloads in the network then reach Keycloak by its private hostname. -
Wait for the connection.
Read the private link again.
statusmoves fromwaitingtoconnectedonce a private endpoint from a listed subscription connects. A subscription that is not on your list is not connected. -
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 }'
Refusals
Section titled “Refusals”| 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.
With Terraform
Section titled “With Terraform”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:
siteis optional and computed. Leave it out for the location’s default site. Changing it replaces the cluster.skycloak_cluster_private_linkholdsenabled,azure_subscription_idsand the computedalias. Use thealiasin the Azure private endpoint, as in step 3. Destroying the resource disables private link and keeps the subscription IDs.skycloak_cluster_public_accesssetspublic_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
aliasoutput, then runterraform applyagain so that public access can be turned off once the connection is ready.
Turn it off
Section titled “Turn it off”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.