Embed Power BI content with service principal and a certificate

Certificate-based authentication enables you to be authenticated by Azure Active Directory (Azure AD) with a client certificate on a Windows, Android or iOS device, or kept in an Azure Key Vault.

Using this method of authentication allows managing certificates from a central place, using the CA, for rotation or revocation.

You can learn more about certificates in Azure AD in the Client credential flows GitHub page.

Method

  1. Embed your content with service principal.

  2. Create a certificate.

  3. Set up certificate authentication.

  4. Get the certificate from Azure Key Vault.

  5. Authenticate using service principal and a certificate.

Step 1 - Embed your content with service principal

To embed your content with service principal, follow the instructions in Embed Power BI content with service principal and an application secret.

Note

If you already have content that's embedded using a service principal, skip this step and advance to step 2.

Step 2 - Create a certificate

You can procure a certificate from a trusted Certificate Authority, or generate a certificate yourself.

This section describes creating a certificate using Azure Key Vault, and downloading the .cer file which contains the public key.

  1. Log into Microsoft Azure.

  2. Search for Key Vaults and click the Key Vaults link.

    A screenshot that shows a link to the key vault in the Azure portal.

  3. Click the key vault you want to add a certificate to.

    A screenshot showing a list of blurred out key vaults in the Azure portal.

  4. Click Certificates.

    A screenshot that shows the Key vaults page with Certificates called out.

  5. Click Generate/Import.

    A screenshot that shows the Certificate pane with Generate / Import called out.

  6. Configure the Create a certificate fields as follows:

    • Method of Certificate Creation - General

    • Certificate Name - Enter a name for your certificate

    • Type of Certificate Authority (CA) - Self-signed certificate

    • Subject - An X.500 distinguished name

    • DNS Names - 0 DNS names

    • Validity Period (in months) - Enter the certificate's validity duration

    • Content Type - PKCS #12

    • Lifetime Action Type - Automatically renew at a given percentage lifetime

    • Percentage Lifetime - 80

    • Advanced Policy Configuration - Not configured

  7. Click Create. The newly created certificate is disabled by default. It can take up to five minutes to become enabled.

  8. Select the certificate you created.

  9. Click Download in CER format. The downloaded file contains the public key.

    A screenshot that shows the download in cer format button.

Step 3 - Set up certificate authentication

  1. In your Azure AD application, click the Certificates & secrets tab.

    A screenshot that shows the certificates and secrets pane for an app in the Azure portal.

  2. Click Upload certificate and upload the .cer file you created and downloaded in step 2 of this tutorial. The .cer file contains the public key.

Step 4 - Get the certificate from Azure Key Vault

Use Managed Service Identity (MSI) to get the certificate from Azure Key Vault. This process involves getting the .pfx certificate that contains both the public and private keys.

Refer to the code example for reading the certificate from Azure Key Vault. If you want to use Visual Studio, refer to Configure Visual Studio to use MSI.

private X509Certificate2 ReadCertificateFromVault(string certName)
{
    var serviceTokenProvider = new AzureServiceTokenProvider();
    var keyVaultClient = new KeyVaultClient(new KeyVaultClient.AuthenticationCallback(serviceTokenProvider.KeyVaultTokenCallback));
    CertificateBundle certificate = null;
    SecretBundle secret = null;
    try
    {
        certificate = keyVaultClient.GetCertificateAsync($"https://{KeyVaultName}.vault.azure.net/", certName).Result;
        secret = keyVaultClient.GetSecretAsync(certificate.SecretIdentifier.Identifier).Result;
    }
    catch (Exception)
    {
        return null;
    }

    return new X509Certificate2(Convert.FromBase64String(secret.Value));
}

Step 5 - Authenticate using service principal and a certificate

You can authenticate your app using service principal and a certificate that's stored in Azure Key Vault, by connecting to Azure Key Vault.

To connect and read the certificate from Azure Key Vault, refer to the code below.

Note

If you already have a certificate created by your organization, upload the .pfx file to Azure Key Vault.

// Preparing needed variables
var Scope = "https://analysis.windows.net/powerbi/api/.default"
var ApplicationId = "{YourApplicationId}"
var tenantSpecificURL = "https://login.microsoftonline.com/{YourTenantId}/"
X509Certificate2 certificate = ReadCertificateFromVault(CertificateName);

// Authenticating with a SP and a certificate
public async Task<AuthenticationResult> DoAuthentication(){
    IConfidentialClientApplication clientApp = null;
    clientApp = ConfidentialClientApplicationBuilder.Create(ApplicationId)
                                                    .WithCertificate(certificate)
                                                    .WithAuthority(tenantSpecificURL)
                                                    .Build();
    try
    {
        authenticationResult = await clientApp.AcquireTokenForClient(Scope).ExecuteAsync();
    }
    catch (MsalException)
    {
        throw;
    }
    return authenticationResult
}

Configure Visual Studio to use MSI

When creating your embedded solution, it may be useful to configure Visual Studio to use Managed Service Identity (MSI). MSI is a feature that enables you to manage your Azure AD identity. Once configured, it will let Visual Studio authenticate against your Azure Key Vault.

  1. Open your project in Visual Studio.

  2. Click Tools > Options.

    A screenshot showing the options button in the tools menu in Visual Studio.

  3. Search for Account Selection and click Account Selection.

    A screenshot showing the account selection option in the Visual Studio options window.

  4. Add the account that has access to your Azure Key Vault.

Next steps