Skip to content

Latest commit

 

History

History
240 lines (140 loc) · 13 KB

service-to-service-authentication.md

File metadata and controls

240 lines (140 loc) · 13 KB
title description keywords author manager services ms.author ms.date ms.topic ms.prod ms.service ms.technology ms.assetid
Service-to-service authentication to Azure Key Vault using .NET
Use the Microsoft.Azure.Services.AppAuthentication library to authenticate to Azure Key Vault using .NET.
azure key-vault authentication local credentials
lleonard-msft
mbaldwin
key-vault
alleonar
11/15/2017
article
microsoft-keyvault
4be434c4-0c99-4800-b775-c9713c973ee9

Service-to-service authentication to Azure Key Vault using .NET

To authenticate to Azure Key Vault, you need an Azure Active Directory (AD) credential, either a shared secret or a certificate. Managing such credentials can be difficult and it's tempting to bundle credentials into an app by including them in source or configuration files.

The Microsoft.Azure.Services.AppAuthentication for .NET library simplifies this problem. It uses the developer's credentials to authenticate during local development. When the solution is later deployed to Azure, the library automatically switches to application credentials.

Using developer credentials during local development is more secure because you do not need to create Azure AD credentials or share credentials between developers.

The Microsoft.Azure.Services.AppAuthentication library manages authentication automatically, which in turn allows you to focus on your solution, rather than your credentials.

The Microsoft.Azure.Services.AppAuthentication library supports local development with Microsoft Visual Studio, Azure CLI, or Azure AD Integrated Authentication. When deployed to Azure App Services or an Azure Virtual Machine (VM), the library automatically uses Managed Service Identity (MSI). No code or configuration changes are required. The library also supports direct use of Azure AD client credentials when MSI is not available or when the developer's security context cannot be determined during local development.

Using the library

For .NET applications, the simplest way to work with a Managed Service Identity (MSI) is through the Microsoft.Azure.Services.AppAuthentication package. Here's how to get started:

  1. Add a reference to the Microsoft.Azure.Services.AppAuthentication NuGet package to your application.

  2. Add the following code:

    using Microsoft.Azure.Services.AppAuthentication;
using Microsoft.Azure.KeyVault;

// ...

var kv = new KeyVaultClient(new KeyVaultClient.AuthenticationCallback(
azureServiceTokenProvider.KeyVaultTokenCallback));

// or

var azureServiceTokenProvider = new AzureServiceTokenProvider();
string accessToken = await azureServiceTokenProvider.GetAccessTokenAsync(
   "https://management.azure.com/").ConfigureAwait(false);

The AzureServiceTokenProvider class caches the token in memory and retrieves it from Azure AD just before expiration. Consequently, you no longer have to check the expiration before calling the GetAccessTokenAsync method. Just call the method when you want to use the token.

The GetAccessTokenAsync method requires a resource identifier. To learn more, see Which Azure services support Managed Service Identity.

Samples

The following samples show the Microsoft.Azure.Services.AppAuthentication library in action:

  1. Use a Managed Service Identity (MSI) to retrieve a secret from Azure Key Vault at runtime

  2. Programmatically deploy an Azure Resource Manager template from an Azure VM with an MSI.

  3. Use .NET Core sample and MSI to call Azure services from an Azure Linux VM.

Local development authentication

For local development, there are two primary authentication scenarios:

Here, you learn the requirements for each scenario and supported tools.

Authenticating to Azure Services

Local machines do not support Managed Service Identity (MSI). As a result, the Microsoft.Azure.Services.AppAuthentication library uses your developer credentials to run in your local development environment. When the solution is deployed to Azure, the library uses MSI to switch to an OAuth 2.0 client credential grant flow. This means you can test the same code locally and remotely without worry.

For local development, AzureServiceTokenProvider fetches tokens using Visual Studio, Azure command-line interface (CLI), or Azure AD Integrated Authentication. Each option is tried sequentially and the library uses the first option that succeeds. If no option works, an AzureServiceTokenProviderException exception is thrown with detailed information.

Authenticating with Visual Studio

To use Visual Studio, verify:

  1. You've installed Visual Studio 2017 v15.5 or later.

  2. The App Authentication extension for Visual Studio is installed.

  3. You signed in to Visual Studio and have selected an account to use for local development. Use Tools > Options > Azure Service Authentication to choose a local development account.

If you run into problems using Visual Studio, such as errors regarding the token provider file, carefully review these steps.

It may also be necessary to reauthenticate your developer token. To do so, go to Tools > Options>Azure Service Authentication and look for a Re-authenticate link under the selected account. Select it to authenticate.

Authenticating with Azure CLI

To use Azure CLI for local development:

  1. Install Azure CLI v2.0.12 or later. Upgrade earlier versions.

  2. Use az login to sign in to Azure.

Use az account get-access-token to verify access. If you receive an error, verify that Step 1 completed successfully.

If Azure CLI is not installed to the default directory, you may receive an error reporting that AzureServiceTokenProvider cannot find the path for Azure CLI. Use the AzureCLIPathenvironment variable to define the Azure CLI installation folder. AzureServiceTokenProvider adds the directory specified in the AzureCLIPath environment variable to the Path environment variable when necessary.

If you are signed in to Azure CLI using multiple accounts or your account has access to multiple subscriptions, you need to specify the specific subscription to be used. To do so, use:

az account set --subscription <subscription-id>

This command generates output only on failure. To verify the current account settings, use:

az account list

Authenticating with Azure AD Integrate authentication

To use Azure AD authentication, verify that:

  • Your on-premises active directory syncs to Azure AD.

  • Your code is running on a domain-joined machine.

Authenticating to custom services

When a service calls Azure services, the previous steps work because Azure services allow access to both users and applications.

When creating a service that calls a custom service, use Azure AD client credentials for local development authentication. There are two options:

  1. Use a service principal to sign into Azure:

    1. Create a service principal.

    2. Use Azure CLI to sign in:

      az login --service-principal -u <principal-id> --password <password>
   --tenant <tenant-id> --allow-no-subscriptions

      Because the service principal may not have access to a subscription, use the --allow-no-subscriptions argument.

  2. Use environment variables to specify service principal details. For details, see Running the application using a service principal.

Once you've signed in to Azure, AzureServiceTokenProvider uses the service principal to retrieve a token for local development.

This applies only to local development. When your solution is deployed to Azure, the library switches to MSI authentication.

Running the application using a Managed Service Identity

When you run your code on an Azure App Service or an Azure VM with MSI enabled, the library automatically uses Managed Service Identity. No code changes are required.

Running the application using a Service Principal

It may be necessary to create an Azure AD Client credential to authenticate. Common examples include:

  1. Your code runs on a local development environment, but not under the developer's identity. Service Fabric, for example, uses the NetworkService account for local development.

  2. Your code runs on a local development environment and you authenticate to a custom service, so you can't use your developer identity.

  3. Your code is running on an Azure compute resource that does not yet support Managed Service Identity, such as Azure Batch.

To use a certificate to sign into Azure AD:

  1. Create a service principal certificate.

  2. Deploy the certificate to either the LocalMachine or CurrentUser store.

  3. Set an environment variable named AzureServicesAuthConnectionString to:

    RunAs=App;AppId={AppId};TenantId={TenantId};CertificateThumbprint={Thumbprint};
      CertificateStoreLocation={LocalMachine or CurrentUser}.

    Replace {AppId}, {TenantId}, and {Thumbprint} with values generated in Step 1.

    CertificateStoreLocation must be either CurrentUser or LocalMachine, based on your deployment plan.

  4. Run the application.

To sign in using an Azure AD shared secret credential:

  1. Create a service principal with a password and grant it access to the Key Vault.

  2. Set an environment variable named AzureServicesAuthConnectionString to:

    RunAs=App;AppId={AppId};TenantId={TenantId};AppKey={ClientSecret}.

    Replace {AppId}, {TenantId}, and {ClientSecret} with values generated in Step 1.

  3. Run the application.

Once everything's set up correctly, no further code changes are necessary. AzureServiceTokenProvider uses the environment variable and the certificate to authenticate to Azure AD.

Connection String Support

By default, AzureServiceTokenProvider uses multiple methods to retrieve a token.

To control the process, use a connection string passed to the AzureServiceTokenProvider constructor or specified in the AzureServicesAuthConnectionString environment variable.

The following options are supported:

Connection string option Scenario Comments
RunAs=Developer; DeveloperTool=AzureCli Local development AzureServiceTokenProvider uses AzureCli to get token.
RunAs=Developer; DeveloperTool=VisualStudio Local development AzureServiceTokenProvider uses Visual Studio to get token.
RunAs=CurrentUser; Local development AzureServiceTokenProvider uses Azure AD Integrated Authentication to get token.
RunAs=App; Managed Service Identity AzureServiceTokenProvider uses Managed Service Identity to get token.
RunAs=App;AppId={AppId};TenantId={TenantId};CertificateThumbprint
={Thumbprint};CertificateStoreLocation={LocalMachine or CurrentUser}		 Service principal AzureServiceTokenProvider uses certificate to get token from Azure AD.
RunAs=App;AppId={AppId};TenantId={TenantId};
CertificateSubjectName={Subject};CertificateStoreLocation=
{LocalMachine or CurrentUser}		 Service principal AzureServiceTokenProvider uses certificate to get token from Azure AD
RunAs=App;AppId={AppId};TenantId={TenantId};AppKey={ClientSecret} Service principal AzureServiceTokenProvider uses secret to get token from Azure AD.

Next steps