docs-mintlify/docs/integrations/power-bi/kerberos.mdx
Kerberos is the most common authentication method for Windows environments. It can be used to authenticate requests to the DAX API and MDX API.
<Note>Available on Enterprise plan.
</Note>On the diagram below, Kerberos is used to authenticate requests from Power BI Desktop (step 2):
Kerberos is the recommended method to authenticate Power BI Desktop requests.
It works as follows:
The Settings → Power BI page of your Cube deployment is the main entrypoint for
configuring XMLA authentication. It shows the XMLA endpoint and your deployment's domain,
generates setspn and ktpass command templates, stores the XMLA service account
credentials, and accepts the keytab upload. The generated commands use the XMLA service
account name — replace it with the keytab account
before running them.
Configuring Kerberos authentication includes the following steps:
To perform the next steps, you need a Windows Server virtual machine:
aadds-vnet subnet.You should log in to this Windows Server machine using the account that has AAD DC Administrators group membership.
It is also recommended to create a custom organizational unit (OU) for the service accounts.
On the screenshot below, the mdax-api-svc-account user is created in the
MyCustomOU OU in the CUBE domain:
Create two separate accounts in your directory:
mdax-api-svc-account) that the SPNs are registered on
and the keytab is generated for. Running ktpass rewrites this account's user principal
name to the SPN format — this is expected, but it means the account can no longer sign
in as a regular user, so don't use it for anything else.cube-pbi-svc-account) that clients — for example,
the Power BI on-premises data gateway — use to connect to Cube.A service principal name (SPN) is a unique identifier of a service instance. Kerberos authentication uses SPNs to associate a service instance with a service sign-in account.
First, obtain your deployment’s domain from the Settings → Power BI page.
Then, use the setspn command to register the Service Principal Name
for the DAX API against the keytab account.
In the following example, the web service (HTTP) SPN on the
redundant-brohman.gcp-us-central1.cubecloudapp.dev domain is registered for the
mdax-api-svc-account user in the CUBE domain:
setspn -S HTTP/redundant-brohman.gcp-us-central1.cubecloudapp.dev CUBE\mdax-api-svc-account
If clients connect to the deployment through a different hostname (e.g., a custom domain), register the SPN for the hostname that clients actually connect to.
On AWS, the deployment’s domain is a CNAME record pointing to the DNS name of an AWS load balancer. When connecting directly (without an HTTP proxy), Windows resolves the CNAME and requests a Kerberos ticket for the load balancer hostname, so a second SPN must be registered on the same account. Without it, clients silently fall back to NTLM. GCP deployments resolve to an A record and don’t need this.
Find the load balancer hostname and register the second SPN:
nslookup redundant-brohman.aws-us-east-1.cubecloudapp.dev
# Name: a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6-1234567890abcdef.elb.us-east-1.amazonaws.com
setspn -S HTTP/a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6-1234567890abcdef.elb.us-east-1.amazonaws.com CUBE\mdax-api-svc-account
The keytab doesn’t need to be regenerated — both SPNs share the keytab account’s key. If the deployment’s load balancer is ever re-provisioned, its hostname changes and the second SPN must be registered again.
The keytab file contains information needed to decrypt the Kerberos token.
First, use the ktpass command to generate the keytab file. You will be
prompted to enter the password for the specified user:
ktpass /out kerberos.keytab /princ HTTP/[email protected] /mapuser mdax-api-svc-account /crypto All /ptype KRB5_NT_PRINCIPAL /pass *
Then, upload the .keytab file on the Settings → Power BI page. It is stored
Base64-encoded in the CUBE_XMLA_KRB5_KEYTAB_B64 environment variable. The
CUBE_XMLA_SPN and KRB5_KTNAME environment variables are managed by Cube
automatically and don’t need to be set.
On the Settings → Power BI page, set the XMLA service account name and password.
They are stored in the CUBE_XMLA_API_USER and CUBE_XMLA_API_PASSWORD environment
variables and default to the deployment’s SQL API credentials.
A connection authenticated as this account is allowed to impersonate other users: when
Power BI Service passes an end user’s UPN via EffectiveUserName, Cube switches the
session to that user. For this to work, the value must exactly match the user name the
connection authenticates as — with Kerberos, that is the full principal in user@REALM
format, e.g., [email protected]. The match is case-sensitive, so keep the
same letter case as the principal — the realm is typically uppercase. A NetBIOS format
like CUBE\cube-pbi-svc-account will not match.
Once the deployment is ready, you can test the Kerberos authentication by connecting from Power BI to the DAX API.
The user principal name passed by Kerberos is often not the email a user is provisioned
into Cube Cloud with. For example, Power BI sends a UPN like [email protected], while
the user exists in Cube as [email protected]. For authentication to succeed, the principal
name must resolve to a Cube user.
To bridge this, Cube Cloud's SCIM API exposes an extension that lets your identity provider sync an alternate username alongside each user. During username-based authentication Cube checks the user's email, username, and any aliases — so the Kerberos UPN resolves to the same user.
Map an IdP attribute to the following single-valued, string target attribute:
urn:cube:params:1.0:UserAliases:alternateUserName
The value is lowercased and trimmed on write, and lookups are lowercased too, so matching is
fully case-insensitive — the value just needs to be the same principal string Kerberos sends
(same realm and separator). It must be unique across the tenant: if it collides with another
user's email, username, or an existing alias, the sync is rejected with 409 Conflict.
These steps assume you already have a SCIM provisioning app connected to Cube Cloud. If not, enable SCIM first under Cube → Settings → Authentication & SSO.
urn:cube:params:1.0:UserAliases:alternateUserName, type String, not
multi-valued, not required. Save.onPremisesUserPrincipalName. To build the principal from
parts, use an Expression mapping, e.g. Join("@", [samAccountName], "INTERNAL.REALM").urn:cube:params:1.0:UserAliases:alternateUserNameGET /api/scim/v2/Users/:id to confirm the alias appears under the extension.Entra only syncs a user when their source data changes, so existing users won't receive the
alias until their next change — use Restart provisioning to force a full re-sync.
onPremisesUserPrincipalName is only populated for users synced from on-prem AD; cloud-only
users need a different source attribute or an expression with a fallback.
The Cube-side target attribute is always urn:cube:params:1.0:UserAliases:alternateUserName;
only the IdP-side mapping UI differs. In Okta, add a custom attribute on the SCIM app via the
Profile Editor, then bind your source attribute to it on the Mappings tab. The value Cube
receives is just a string — what you map to it is your decision.
Unable to fetch Cloud context for XMLA user in logs, Access Denied in the client.
The Kerberos principal doesn’t resolve to a Cube user. Check that the user has a matching
alternate username; if the user was provisioned before
the SCIM mapping was added, force a re-sync.... is not allowed to switch to '<user>'. The connection didn’t authenticate as
the XMLA service account — often because the account
is set in NetBIOS format instead of user@REALM, or with a different letter case.ktpass rewrites the keytab
account’s UPN, so it can no longer sign in. Connect with a
separate XMLA service account.Cube always offers Negotiate, NTLM, and Basic authentication on the XMLA endpoints;
the NTLM fallback can’t be disabled. Check the deployment logs to see which method a
connection actually used: method=kerberos vs. method=ntlm.