Hizmet sorumlusu ve sertifikayla Power BI içeriği eklemeEmbed Power BI content with service principal and a certificate

Service principal is an authentication method that can be used to let an Azure AD application access Power BI service content and APIs.

When you create an Azure Active Directory (Azure AD) app, a service principal object is created. The service principal object, also known simply as service principal, allows Azure AD to authenticate your app. Once authenticated, the app can access Azure AD tenant resources.

To authenticate, the service principal uses the Azure AD app's Application ID, and one of the following:

  • Application secret
  • Certificate

Not

Arka uç hizmetlerinizin güvenliğini, gizli diziler yerine sertifikaları kullanarak sağlamanızı öneririz.We recommend that you secure your backend services using certificates, rather than secret keys. Gizli dizileri veya sertifikaları kullanarak Azure AD’den erişim belirteçlerini alma hakkında daha fazla bilgi edinin.Learn more about getting access tokens from Azure AD using secret keys or certificates.

Sertifika tabanlı kimlik doğrulamasıCertificate-based authentication

Sertifika tabanlı kimlik doğrulaması, Azure Active Directory (Azure AD) kullanılarak Windows, Android veya iOS cihazda bulunan ya da bir Azure Key Vault’ta tutulan bir istemci sertifikasıyla kimliğinizin doğrulanmasına olanak tanır.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.

Bu kimlik doğrulaması yönteminin kullanılması, döndürme veya iptal için CA kullanılarak merkezi bir yerden sertifikaların yönetilmesine olanak verir.Using this method of authentication allows managing certificates from a central place, using the CA, for rotation or revocation.

Azure AD’de İstemci kimlik bilgisi akışları adlı GitHub sayfasında sertifikalar hakkında daha fazla bilgi edinebilirsiniz.You can learn more about certificates in Azure AD in the Client credential flows GitHub page.

YöntemMethod

Ekli analizlerle hizmet sorumlusunu ve sertifika kullanmak için şu adımları izleyin:To use service principal and a certificate with embedded analytics, follow these steps:

  1. Azure AD uygulaması oluşturun.Create an Azure AD Application.

  2. Bir Azure AD güvenlik grubu oluşturun.Create an Azure AD security group.

  3. Power BI hizmeti yönetici ayarlarını etkinleştirin.Enable the Power BI service admin settings.

  4. Hizmet sorumlusunu çalışma alanınıza ekleyin.Add the service principal to your workspace.

  5. Sertifika oluşturun.Create a certificate.

  6. Sertifikası kimlik doğrulaması ayarlayın.Set up certificate authentication.

  7. Azure Key Vault’tan bir sertifikayı alın.Get the certificate from Azure Key Vault.

  8. Hizmet sorumlusu ve sertifika kullanarak kimlik doğrulaması yapın.Authenticate using service principal and a certificate.

1. Adım: Azure AD uygulaması oluşturmaStep 1 - Create an Azure AD Application

  1. Log into Microsoft Azure.

  2. Search for App registrations and click the App registrations link.

    azure app registration

  3. Click New registration.

    new registration

  4. Fill in the required information:

    • Name - Enter a name for your application
    • Supported account types - Select supported account types
    • (Optional) Redirect URI - Enter a URI if needed
  5. Click Register.

  6. After registering, the Application ID is available from the Overview tab. Copy and save the Application ID for later use.

    Screenshot shows where to obtain an Application I D in the Overview tab.

PowerShell kullanarak Azure AD uygulaması oluşturmaCreating an Azure AD app using PowerShell

Bu bölüm, PowerShell kullanarak yeni bir Azure AD uygulaması oluşturmaya yönelik örnek betik içerir.This section includes a sample script to create a new Azure AD app using PowerShell.

# The app ID - $app.appid
# The service principal object ID - $sp.objectId
# The app key - $key.value

# Sign in as a user that's allowed to create an app
Connect-AzureAD

# Create a new Azure AD web application
$app = New-AzureADApplication -DisplayName "testApp1" -Homepage "https://localhost:44322" -ReplyUrls "https://localhost:44322"

# Creates a service principal
$sp = New-AzureADServicePrincipal -AppId $app.AppId

Step 2 - Create an Azure AD security group

Your service principal doesn't have access to any of your Power BI content and APIs. To give the service principal access, create a security group in Azure AD, and add the service principal you created to that security group.

There are two ways to create an Azure AD security group:

  • Manually (in Azure)
  • Using PowerShell

Create a security group manually

To create an Azure security group manually, follow the instructions in the Create a basic group and add members using Azure Active Directory article.

Create a security group using PowerShell

Below is a sample script for creating a new security group, and adding an app to that security group.

Not

If you want to enable service principal access for the entire organization, skip this step.

# Required to sign in as admin
Connect-AzureAD

# Create an Azure AD security group
$group = New-AzureADGroup -DisplayName <Group display name> -SecurityEnabled $true -MailEnabled $false -MailNickName notSet

# Add the service principal to the group
Add-AzureADGroupMember -ObjectId $($group.ObjectId) -RefObjectId $($sp.ObjectId)

Step 3 - Enable the Power BI service admin settings

For an Azure AD app to be able to access the Power BI content and APIs, a Power BI admin needs to enable service principal access in the Power BI admin portal.

Add the security group you created in Azure AD, to the specific security group section in the Developer settings.

Önemli

Service principals have access to any tenant settings they're enabled for. Depending on your admin settings, this includes specific security groups or the entire organization.

To restrict service principal access to specific tenant settings, allow access only to specific security groups. Alternatively, you can create a dedicated security group for service principals, and exclude it from the desired tenant settings.

Screenshot showing the developer settings in the admin options in the Power BI portal.

Step 4 - Add the service principal to your workspace

To enable your Azure AD app access artifacts such as reports, dashboards and datasets in the Power BI service, add the service principal entity as a member or admin to your workspace.

Not

This section provides UI instructions. You can also add a service principal to a workspace using the Groups - add group user API.

  1. Scroll to the workspace you want to enable access for, and from the More menu, select Workspace access.

    Screenshot showing the workspace access button in the more menu of a Power BI workspace.

  2. Add the service principal as an Admin or Member to the workspace.

    Screenshot showing adding a member or an admin to the access pane in the Power BI portal.

5. Adım: Sertifika oluşturmaStep 5 - Create a certificate

Güvenilir bir Sertifika Yetkilisi’nden bir sertifika temin edebilir veya kendiniz bir sertifika oluşturabilirsiniz.You can procure a certificate from a trusted Certificate Authority, or generate a certificate yourself.

Bu bölümde, Azure Key Vault kullanılarak bir sertifika oluşturma ve genel anahtar içeren .cer dosyasını indirme işlemleri açıklanmaktadır.This section describes creating a certificate using Azure Key Vault, and downloading the .cer file which contains the public key.

  1. Microsoft Azure’da oturum açın.Log into Microsoft Azure.

  2. Anahtar Kasaları’nı arayın ve Anahtar Kasaları bağlantısına tıklayın.Search for Key Vaults and click the Key Vaults link.

    Azure portalındaki anahtar kasası bağlantısını gösteren ekran görüntüsü.

  3. Sertifika eklemek istediğiniz anahtar kasasına tıklayın.Click the key vault you want to add a certificate to.

    Azure portalındaki anahtar kasalarının bulanık bir listesini gösteren ekran görüntüsü.

  4. Sertifikalar’a tıklayın.Click Certificates.

    Sertifikalar'ın vurgulandığı Anahtar kasaları sayfasını gösteren ekran görüntüsü.

  5. Oluştur/İçeri Aktar’a tıklayın.Click Generate/Import.

    Oluştur/İçeri Aktar seçeneğinin vurgulandığı Sertifika bölmesini gösteren ekran görüntüsü.

  6. Sertifika oluştur alanlarını aşağıdaki şekilde yapılandırın:Configure the Create a certificate fields as follows:

    • Sertifika Oluşturma Yöntemi - GenelMethod of Certificate Creation - General

    • Sertifika Adı - Sertifikanız için bir ad girinCertificate Name - Enter a name for your certificate

    • Sertifika Yetkilisi (CA) Türü - Otomatik olarak imzalanan sertifikaType of Certificate Authority (CA) - Self-signed certificate

    • Konu - X.500 ayırt edici adıSubject - An X.500 distinguished name

    • DNS Adları - 0 DNS adıDNS Names - 0 DNS names

    • Geçerlilik Süresi (ay) - Sertifikanın geçerlilik süresini girinValidity Period (in months) - Enter the certificate's validity duration

    • İçerik Türü - PKCS #12Content Type - PKCS #12

    • Yaşam Süresi Eylem Türü - Belirli bir yaşam süresi yüzdesinde otomatik olarak yenilerLifetime Action Type - Automatically renew at a given percentage lifetime

    • Yaşam Süresi Yüzdesi - 80Percentage Lifetime - 80

    • Gelişmiş İlke Yapılandırması - YapılandırılmamışAdvanced Policy Configuration - Not configured

  7. Oluştur'a tıklayın.Click Create. Yeni oluşturulan sertifika varsayılan olarak devre dışı bırakılır.The newly created certificate is disabled by default. Etkinleştirilmeleri beş dakikaya kadar sürebilir.It can take up to five minutes to become enabled.

  8. Oluşturduğunuz sertifikayı seçin.Select the certificate you created.

  9. CER biçiminde indir’e tıklayın.Click Download in CER format. İndirilen dosyada ortak anahtar yer alır.The downloaded file contains the public key.

    CER biçiminde indir düğmesini gösteren ekran görüntüsü.

6. Adım: Sertifika kimlik doğrulaması ayarlamaStep 6 - Set up certificate authentication

  1. Azure AD uygulamanızda Sertifikalar ve gizli diziler sekmesine tıklayın.In your Azure AD application, click the Certificates & secrets tab.

    Azure portalında bir uygulamanın Sertifikalar ve gizli diziler bölmesini gösteren ekran görüntüsü.

  2. Sertifikayı karşıya yükle’ye tıklayın ve bu öğreticinin ilk adımında oluşturup indirdiğiniz .cer dosyasını karşıya yükleyin.Click Upload certificate and upload the .cer file you created and downloaded in the first step of this tutorial. .cer dosyası ortak anahtarı içerir.The .cer file contains the public key.

7. Adım: Azure Key Vault’tan bir sertifikayı almaStep 7 - Get the certificate from Azure Key Vault

Azure Key Vault’tan sertifikayı almak için Yönetilen Hizmet Kimliği’ni (MSI) kullanın.Use Managed Service Identity (MSI) to get the certificate from Azure Key Vault. Bu işlem, hem ortak hem de özel anahtarları içeren .pfx sertifikasını almayı içerir.This process involves getting the .pfx certificate that contains both the public and private keys.

Azure Key Vault’tan sertifikayı okumak için kod örneğine başvurun.Refer to the code example for reading the certificate from Azure Key Vault. Visual Studio kullanmak istiyorsanız Visual Studio’yu MSI kullanacak şekilde yapılandırma sayfasına başvurun.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));
}

8. Adım: Hizmet sorumlusu ve sertifika kullanarak kimlik doğrulaması yapmaStep 8 - Authenticate using service principal and a certificate

Azure Key Vault’a bağlanıp burada depolanan hizmet sorumlusunu ve sertifikayı kullanarak uygulamanızın kimliğini doğrulayabilirsiniz.You can authenticate your app using service principal and a certificate that's stored in Azure Key Vault, by connecting to Azure Key Vault.

Azure Key Vault’a bağlanıp sertifikayı okumak için aşağıdaki koda bakın.To connect and read the certificate from Azure Key Vault, refer to the code below.

Not

Kuruluşunuz tarafından oluşturulan bir sertifikaya zaten sahipseniz .pfx dosyasını Azure Key Vault’a yükleyin.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
}

Visual Studio’yu MSI kullanacak şekilde yapılandırmaConfigure Visual Studio to use MSI

Ekli çözümünüzü oluştururken Visual Studio’yu Yönetilen Hizmet Kimliği’ni (MSI) kullanacak şekilde yapılandırmanız yararlı olabilir.When creating your embedded solution, it may be useful to configure Visual Studio to use Managed Service Identity (MSI). MSI, Azure AD kimliğinizi yönetmenizi sağlayan bir özelliktir.MSI is a feature that enables you to manage your Azure AD identity. Yapılandırıldıktan sonra, Visual Studio’nun Azure Key Vault’a göre kimlik doğrulaması yapmasını sağlar.Once configured, it will let Visual Studio authenticate against your Azure Key Vault.

  1. Projenizi Visual Studio’da açın.Open your project in Visual Studio.

  2. Araçlar > Seçenekler’e tıklayın.Click Tools > Options.

    Visual Studio'nun Araçlar menüsündeki Seçenekler düğmesini gösteren ekran görüntüsü.

  3. Hesap Seçimi’ni arayın ve Hesap Seçimi’ne tıklayın.Search for Account Selection and click Account Selection.

    Visual Studio'nun seçenekler penceresindeki Hesap seçimi seçeneğini gösteren ekran görüntüsü.

  4. Azure Key Vault’unuz erişimi olan hesabı ekleyin.Add the account that has access to your Azure Key Vault.

Considerations and limitations

  • Service principal only works with new workspaces.
  • My Workspace isn't supported when using service principal.
  • A capacity is required when moving to production.
  • You can't sign into the Power BI portal using service principal.
  • Power BI admin rights are required to enable service principal in developer settings within the Power BI admin portal.
  • Embed for your organization applications can't use service principal.
  • Dataflows management is not supported.
  • Service principal currently does not support any admin APIs.
  • When using service principal with an Azure Analysis Services data source, the service principal itself must have an Azure Analysis Services instance permissions. Using a security group that contains the service principal for this purpose, doesn't work.

Sonraki adımlarNext steps