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:
- Obtain a Windows Server machine to use during the next steps.
- Register the service principal name.
- Generate a keytab.
- Configure the deployment to verify Kerberos tickets.
- Optionally, customize the authentication.
Obtaining a Windows machine
To perform the next steps, you need a Windows Server virtual machine:
- It should be joined to the same domain as the organization’s users.
- It should have the RSAT (opens in a new tab) feature enabled.
- It should be able to reach the Key Distribution Center (opens in a new tab) (KDC). For example,
on Azure, this virtual machine can be created in the
aadds-vnet
subnet.
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 variable | Value |
---|---|
CUBE_XMLA_KRB5_KEYTAB_B64 | Base64-encoded keytab |
CUBE_XMLA_SPN | HTTP |
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.