서비스 주체 및 인증서를 사용하여 Power BI 콘텐츠 포함Embed 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

참고

비밀 키가 아닌 인증서를 사용하여 백 엔드 서비스를 보호하는 것이 좋습니다.We recommend that you secure your backend services using certificates, rather than secret keys. 비밀 키 또는 인증서를 사용하여 Azure AD에서 액세스 토큰을 가져오는 방법에 대해 자세히 알아보세요.Learn more about getting access tokens from Azure AD using secret keys or certificates.

인증서 기반 인증Certificate-based authentication

인증서 기반 인증을 사용하면 Windows, Android 또는 iOS 디바이스의 클라이언트 인증서를 사용하여 Azure AD(Azure Active Directory)에서 인증을 받거나 Azure Key Vault에 보관할 수 있습니다.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.

이 인증 방법을 사용하면 중앙에서 CA를 사용하여 순환 또는 해지를 위해 인증서를 관리할 수 있습니다.Using this method of authentication allows managing certificates from a central place, using the CA, for rotation or revocation.

Azure AD의 인증서에 대한 자세한 내용은 클라이언트 자격 증명 흐름 GitHub 페이지에서 확인할 수 있습니다.You can learn more about certificates in Azure AD in the Client credential flows GitHub page.

메서드Method

서비스 주체 및 인증서를 임베디드 분석과 함께 사용하려면 다음 단계를 수행합니다.To use service principal and a certificate with embedded analytics, follow these steps:

  1. Azure AD 애플리케이션을 만듭니다.Create an Azure AD Application.

  2. Azure AD 보안 그룹을 만듭니다.Create an Azure AD security group.

  3. Power BI 서비스 관리자 설정을 사용하도록 설정합니다.Enable the Power BI service admin settings.

  4. 작업 영역에 서비스 주체를 추가합니다.Add the service principal to your workspace.

  5. 인증서 만들기Create a certificate.

  6. 인증서 인증을 설정합니다.Set up certificate authentication.

  7. Azure Key Vault에서 인증서를 가져옵니다.Get the certificate from Azure Key Vault.

  8. 서비스 주체 및 인증서를 사용하여 인증합니다.Authenticate using service principal and a certificate.

1단계 - Azure AD 애플리케이션 만들기Step 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을 사용하여 Azure AD 앱 만들기Creating an Azure AD app using PowerShell

이 섹션에는 PowerShell을 사용하여 새 Azure AD 앱을 만드는 샘플 스크립트가 포함되어 있습니다.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.

참고

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.

중요

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.

참고

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단계 - 인증서 만들기Step 5 - Create a certificate

신뢰할 수 있는 ‘인증 기관’에서 인증서를 구하거나 인증서를 직접 생성할 수 있습니다.You can procure a certificate from a trusted Certificate Authority , or generate a certificate yourself.

이 섹션에서는 Azure Key Vault를 사용하여 인증서를 만들고 공개 키가 포함된 .cer 파일을 다운로드하는 방법을 설명합니다.This section describes creating a certificate using Azure Key Vault, and downloading the .cer file which contains the public key.

  1. Microsoft Azure에 로그인합니다.Log into Microsoft Azure.

  2. Key Vaults 를 검색하고 Key Vaults 링크를 클릭합니다.Search for Key Vaults and click the Key Vaults link.

    Azure Portal의 키 자격 증명 모음에 대한 링크를 보여주는 스크린샷.

  3. 인증서를 추가하려는 키 자격 증명 모음을 클릭합니다.Click the key vault you want to add a certificate to.

    Azure Portal에서 흐리게 표시된 키 자격 증명 모음 목록을 보여주는 스크린샷.

  4. 인증서 를 클릭합니다.Click Certificates .

    인증서가 호출된 키 자격 증명 모음 페이지를 보여주는 스크린샷.

  5. 생성/가져오기 를 클릭합니다.Click Generate/Import .

    생성/가져오기가 호출된 인증서 창을 보여주는 스크린샷.

  6. 다음과 같이 인증서 만들기 필드를 구성합니다.Configure the Create a certificate fields as follows:

    • 인증서를 만드는 방법 - 일반Method of Certificate Creation - General

    • 인증서 이름 - 인증서의 이름을 입력합니다.Certificate Name - Enter a name for your certificate

    • CA(인증 기관)의 유형 - 자체 서명된 인증서Type of Certificate Authority (CA) - Self-signed certificate

    • 주체 - An X.500 고유 이름Subject - An X.500 distinguished name

    • DNS 이름 - 0개의 DNS 이름DNS Names - 0 DNS names

    • 유효 기간(개월) - 인증서의 유효 기간 입력Validity Period (in months) - Enter the certificate's validity duration

    • 콘텐츠 형식 - PKCS #12Content Type - PKCS #12

    • 수명 동작 유형 - 지정된 백분율 수명에 자동으로 갱신Lifetime Action Type - Automatically renew at a given percentage lifetime

    • 백분율 수명 - 80Percentage Lifetime - 80

    • 고급 정책 구성 - 구성되지 않음Advanced Policy Configuration - Not configured

  7. 만들기 를 클릭합니다.Click Create . 새로 만든 인증서는 기본적으로 사용되지 않도록 설정되어 있습니다.The newly created certificate is disabled by default. 사용하도록 설정하는 데 최대 5분이 걸릴 수 있습니다.It can take up to five minutes to become enabled.

  8. 만든 인증서를 선택합니다.Select the certificate you created.

  9. CER 형식으로 다운로드 를 클릭합니다.Click Download in CER format . 다운로드한 파일에는 공개 키가 들어 있습니다.The downloaded file contains the public key.

    CER 형식으로 다운로드 단추를 표시하는 스크린샷.

6단계 - 인증서 인증 설정Step 6 - Set up certificate authentication

  1. Azure AD 애플리케이션에서 인증서 및 암호 탭을 클릭합니다.In your Azure AD application, click the Certificates & secrets tab.

    Azure Portal에서 앱의 인증서 및 비밀 창을 보여주는 스크린샷.

  2. 인증서 업로드 를 클릭하고 이 자습서의 1단계에서 만들고 다운로드한 .cer 파일을 업로드합니다.Click Upload certificate and upload the .cer file you created and downloaded in the first step of this tutorial. .cer 파일에는 공개 키가 들어 있습니다.The .cer file contains the public key.

7단계 - Azure Key Vault에서 인증서 가져오기Step 7 - Get the certificate from Azure Key Vault

MSI(관리 서비스 ID)를 사용하여 Azure Key Vault에서 인증서를 가져옵니다.Use Managed Service Identity (MSI) to get the certificate from Azure Key Vault. 이 프로세스에는 퍼블릭 키와 프라이빗 키가 둘 다 들어 있는 .pfx 인증서를 가져오는 과정이 포함됩니다.This process involves getting the .pfx certificate that contains both the public and private keys.

Azure Key Vault에서 인증서를 읽는 방법에 대한 코드 예제를 참조하세요.Refer to the code example for reading the certificate from Azure Key Vault. Visual Studio를 사용하려면 MSI를 사용하도록 Visual Studio 구성을 참조하세요.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단계 - 서비스 주체 및 인증서를 사용하여 인증Step 8 - Authenticate using service principal and a certificate

Azure Key Vault에 연결하여 Azure Key Vault에 저장된 인증서 및 서비스 주체를 사용하여 앱을 인증할 수 있습니다.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에서 인증서를 연결하고 읽으려면 아래 코드를 참조하세요.To connect and read the certificate from Azure Key Vault, refer to the code below.

참고

조직에서 만든 인증서가 이미 있는 경우 Azure Key Vault에 .pfx 파일을 업로드합니다.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
}

MSI를 사용하도록 Visual Studio 구성Configure Visual Studio to use MSI

포함된 솔루션을 만들 때 MSI(관리 서비스 ID)를 사용하도록 Visual Studio를 구성하는 것이 유용할 수 있습니다.When creating your embedded solution, it may be useful to configure Visual Studio to use Managed Service Identity (MSI). MSI는 Azure AD ID를 관리할 수 있는 기능입니다.MSI is a feature that enables you to manage your Azure AD identity. 구성된 후에는 Visual Studio가 Azure Key Vault에 대해 인증을 수행하도록 합니다.Once configured, it will let Visual Studio authenticate against your Azure Key Vault.

  1. Visual Studio에서 새 프로젝트를 엽니다.Open your project in Visual Studio.

  2. 도구 > 옵션 을 클릭합니다.Click Tools > Options .

    Visual Studio의 도구 메뉴에 있는 옵션 단추를 보여주는 스크린샷.

  3. 계정 선택 를 검색하고 계정 선택 을 클릭합니다.Search for Account Selection and click Account Selection .

    Visual Studio 옵션 창의 계정 선택 옵션을 보여주는 스크린샷.

  4. Azure Key Vault에 대한 액세스 권한이 있는 계정을 추가합니다.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.

다음 단계Next steps