Documentation
Kerberos

Kerberos authentication

Kerberos (opens in a new tab) is the most common authentication method for Windows environments. It can be used to authenticate requests to DAX API and MDX API.

DAX API and MDX API are available in Cube Cloud on Enterprise and above (opens in a new tab) product tiers. They also require the M deployment tier.

On the diagram below, Kerberos is used to authenticate requests from Power BI Desktop (step 2):

Authentication flow

Kerberos is the recommended method to authenticate Power BI Desktop requests.

It works as follows:

  • Power BI Desktop is launched normally, under the Windows domain account of the user.
  • When connecting the DAX API, Windows verifies whether its service principal name is registered in the domain.
  • Once verified, the Key Distribution Center issues a Kerberos ticket for the user.
  • This ticket is transmitted to the DAX API in the request authorization header.
  • The DAX API decrypts and verifies the Kerberos ticket.
  • Finally, the user principal name is passed for further verification.

Configuration

Configuring Kerberos authentication includes the following steps:

Obtaining a Windows machine

To perform the next steps, you need a Windows Server virtual machine:

You should log in to this Windows Server machine using the account that has AAD DC Administrators (opens in a new tab) group membership.

It is also recommended to create a custom organizational unit (OU) and a new user in this OU that will act as the service account.

On the screenshot below, the mdax-api-svc-account user is created in the MyCustomOU OU in the CUBE domain:

Registering the SPN

A service principal name (opens in a new tab) (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 Cube Cloud deployment’s domain by going to Settings → General and copying the value in the Custom domain section.

Then, use the setspn command (opens in a new tab) to register the Service Principal Name for the DAX API.

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

Generating the keytab

The keytab (opens in a new tab) file contains information needed to decrypt the Kerberos token.

First, use the ktpass command (opens in a new tab) to generate the keytab file. You will be prompted to enter the password for the specified user:

ktpass /out kerberos.keytab /princ HTTP/redundant-brohman.gcp-us-central1.cubecloudapp.dev@CUBE.DEV /mapuser mdax-api-svc-account /crypto All /ptype KRB5_NT_PRINCIPAL /pass *

Then, convert the keytab to a Base64-encoded string. For example, the following PowerShell script will do the conversion and put the result in the clipboard:

$Path = "C:\kerberos.keytab"
[Convert]::ToBase64String([System.IO.File]::ReadAllBytes($Path)) | Set-Clipboard

Configuring the deployment

Go to Settings → Environment Variables of your Cube Cloud deployment and set the following environment variables to facilitate the verification of Kerberos tickets:

Environment variableValue
CUBE_XMLA_KRB5_KEYTAB_B64Base64-encoded keytab
CUBE_XMLA_SPNHTTP
KRB5_KTNAME/cube/conf/kerberos.keytab

Verifying the credentials

By default, CUBEJS_SQL_USER and CUBEJS_SQL_PASSWORD environment variables are used to verify the passed credentials. You can also customize the authentication by using the check_sql_auth configuration option.

Once the deployment is ready, you can test the Kerberos authentication by connecting from Power BI to the DAX API.