Using certificates

Jump to bottom
Jenny Ferries edited this page Sep 22, 2020 · 30 revisions

Using certificates with Microsoft.Identity.Web

Microsoft.Identity.Web uses certificates in two situations:

  • In web apps and web APIs, to prove the identity of the application, instead of using a client secret.
  • In web APIs, to decrypt tokens if the web API opted to get encrypted tokens.

This article explains both usages, as well as describes the certificates to use.

Table of contents:

Client certificates

Web apps and web APIs are confidential client applications.

They can prove their identity to Azure AD or Azure AD B2C by 3 means:

MethodSupported in Microsoft.Identity.Web
Client secretsYes
Client certificatesYes
Client assertionsNot yet

Microsoft.Identity.Web supports specifying client certificates. The configuration property to specify the client certificates is ClientCertificates. It is an array of certificate descriptions. There are several ways of describing certificates. see Specifying certificates below.

Describing client certificates to use by configuration

You can express the client certificates in the ClientCertificates property. ClientCertificates and ClientSecret are mutually exclusive.

{
"AzureAd": {
"Instance": "https://login.microsoftonline.com/",
"Domain": "msidentitysamplestesting.onmicrosoft.com",
"TenantId": "7f58f645-c190-4ce5-9de4-e2b7acd2a6ab",
"ClientId": "86699d80-dd21-476a-bcd1-7c1a3d471f75",
"ClientCertificates": [
{
"SourceType": "KeyVault",
"KeyVaultUrl": "https://msidentitywebsamples.vault.azure.net",
"KeyVaultCertificateName": "MicrosoftIdentitySamplesCert"
}
]
}
}

See Specifying certificates below for all the ways to describe certificates.

Describing client certificates to use programmatically

You can also specify the certificate description programmatically. For this you add CertificateDescription instances to the ClientCertificates property of MicrosoftIdentityOptions. You can then use some of the overloads of AddMicrosoftIdentityWebApp, EnableTokenAcquisitionToCallDownstreamApi using delegates to set the MicrosoftIdentityOptions.

MicrosoftIdentityOptionsoptions=newMicrosoftIdentityOptions();options.ClientCertificates=newCertificateDescription[]{CertificateDescription.FromKeyVault("https://msidentitywebsamples.vault.azure.net","MicrosoftIdentitySamplesCert")};

See Specifying certificates below for all the ways to describe certificates.

Decryption certificates

Web APIs can request token encryption (for privacy reasons). This is even compulsory for first-party (Microsoft) web APIs that access MSA identities. The configuration property to specify the client certificates is TokenDecryptionCertificates. It is an array of descriptions of certificates.

Describing decryption certificates to use by configuration

You can express the decryption certificates in the TokenDecryptionCertificates property.

{
"AzureAd": {
"Instance": "https://login.microsoftonline.com/",
"Domain": "msidentitysamplestesting.onmicrosoft.com",
"TenantId": "7f58f645-c190-4ce5-9de4-e2b7acd2a6ab",
"ClientId": "86699d80-dd21-476a-bcd1-7c1a3d471f75",
"TokenDecryptionCertificates": [
{
"SourceType": "KeyVault",
"KeyVaultUrl": "https://msidentitywebsamples.vault.azure.net",
"KeyVaultCertificateName": "MicrosoftIdentitySamplesCert"
}
]
}
}

See Specifying certificates below for all the ways to describe certificates.

Describing decryption certificates to use programmatically

You can also specify the certificate description programmatically:

MicrosoftIdentityOptionsoptions=newMicrosoftIdentityOptions();options.TokenDecryptionCertificates=newCertificateDescription[]{CertificateDescription.FromKeyVault("https://msidentitywebsamples.vault.azure.net","MicrosoftIdentitySamplesCert")};

See Specifying certificates below for all the ways to describe certificates.

Helping certificate rotation by sending x5c

It's possible to specify if the x5c claim (public key of the certificate) should be sent to the STS each time the web app or web API calls Azure AD. Sending the x5c enables application developers to achieve easy certificate rollover in Azure AD: this method will send the public certificate to Azure AD along with the token request, so that Azure AD can use it to validate the subject name based on a trusted issuer policy. This saves the application admin from the need to explicitly manage the certificate rollover (either via portal or PowerShell/CLI operation). For details see https://aka.ms/msal-net-sni.

To specify to send the x5c claim, set the boolean SendX5C property of the options to true either by configuration or programmatically.

{
"AzureAd": {
"Instance": "https://login.microsoftonline.com/",
"Domain": "msidentitysamplestesting.onmicrosoft.com",
"TenantId": "7f58f645-c190-4ce5-9de4-e2b7acd2a6ab",
"ClientId": "86699d80-dd21-476a-bcd1-7c1a3d471f75",
"TokenDecryptionCertificates": [
{
"SourceType": "KeyVault",
"KeyVaultUrl": "https://msidentitywebsamples.vault.azure.net",
"KeyVaultCertificateName": "MicrosoftIdentitySamplesCert"
}
],
"SendX5C": "true"
}
}

Specifying certificates

You can describe the certificates to load, either by configuration, or programmatically:

  • from the certificate store (Windows) and a thumbprint ("440A5BE6C4BE2FF02A0ADBED1AAA43D6CF12E269"),
  • from the certificate store (Windows) and a distinguished name ("CN=TestCert"),
  • from a path on the disk and optionally a password (probably only for debugging locally),
  • directly from a Base64 representation of the certificate,
  • from Azure Key Vault,
  • directly providing it (programmatically only).

Describing the certificate by configuration allows for just-in-time loading, rather than paying the startup cost. For instance for a web app that signs in a user, do not load the certificate until an access token is needed to call a web API.

When your certificate is in Key Vault, Microsoft.Identity.Web leverages Managed Identity, therefore enabling your application to have the same code when deployed (for instance on a VM or Azure app services), or locally on your developer box (using developer credentials).

The following sections show how to specify the client credential certificates, but the principle is the same for the decryption certificates. Just replace ClientCertificates with TokenDecryptionCertificates.

Getting certificates from Key Vault

Microsoft.Identity.Web leverages Managed Identity

To fetch certificates from KeyVault, Microsoft.Identity.Web leverages Managed Identity through the Azure SDK DefaultAzureCredential.

This works out of the box on the developer machine using the developer credentials, and also when deployed with Service fabric or App Services in Azure provided you've been using a System-assigned Managed identity.

However:

  • If you are using a User-assigned managed identity, you will need to set an environment variable AZURE_CLIENT_ID to be the user-assigned managed identity clientID. You can do that through the Azure portal:

    1. Go to Azure App Service -> Settings | Configuration -> Application Settings
    2. Add or update the AZURE_CLIENT_ID app setting to the user assigned managed identity ID.

  • When used on your developer machine, you have several accounts in Visual Studio, you'll need to specify which account to use, by setting another environement variable AZURE_USERNAME

Specifying client certificate from Key Vault by configuration
{
"ClientCertificates": [
{
"SourceType": "KeyVault",
"KeyVaultUrl": "https://msidentitywebsamples.vault.azure.net",
"KeyVaultCertificateName": "MicrosoftIdentitySamplesCert"
}
]
}
}
Specifying client certificate from Key Vault programmatically
MicrosoftIdentityOptionsoptions=newMicrosoftIdentityOptions();options.ClientCertificates=newCertificateDescription[]{CertificateDescription.FromKeyVault("https://msidentitywebsamples.vault.azure.net","MicrosoftIdentitySamplesCert")};

Specifying certificates from a path

Specifying certificates from a path by configuration
{
"ClientCertificates": [
{
"SourceType": "Path",
"CertificateDiskPath": "c:\\temp\\WebAppCallingWebApiCert.pfx",
"CertificatePassword": "password"
}]
}
Specifying certificates from a path programmatically
MicrosoftIdentityOptionsoptions=newMicrosoftIdentityOptions();options.ClientCertificates=newCertificateDescription[]{CertificateDescription.FromPath(@"c:\temp\WebAppCallingWebApiCert.pfx","password")};

Specifying certificates from a certificate store by distinguished name

Specifying certificates from a certificate store by distinguished name by configuration
{
"ClientCertificates": [
{
"SourceType": "StoreWithDistinguishedName",
"CertificateStorePath": "CurrentUser/My",
"CertificateDistinguishedName": "CN=WebAppCallingWebApiCert"
}]
}
Specifying certificates from a certificate store by distinguished name programmatically
MicrosoftIdentityOptionsoptions=newMicrosoftIdentityOptions();options.ClientCertificates=newCertificateDescription[]{CertificateDescription.FromStoreWithDistinguishedName(StoreLocation.CurrentUser,StoreName.My,"CN=WebAppCallingWebApiCert")};

Specifying certificates from a certificate store by thumbprint

Specifying certificates from a certificate store by thumbprint by configuration
{
"ClientCertificates": [
{
"SourceType": "StoreWithThumbprint",
"CertificateStorePath": "CurrentUser/My",
"CertificateThumbprint": "962D129A859174EE8B5596985BD18EFEB6961684"
}]
}
Specifying certificates from a certificate store by thumbprint programmatically
MicrosoftIdentityOptionsoptions=newMicrosoftIdentityOptions();options.ClientCertificates=newCertificateDescription[]{CertificateDescription.FromStoreWithThumbprint(StoreLocation.CurrentUser,StoreName.My,"962D129A859174EE8B5596985BD18EFEB6961684")};

Specifying certificates from a certificate store by Base64 encoded value

Specifying certificates from a certificate store by Base64 encoded value by configuration
{
"ClientCertificates": [
{
"SourceType": "Base64Encoded",
"Base64EncodedValue": "MIIDHzCCAgegA.....r1n8Czew8TPfab4OG37BuEMNmBpqoRrRgFnDzVtItOnhuFTa0="
}]
}
Specifying certificates from a certificate store by Base64 encoded value programmatically
MicrosoftIdentityOptionsoptions=newMicrosoftIdentityOptions();options.ClientCertificates=newCertificateDescription[]{CertificateDescription.FromBase64Encoded("MIIDHzCCAgegA.....r1n8Czew8TPfab4OG37BuEMNmBpqoRrRgFnDzVtItOnhuFTa0=")};

Specifying certificates as an X509Certificate2

You can also directly specify the certificate description as an X509Certificate2 that would you have loaded. This is only possible programmatically

MicrosoftIdentityOptionsoptions=newMicrosoftIdentityOptions();options.ClientCertificates=newCertificateDescription[]{CertificateDescription.FromCertificate(x509certificate2)};

Microsoft Identity Web classes used for certificate management

This is a class diagram showing how the classes involved in certificate management in Microsoft.Identity.Web are articulated:

image

Getting started with Microsoft Identity Web

Credentials

Token cache serialization

Web apps

Web APIs

Daemon scenario

Advanced topics

Extensibility

Credential providers

FAQ

News

Contribute

Other resources

Clone this wiki locally

, 'i'); if (__m === '*' || __re.test(location.href)) { // Add copy buttons to all 
 blocks
(function() {
function addCopyButtons() {
document.querySelectorAll('pre code').forEach(function(codeBlock) {
if (codeBlock.parentElement.hasAttribute('data-copy-added')) return;
codeBlock.parentElement.setAttribute('data-copy-added', 'true');
var btn = document.createElement('button');
btn.textContent = 'Copy';
btn.style.cssText = 'position:absolute;top:4px;right:4px;padding:2px 8px;font-size:11px;background:#4ecdc4;border:none;border-radius:4px;color:#1a1a2e;cursor:pointer;opacity:0.7;transition:opacity 0.2s;';
btn.onmouseover = function() { this.style.opacity = '1'; };
btn.onmouseout = function() { this.style.opacity = '0.7'; };
btn.onclick = function() {
navigator.clipboard.writeText(codeBlock.textContent).then(function() {
btn.textContent = 'Copied!';
setTimeout(function() { btn.textContent = 'Copy'; }, 1500);
});
};
codeBlock.parentElement.style.position = 'relative';
codeBlock.parentElement.appendChild(btn);
});
}
addCopyButtons();
// Re-run on dynamic content
var observer = new MutationObserver(addCopyButtons);
observer.observe(document.body, { childList: true, subtree: true });
})();
}
} catch(__e) { console.warn('[Userscript:Add Copy Buttons to Code Blocks]', __e); }
})();
(function(){
try {
var __m = "github.com";
var __re = new RegExp('^' + "github\\.com" + '

Skip to content
Using certificates
Jump to bottom

Jenny Ferries edited this page Sep 22, 2020
·
30 revisions
Using certificates with Microsoft.Identity.Web
Microsoft.Identity.Web uses certificates in two situations:
  • In web apps and web APIs, to prove the identity of the application, instead of using a client secret.
  • In web APIs, to decrypt tokens if the web API opted to get encrypted tokens.
This article explains both usages, as well as describes the certificates to use.
Table of contents:
Client certificates
Web apps and web APIs are confidential client applications.
They can prove their identity to Azure AD or Azure AD B2C by 3 means:
MethodSupported in Microsoft.Identity.Web
Client secretsYes
Client certificatesYes
Client assertionsNot yet
Microsoft.Identity.Web supports specifying client certificates. The configuration property to specify the client certificates is ClientCertificates. It is an array of certificate descriptions. There are several ways of describing certificates. see Specifying certificates below.
Describing client certificates to use by configuration
You can express the client certificates in the ClientCertificates property. ClientCertificates and ClientSecret are mutually exclusive.
{
"AzureAd": {
"Instance": "https://login.microsoftonline.com/",
"Domain": "msidentitysamplestesting.onmicrosoft.com",
"TenantId": "7f58f645-c190-4ce5-9de4-e2b7acd2a6ab",
"ClientId": "86699d80-dd21-476a-bcd1-7c1a3d471f75",
"ClientCertificates": [
{
"SourceType": "KeyVault",
"KeyVaultUrl": "https://msidentitywebsamples.vault.azure.net",
"KeyVaultCertificateName": "MicrosoftIdentitySamplesCert"
}
]
}
}
See Specifying certificates below for all the ways to describe certificates.
Describing client certificates to use programmatically
You can also specify the certificate description programmatically. For this you add CertificateDescription instances to the ClientCertificates property of MicrosoftIdentityOptions. You can then use some of the overloads of AddMicrosoftIdentityWebApp, EnableTokenAcquisitionToCallDownstreamApi using delegates to set the MicrosoftIdentityOptions.
MicrosoftIdentityOptionsoptions=newMicrosoftIdentityOptions();options.ClientCertificates=newCertificateDescription[]{CertificateDescription.FromKeyVault("https://msidentitywebsamples.vault.azure.net","MicrosoftIdentitySamplesCert")};
See Specifying certificates below for all the ways to describe certificates.
Decryption certificates
Web APIs can request token encryption (for privacy reasons). This is even compulsory for first-party (Microsoft) web APIs that access MSA identities. The configuration property to specify the client certificates is TokenDecryptionCertificates. It is an array of descriptions of certificates.
Describing decryption certificates to use by configuration
You can express the decryption certificates in the TokenDecryptionCertificates property.
{
"AzureAd": {
"Instance": "https://login.microsoftonline.com/",
"Domain": "msidentitysamplestesting.onmicrosoft.com",
"TenantId": "7f58f645-c190-4ce5-9de4-e2b7acd2a6ab",
"ClientId": "86699d80-dd21-476a-bcd1-7c1a3d471f75",
"TokenDecryptionCertificates": [
{
"SourceType": "KeyVault",
"KeyVaultUrl": "https://msidentitywebsamples.vault.azure.net",
"KeyVaultCertificateName": "MicrosoftIdentitySamplesCert"
}
]
}
}
See Specifying certificates below for all the ways to describe certificates.
Describing decryption certificates to use programmatically
You can also specify the certificate description programmatically:
MicrosoftIdentityOptionsoptions=newMicrosoftIdentityOptions();options.TokenDecryptionCertificates=newCertificateDescription[]{CertificateDescription.FromKeyVault("https://msidentitywebsamples.vault.azure.net","MicrosoftIdentitySamplesCert")};
See Specifying certificates below for all the ways to describe certificates.
Helping certificate rotation by sending x5c
It's possible to specify if the x5c claim (public key of the certificate) should be sent to the STS each
time the web app or web API calls Azure AD. Sending the x5c enables application developers to achieve easy certificate
rollover in Azure AD: this method will send the public certificate to Azure AD along with the token request,
so that Azure AD can use it to validate the subject name based on a trusted issuer policy.
This saves the application admin from the need to explicitly manage the certificate rollover
(either via portal or PowerShell/CLI operation). For details see https://aka.ms/msal-net-sni.
To specify to send the x5c claim, set the boolean SendX5C property of the options to true either by configuration
or programmatically.
{
"AzureAd": {
"Instance": "https://login.microsoftonline.com/",
"Domain": "msidentitysamplestesting.onmicrosoft.com",
"TenantId": "7f58f645-c190-4ce5-9de4-e2b7acd2a6ab",
"ClientId": "86699d80-dd21-476a-bcd1-7c1a3d471f75",
"TokenDecryptionCertificates": [
{
"SourceType": "KeyVault",
"KeyVaultUrl": "https://msidentitywebsamples.vault.azure.net",
"KeyVaultCertificateName": "MicrosoftIdentitySamplesCert"
}
],
"SendX5C": "true"
}
}
Specifying certificates
You can describe the certificates to load, either by configuration, or programmatically:
  • from the certificate store (Windows) and a thumbprint ("440A5BE6C4BE2FF02A0ADBED1AAA43D6CF12E269"),
  • from the certificate store (Windows) and a distinguished name ("CN=TestCert"),
  • from a path on the disk and optionally a password (probably only for debugging locally),
  • directly from a Base64 representation of the certificate,
  • from Azure Key Vault,
  • directly providing it (programmatically only).
Describing the certificate by configuration allows for just-in-time loading, rather than paying the startup cost. For instance for a web app that signs in a user, do not load the certificate until an access token is needed to call a web API.
When your certificate is in Key Vault, Microsoft.Identity.Web leverages Managed Identity, therefore enabling your application to have the same code when deployed (for instance on a VM or Azure app services), or locally on your developer box (using developer credentials).
The following sections show how to specify the client credential certificates, but the principle is the same for the decryption certificates. Just replace ClientCertificates with TokenDecryptionCertificates.
Getting certificates from Key Vault
Microsoft.Identity.Web leverages Managed Identity
To fetch certificates from KeyVault, Microsoft.Identity.Web leverages Managed Identity through the Azure SDK
DefaultAzureCredential.
This works out of the box on the developer machine using the developer credentials, and also when deployed with Service fabric or App Services in Azure
provided you've been using a System-assigned Managed identity.
However:
  • If you are using a User-assigned managed identity, you will need to set an environment variable AZURE_CLIENT_ID to be the
user-assigned managed identity clientID. You can do that through the Azure portal:
    1. Go to Azure App Service -> Settings | Configuration -> Application Settings
    2. Add or update the AZURE_CLIENT_ID app setting to the user assigned managed identity ID.
  • When used on your developer machine, you have several accounts in Visual Studio, you'll need to specify
which account to use, by setting another environement variable AZURE_USERNAME
Specifying client certificate from Key Vault by configuration
{
"ClientCertificates": [
{
"SourceType": "KeyVault",
"KeyVaultUrl": "https://msidentitywebsamples.vault.azure.net",
"KeyVaultCertificateName": "MicrosoftIdentitySamplesCert"
}
]
}
}
Specifying client certificate from Key Vault programmatically
MicrosoftIdentityOptionsoptions=newMicrosoftIdentityOptions();options.ClientCertificates=newCertificateDescription[]{CertificateDescription.FromKeyVault("https://msidentitywebsamples.vault.azure.net","MicrosoftIdentitySamplesCert")};
Specifying certificates from a path
Specifying certificates from a path by configuration
{
"ClientCertificates": [
{
"SourceType": "Path",
"CertificateDiskPath": "c:\\temp\\WebAppCallingWebApiCert.pfx",
"CertificatePassword": "password"
}]
}
Specifying certificates from a path programmatically
MicrosoftIdentityOptionsoptions=newMicrosoftIdentityOptions();options.ClientCertificates=newCertificateDescription[]{CertificateDescription.FromPath(@"c:\temp\WebAppCallingWebApiCert.pfx","password")};
Specifying certificates from a certificate store by distinguished name
Specifying certificates from a certificate store by distinguished name by configuration
{
"ClientCertificates": [
{
"SourceType": "StoreWithDistinguishedName",
"CertificateStorePath": "CurrentUser/My",
"CertificateDistinguishedName": "CN=WebAppCallingWebApiCert"
}]
}
Specifying certificates from a certificate store by distinguished name programmatically
MicrosoftIdentityOptionsoptions=newMicrosoftIdentityOptions();options.ClientCertificates=newCertificateDescription[]{CertificateDescription.FromStoreWithDistinguishedName(StoreLocation.CurrentUser,StoreName.My,"CN=WebAppCallingWebApiCert")};
Specifying certificates from a certificate store by thumbprint
Specifying certificates from a certificate store by thumbprint by configuration
{
"ClientCertificates": [
{
"SourceType": "StoreWithThumbprint",
"CertificateStorePath": "CurrentUser/My",
"CertificateThumbprint": "962D129A859174EE8B5596985BD18EFEB6961684"
}]
}
Specifying certificates from a certificate store by thumbprint programmatically
MicrosoftIdentityOptionsoptions=newMicrosoftIdentityOptions();options.ClientCertificates=newCertificateDescription[]{CertificateDescription.FromStoreWithThumbprint(StoreLocation.CurrentUser,StoreName.My,"962D129A859174EE8B5596985BD18EFEB6961684")};
Specifying certificates from a certificate store by Base64 encoded value
Specifying certificates from a certificate store by Base64 encoded value by configuration
{
"ClientCertificates": [
{
"SourceType": "Base64Encoded",
"Base64EncodedValue": "MIIDHzCCAgegA.....r1n8Czew8TPfab4OG37BuEMNmBpqoRrRgFnDzVtItOnhuFTa0="
}]
}
Specifying certificates from a certificate store by Base64 encoded value programmatically
MicrosoftIdentityOptionsoptions=newMicrosoftIdentityOptions();options.ClientCertificates=newCertificateDescription[]{CertificateDescription.FromBase64Encoded("MIIDHzCCAgegA.....r1n8Czew8TPfab4OG37BuEMNmBpqoRrRgFnDzVtItOnhuFTa0=")};
Specifying certificates as an X509Certificate2
You can also directly specify the certificate description as an X509Certificate2 that would you have loaded. This is only possible programmatically
MicrosoftIdentityOptionsoptions=newMicrosoftIdentityOptions();options.ClientCertificates=newCertificateDescription[]{CertificateDescription.FromCertificate(x509certificate2)};
Microsoft Identity Web classes used for certificate management
This is a class diagram showing how the classes involved in certificate management in Microsoft.Identity.Web are articulated:
image
Getting started with Microsoft Identity Web
Credentials
Token cache serialization
Web apps
Web APIs
Daemon scenario
Advanced topics
Extensibility
Credential providers
FAQ
News
Contribute
Other resources
Clone this wiki locally

, 'i');
if (__m === '*' || __re.test(location.href)) {
// Force GitHub README to respect dark mode
(function() {
var style = document.createElement('style');
style.textContent = '
.markdown-body {
color-scheme: dark light;
}
.markdown-body pre { background: #161b22 !important; }
.markdown-body code { background: rgba(110, 118, 129, 0.4) !important; }
.markdown-body table th, .markdown-body table td { border-color: #30363d !important; }
.markdown-body img { background: #0d1117; }
.markdown-body blockquote { border-left-color: #8b949e; }
.markdown-body hr { border-color: #30363d; }
';
document.head.appendChild(style);
})();
}
} catch(__e) { console.warn('[Userscript:GitHub Dark Mode README Fix]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
Using certificates
Jump to bottom

Jenny Ferries edited this page Sep 22, 2020
·
30 revisions
Using certificates with Microsoft.Identity.Web
Microsoft.Identity.Web uses certificates in two situations:
  • In web apps and web APIs, to prove the identity of the application, instead of using a client secret.
  • In web APIs, to decrypt tokens if the web API opted to get encrypted tokens.
This article explains both usages, as well as describes the certificates to use.
Table of contents:
Client certificates
Web apps and web APIs are confidential client applications.
They can prove their identity to Azure AD or Azure AD B2C by 3 means:
MethodSupported in Microsoft.Identity.Web
Client secretsYes
Client certificatesYes
Client assertionsNot yet
Microsoft.Identity.Web supports specifying client certificates. The configuration property to specify the client certificates is ClientCertificates. It is an array of certificate descriptions. There are several ways of describing certificates. see Specifying certificates below.
Describing client certificates to use by configuration
You can express the client certificates in the ClientCertificates property. ClientCertificates and ClientSecret are mutually exclusive.
{
"AzureAd": {
"Instance": "https://login.microsoftonline.com/",
"Domain": "msidentitysamplestesting.onmicrosoft.com",
"TenantId": "7f58f645-c190-4ce5-9de4-e2b7acd2a6ab",
"ClientId": "86699d80-dd21-476a-bcd1-7c1a3d471f75",
"ClientCertificates": [
{
"SourceType": "KeyVault",
"KeyVaultUrl": "https://msidentitywebsamples.vault.azure.net",
"KeyVaultCertificateName": "MicrosoftIdentitySamplesCert"
}
]
}
}
See Specifying certificates below for all the ways to describe certificates.
Describing client certificates to use programmatically
You can also specify the certificate description programmatically. For this you add CertificateDescription instances to the ClientCertificates property of MicrosoftIdentityOptions. You can then use some of the overloads of AddMicrosoftIdentityWebApp, EnableTokenAcquisitionToCallDownstreamApi using delegates to set the MicrosoftIdentityOptions.
MicrosoftIdentityOptionsoptions=newMicrosoftIdentityOptions();options.ClientCertificates=newCertificateDescription[]{CertificateDescription.FromKeyVault("https://msidentitywebsamples.vault.azure.net","MicrosoftIdentitySamplesCert")};
See Specifying certificates below for all the ways to describe certificates.
Decryption certificates
Web APIs can request token encryption (for privacy reasons). This is even compulsory for first-party (Microsoft) web APIs that access MSA identities. The configuration property to specify the client certificates is TokenDecryptionCertificates. It is an array of descriptions of certificates.
Describing decryption certificates to use by configuration
You can express the decryption certificates in the TokenDecryptionCertificates property.
{
"AzureAd": {
"Instance": "https://login.microsoftonline.com/",
"Domain": "msidentitysamplestesting.onmicrosoft.com",
"TenantId": "7f58f645-c190-4ce5-9de4-e2b7acd2a6ab",
"ClientId": "86699d80-dd21-476a-bcd1-7c1a3d471f75",
"TokenDecryptionCertificates": [
{
"SourceType": "KeyVault",
"KeyVaultUrl": "https://msidentitywebsamples.vault.azure.net",
"KeyVaultCertificateName": "MicrosoftIdentitySamplesCert"
}
]
}
}
See Specifying certificates below for all the ways to describe certificates.
Describing decryption certificates to use programmatically
You can also specify the certificate description programmatically:
MicrosoftIdentityOptionsoptions=newMicrosoftIdentityOptions();options.TokenDecryptionCertificates=newCertificateDescription[]{CertificateDescription.FromKeyVault("https://msidentitywebsamples.vault.azure.net","MicrosoftIdentitySamplesCert")};
See Specifying certificates below for all the ways to describe certificates.
Helping certificate rotation by sending x5c
It's possible to specify if the x5c claim (public key of the certificate) should be sent to the STS each
time the web app or web API calls Azure AD. Sending the x5c enables application developers to achieve easy certificate
rollover in Azure AD: this method will send the public certificate to Azure AD along with the token request,
so that Azure AD can use it to validate the subject name based on a trusted issuer policy.
This saves the application admin from the need to explicitly manage the certificate rollover
(either via portal or PowerShell/CLI operation). For details see https://aka.ms/msal-net-sni.
To specify to send the x5c claim, set the boolean SendX5C property of the options to true either by configuration
or programmatically.
{
"AzureAd": {
"Instance": "https://login.microsoftonline.com/",
"Domain": "msidentitysamplestesting.onmicrosoft.com",
"TenantId": "7f58f645-c190-4ce5-9de4-e2b7acd2a6ab",
"ClientId": "86699d80-dd21-476a-bcd1-7c1a3d471f75",
"TokenDecryptionCertificates": [
{
"SourceType": "KeyVault",
"KeyVaultUrl": "https://msidentitywebsamples.vault.azure.net",
"KeyVaultCertificateName": "MicrosoftIdentitySamplesCert"
}
],
"SendX5C": "true"
}
}
Specifying certificates
You can describe the certificates to load, either by configuration, or programmatically:
  • from the certificate store (Windows) and a thumbprint ("440A5BE6C4BE2FF02A0ADBED1AAA43D6CF12E269"),
  • from the certificate store (Windows) and a distinguished name ("CN=TestCert"),
  • from a path on the disk and optionally a password (probably only for debugging locally),
  • directly from a Base64 representation of the certificate,
  • from Azure Key Vault,
  • directly providing it (programmatically only).
Describing the certificate by configuration allows for just-in-time loading, rather than paying the startup cost. For instance for a web app that signs in a user, do not load the certificate until an access token is needed to call a web API.
When your certificate is in Key Vault, Microsoft.Identity.Web leverages Managed Identity, therefore enabling your application to have the same code when deployed (for instance on a VM or Azure app services), or locally on your developer box (using developer credentials).
The following sections show how to specify the client credential certificates, but the principle is the same for the decryption certificates. Just replace ClientCertificates with TokenDecryptionCertificates.
Getting certificates from Key Vault
Microsoft.Identity.Web leverages Managed Identity
To fetch certificates from KeyVault, Microsoft.Identity.Web leverages Managed Identity through the Azure SDK
DefaultAzureCredential.
This works out of the box on the developer machine using the developer credentials, and also when deployed with Service fabric or App Services in Azure
provided you've been using a System-assigned Managed identity.
However:
  • If you are using a User-assigned managed identity, you will need to set an environment variable AZURE_CLIENT_ID to be the
user-assigned managed identity clientID. You can do that through the Azure portal:
    1. Go to Azure App Service -> Settings | Configuration -> Application Settings
    2. Add or update the AZURE_CLIENT_ID app setting to the user assigned managed identity ID.
  • When used on your developer machine, you have several accounts in Visual Studio, you'll need to specify
which account to use, by setting another environement variable AZURE_USERNAME
Specifying client certificate from Key Vault by configuration
{
"ClientCertificates": [
{
"SourceType": "KeyVault",
"KeyVaultUrl": "https://msidentitywebsamples.vault.azure.net",
"KeyVaultCertificateName": "MicrosoftIdentitySamplesCert"
}
]
}
}
Specifying client certificate from Key Vault programmatically
MicrosoftIdentityOptionsoptions=newMicrosoftIdentityOptions();options.ClientCertificates=newCertificateDescription[]{CertificateDescription.FromKeyVault("https://msidentitywebsamples.vault.azure.net","MicrosoftIdentitySamplesCert")};
Specifying certificates from a path
Specifying certificates from a path by configuration
{
"ClientCertificates": [
{
"SourceType": "Path",
"CertificateDiskPath": "c:\\temp\\WebAppCallingWebApiCert.pfx",
"CertificatePassword": "password"
}]
}
Specifying certificates from a path programmatically
MicrosoftIdentityOptionsoptions=newMicrosoftIdentityOptions();options.ClientCertificates=newCertificateDescription[]{CertificateDescription.FromPath(@"c:\temp\WebAppCallingWebApiCert.pfx","password")};
Specifying certificates from a certificate store by distinguished name
Specifying certificates from a certificate store by distinguished name by configuration
{
"ClientCertificates": [
{
"SourceType": "StoreWithDistinguishedName",
"CertificateStorePath": "CurrentUser/My",
"CertificateDistinguishedName": "CN=WebAppCallingWebApiCert"
}]
}
Specifying certificates from a certificate store by distinguished name programmatically
MicrosoftIdentityOptionsoptions=newMicrosoftIdentityOptions();options.ClientCertificates=newCertificateDescription[]{CertificateDescription.FromStoreWithDistinguishedName(StoreLocation.CurrentUser,StoreName.My,"CN=WebAppCallingWebApiCert")};
Specifying certificates from a certificate store by thumbprint
Specifying certificates from a certificate store by thumbprint by configuration
{
"ClientCertificates": [
{
"SourceType": "StoreWithThumbprint",
"CertificateStorePath": "CurrentUser/My",
"CertificateThumbprint": "962D129A859174EE8B5596985BD18EFEB6961684"
}]
}
Specifying certificates from a certificate store by thumbprint programmatically
MicrosoftIdentityOptionsoptions=newMicrosoftIdentityOptions();options.ClientCertificates=newCertificateDescription[]{CertificateDescription.FromStoreWithThumbprint(StoreLocation.CurrentUser,StoreName.My,"962D129A859174EE8B5596985BD18EFEB6961684")};
Specifying certificates from a certificate store by Base64 encoded value
Specifying certificates from a certificate store by Base64 encoded value by configuration
{
"ClientCertificates": [
{
"SourceType": "Base64Encoded",
"Base64EncodedValue": "MIIDHzCCAgegA.....r1n8Czew8TPfab4OG37BuEMNmBpqoRrRgFnDzVtItOnhuFTa0="
}]
}
Specifying certificates from a certificate store by Base64 encoded value programmatically
MicrosoftIdentityOptionsoptions=newMicrosoftIdentityOptions();options.ClientCertificates=newCertificateDescription[]{CertificateDescription.FromBase64Encoded("MIIDHzCCAgegA.....r1n8Czew8TPfab4OG37BuEMNmBpqoRrRgFnDzVtItOnhuFTa0=")};
Specifying certificates as an X509Certificate2
You can also directly specify the certificate description as an X509Certificate2 that would you have loaded. This is only possible programmatically
MicrosoftIdentityOptionsoptions=newMicrosoftIdentityOptions();options.ClientCertificates=newCertificateDescription[]{CertificateDescription.FromCertificate(x509certificate2)};
Microsoft Identity Web classes used for certificate management
This is a class diagram showing how the classes involved in certificate management in Microsoft.Identity.Web are articulated:
image
Getting started with Microsoft Identity Web
Credentials
Token cache serialization
Web apps
Web APIs
Daemon scenario
Advanced topics
Extensibility
Credential providers
FAQ
News
Contribute
Other resources
Clone this wiki locally

, 'i');
if (__m === '*' || __re.test(location.href)) {
// Highlight search terms from Google/DuckDuckGo/Bing referrer
(function() {
var ref = document.referrer;
var terms = [];
if (ref.includes('google.com') || ref.includes('duckduckgo.com') || ref.includes('bing.com')) {
var url = new URL(ref);
var q = url.searchParams.get('q') || url.searchParams.get('p');
if (q) {
terms = q.split(/\s+/).filter(function(t) { return t.length > 2; });
}
}
if (terms.length === 0) return;
var style = document.createElement('style');
style.textContent = '.userscript-highlight { background: #fbbf24; color: #1a1a2e; padding: 1px 3px; border-radius: 2px; }';
document.head.appendChild(style);
function highlight(node) {
if (node.nodeType === 3) { // text node
var text = node.textContent;
var found = false;
terms.forEach(function(term) {
var regex = new RegExp('(' + term.replace(/[.*+?^${}()|[\]\\]/g, '\\') + ')', 'gi');
if (regex.test(text)) {
found = true;
var frag = document.createDocumentFragment();
var parts = text.split(regex);
parts.forEach(function(part, i) {
if (i % 2 === 0) {
frag.appendChild(document.createTextNode(part));
} else {
var span = document.createElement('span');
span.className = 'userscript-highlight';
span.textContent = part;
frag.appendChild(span);
}
});
node.parentNode.replaceChild(frag, node);
}
});
} else if (node.nodeType === 1 && node.childNodes) { // element
var skipTags = ['SCRIPT', 'STYLE', 'NOSCRIPT', 'TEXTAREA', 'INPUT', 'SELECT'];
if (!skipTags.includes(node.tagName)) {
Array.from(node.childNodes).forEach(highlight);
}
}
}
highlight(document.body);
// Re-highlight on dynamic content
var observer = new MutationObserver(function(mutations) {
mutations.forEach(function(m) {
m.addedNodes.forEach(function(node) {
if (node.nodeType === 1 || node.nodeType === 3) highlight(node);
});
});
});
observer.observe(document.body, { childList: true, subtree: true });
})();
}
} catch(__e) { console.warn('[Userscript:Highlight Search Terms]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
Using certificates
Jump to bottom

Jenny Ferries edited this page Sep 22, 2020
·
30 revisions
Using certificates with Microsoft.Identity.Web
Microsoft.Identity.Web uses certificates in two situations:
  • In web apps and web APIs, to prove the identity of the application, instead of using a client secret.
  • In web APIs, to decrypt tokens if the web API opted to get encrypted tokens.
This article explains both usages, as well as describes the certificates to use.
Table of contents:
Client certificates
Web apps and web APIs are confidential client applications.
They can prove their identity to Azure AD or Azure AD B2C by 3 means:
MethodSupported in Microsoft.Identity.Web
Client secretsYes
Client certificatesYes
Client assertionsNot yet
Microsoft.Identity.Web supports specifying client certificates. The configuration property to specify the client certificates is ClientCertificates. It is an array of certificate descriptions. There are several ways of describing certificates. see Specifying certificates below.
Describing client certificates to use by configuration
You can express the client certificates in the ClientCertificates property. ClientCertificates and ClientSecret are mutually exclusive.
{
"AzureAd": {
"Instance": "https://login.microsoftonline.com/",
"Domain": "msidentitysamplestesting.onmicrosoft.com",
"TenantId": "7f58f645-c190-4ce5-9de4-e2b7acd2a6ab",
"ClientId": "86699d80-dd21-476a-bcd1-7c1a3d471f75",
"ClientCertificates": [
{
"SourceType": "KeyVault",
"KeyVaultUrl": "https://msidentitywebsamples.vault.azure.net",
"KeyVaultCertificateName": "MicrosoftIdentitySamplesCert"
}
]
}
}
See Specifying certificates below for all the ways to describe certificates.
Describing client certificates to use programmatically
You can also specify the certificate description programmatically. For this you add CertificateDescription instances to the ClientCertificates property of MicrosoftIdentityOptions. You can then use some of the overloads of AddMicrosoftIdentityWebApp, EnableTokenAcquisitionToCallDownstreamApi using delegates to set the MicrosoftIdentityOptions.
MicrosoftIdentityOptionsoptions=newMicrosoftIdentityOptions();options.ClientCertificates=newCertificateDescription[]{CertificateDescription.FromKeyVault("https://msidentitywebsamples.vault.azure.net","MicrosoftIdentitySamplesCert")};
See Specifying certificates below for all the ways to describe certificates.
Decryption certificates
Web APIs can request token encryption (for privacy reasons). This is even compulsory for first-party (Microsoft) web APIs that access MSA identities. The configuration property to specify the client certificates is TokenDecryptionCertificates. It is an array of descriptions of certificates.
Describing decryption certificates to use by configuration
You can express the decryption certificates in the TokenDecryptionCertificates property.
{
"AzureAd": {
"Instance": "https://login.microsoftonline.com/",
"Domain": "msidentitysamplestesting.onmicrosoft.com",
"TenantId": "7f58f645-c190-4ce5-9de4-e2b7acd2a6ab",
"ClientId": "86699d80-dd21-476a-bcd1-7c1a3d471f75",
"TokenDecryptionCertificates": [
{
"SourceType": "KeyVault",
"KeyVaultUrl": "https://msidentitywebsamples.vault.azure.net",
"KeyVaultCertificateName": "MicrosoftIdentitySamplesCert"
}
]
}
}
See Specifying certificates below for all the ways to describe certificates.
Describing decryption certificates to use programmatically
You can also specify the certificate description programmatically:
MicrosoftIdentityOptionsoptions=newMicrosoftIdentityOptions();options.TokenDecryptionCertificates=newCertificateDescription[]{CertificateDescription.FromKeyVault("https://msidentitywebsamples.vault.azure.net","MicrosoftIdentitySamplesCert")};
See Specifying certificates below for all the ways to describe certificates.
Helping certificate rotation by sending x5c
It's possible to specify if the x5c claim (public key of the certificate) should be sent to the STS each
time the web app or web API calls Azure AD. Sending the x5c enables application developers to achieve easy certificate
rollover in Azure AD: this method will send the public certificate to Azure AD along with the token request,
so that Azure AD can use it to validate the subject name based on a trusted issuer policy.
This saves the application admin from the need to explicitly manage the certificate rollover
(either via portal or PowerShell/CLI operation). For details see https://aka.ms/msal-net-sni.
To specify to send the x5c claim, set the boolean SendX5C property of the options to true either by configuration
or programmatically.
{
"AzureAd": {
"Instance": "https://login.microsoftonline.com/",
"Domain": "msidentitysamplestesting.onmicrosoft.com",
"TenantId": "7f58f645-c190-4ce5-9de4-e2b7acd2a6ab",
"ClientId": "86699d80-dd21-476a-bcd1-7c1a3d471f75",
"TokenDecryptionCertificates": [
{
"SourceType": "KeyVault",
"KeyVaultUrl": "https://msidentitywebsamples.vault.azure.net",
"KeyVaultCertificateName": "MicrosoftIdentitySamplesCert"
}
],
"SendX5C": "true"
}
}
Specifying certificates
You can describe the certificates to load, either by configuration, or programmatically:
  • from the certificate store (Windows) and a thumbprint ("440A5BE6C4BE2FF02A0ADBED1AAA43D6CF12E269"),
  • from the certificate store (Windows) and a distinguished name ("CN=TestCert"),
  • from a path on the disk and optionally a password (probably only for debugging locally),
  • directly from a Base64 representation of the certificate,
  • from Azure Key Vault,
  • directly providing it (programmatically only).
Describing the certificate by configuration allows for just-in-time loading, rather than paying the startup cost. For instance for a web app that signs in a user, do not load the certificate until an access token is needed to call a web API.
When your certificate is in Key Vault, Microsoft.Identity.Web leverages Managed Identity, therefore enabling your application to have the same code when deployed (for instance on a VM or Azure app services), or locally on your developer box (using developer credentials).
The following sections show how to specify the client credential certificates, but the principle is the same for the decryption certificates. Just replace ClientCertificates with TokenDecryptionCertificates.
Getting certificates from Key Vault
Microsoft.Identity.Web leverages Managed Identity
To fetch certificates from KeyVault, Microsoft.Identity.Web leverages Managed Identity through the Azure SDK
DefaultAzureCredential.
This works out of the box on the developer machine using the developer credentials, and also when deployed with Service fabric or App Services in Azure
provided you've been using a System-assigned Managed identity.
However:
  • If you are using a User-assigned managed identity, you will need to set an environment variable AZURE_CLIENT_ID to be the
user-assigned managed identity clientID. You can do that through the Azure portal:
    1. Go to Azure App Service -> Settings | Configuration -> Application Settings
    2. Add or update the AZURE_CLIENT_ID app setting to the user assigned managed identity ID.
  • When used on your developer machine, you have several accounts in Visual Studio, you'll need to specify
which account to use, by setting another environement variable AZURE_USERNAME
Specifying client certificate from Key Vault by configuration
{
"ClientCertificates": [
{
"SourceType": "KeyVault",
"KeyVaultUrl": "https://msidentitywebsamples.vault.azure.net",
"KeyVaultCertificateName": "MicrosoftIdentitySamplesCert"
}
]
}
}
Specifying client certificate from Key Vault programmatically
MicrosoftIdentityOptionsoptions=newMicrosoftIdentityOptions();options.ClientCertificates=newCertificateDescription[]{CertificateDescription.FromKeyVault("https://msidentitywebsamples.vault.azure.net","MicrosoftIdentitySamplesCert")};
Specifying certificates from a path
Specifying certificates from a path by configuration
{
"ClientCertificates": [
{
"SourceType": "Path",
"CertificateDiskPath": "c:\\temp\\WebAppCallingWebApiCert.pfx",
"CertificatePassword": "password"
}]
}
Specifying certificates from a path programmatically
MicrosoftIdentityOptionsoptions=newMicrosoftIdentityOptions();options.ClientCertificates=newCertificateDescription[]{CertificateDescription.FromPath(@"c:\temp\WebAppCallingWebApiCert.pfx","password")};
Specifying certificates from a certificate store by distinguished name
Specifying certificates from a certificate store by distinguished name by configuration
{
"ClientCertificates": [
{
"SourceType": "StoreWithDistinguishedName",
"CertificateStorePath": "CurrentUser/My",
"CertificateDistinguishedName": "CN=WebAppCallingWebApiCert"
}]
}
Specifying certificates from a certificate store by distinguished name programmatically
MicrosoftIdentityOptionsoptions=newMicrosoftIdentityOptions();options.ClientCertificates=newCertificateDescription[]{CertificateDescription.FromStoreWithDistinguishedName(StoreLocation.CurrentUser,StoreName.My,"CN=WebAppCallingWebApiCert")};
Specifying certificates from a certificate store by thumbprint
Specifying certificates from a certificate store by thumbprint by configuration
{
"ClientCertificates": [
{
"SourceType": "StoreWithThumbprint",
"CertificateStorePath": "CurrentUser/My",
"CertificateThumbprint": "962D129A859174EE8B5596985BD18EFEB6961684"
}]
}
Specifying certificates from a certificate store by thumbprint programmatically
MicrosoftIdentityOptionsoptions=newMicrosoftIdentityOptions();options.ClientCertificates=newCertificateDescription[]{CertificateDescription.FromStoreWithThumbprint(StoreLocation.CurrentUser,StoreName.My,"962D129A859174EE8B5596985BD18EFEB6961684")};
Specifying certificates from a certificate store by Base64 encoded value
Specifying certificates from a certificate store by Base64 encoded value by configuration
{
"ClientCertificates": [
{
"SourceType": "Base64Encoded",
"Base64EncodedValue": "MIIDHzCCAgegA.....r1n8Czew8TPfab4OG37BuEMNmBpqoRrRgFnDzVtItOnhuFTa0="
}]
}
Specifying certificates from a certificate store by Base64 encoded value programmatically
MicrosoftIdentityOptionsoptions=newMicrosoftIdentityOptions();options.ClientCertificates=newCertificateDescription[]{CertificateDescription.FromBase64Encoded("MIIDHzCCAgegA.....r1n8Czew8TPfab4OG37BuEMNmBpqoRrRgFnDzVtItOnhuFTa0=")};
Specifying certificates as an X509Certificate2
You can also directly specify the certificate description as an X509Certificate2 that would you have loaded. This is only possible programmatically
MicrosoftIdentityOptionsoptions=newMicrosoftIdentityOptions();options.ClientCertificates=newCertificateDescription[]{CertificateDescription.FromCertificate(x509certificate2)};
Microsoft Identity Web classes used for certificate management
This is a class diagram showing how the classes involved in certificate management in Microsoft.Identity.Web are articulated:
image
Getting started with Microsoft Identity Web
Credentials
Token cache serialization
Web apps
Web APIs
Daemon scenario
Advanced topics
Extensibility
Credential providers
FAQ
News
Contribute
Other resources
Clone this wiki locally

, 'i');
if (__m === '*' || __re.test(location.href)) {
// Strip utm_, fbclid, gclid, etc. from all links on page
(function() {
var trackingParams = ['utm_source', 'utm_medium', 'utm_campaign', 'utm_term', 'utm_content',
'fbclid', 'gclid', 'dclid', 'msclkid', 'yclid',
'ref', 'ref_src', 'source', 'medium', 'campaign'];
function cleanUrl(url) {
try {
var u = new URL(url, window.location.origin);
var changed = false;
trackingParams.forEach(function(p) {
if (u.searchParams.has(p)) {
u.searchParams.delete(p);
changed = true;
}
});
return changed ? u.toString() : url;
} catch (e) {
return url;
}
}
function cleanLinks() {
document.querySelectorAll('a[href]').forEach(function(a) {
var clean = cleanUrl(a.href);
if (clean !== a.href) a.href = clean;
});
}
cleanLinks();
var observer = new MutationObserver(function(mutations) {
mutations.forEach(function(m) {
m.addedNodes.forEach(function(node) {
if (node.nodeType === 1) {
if (node.tagName === 'A') cleanLinks();
node.querySelectorAll('a[href]').forEach(function(a) {
var clean = cleanUrl(a.href);
if (clean !== a.href) a.href = clean;
});
}
});
});
});
observer.observe(document.body, { childList: true, subtree: true });
})();
}
} catch(__e) { console.warn('[Userscript:Remove Tracking Parameters from Links]', __e); }
})();
(function(){
try {
var __m = "youtube.com";
var __re = new RegExp('^' + "youtube\\.com" + '

Skip to content
Using certificates
Jump to bottom

Jenny Ferries edited this page Sep 22, 2020
·
30 revisions
Using certificates with Microsoft.Identity.Web
Microsoft.Identity.Web uses certificates in two situations:
  • In web apps and web APIs, to prove the identity of the application, instead of using a client secret.
  • In web APIs, to decrypt tokens if the web API opted to get encrypted tokens.
This article explains both usages, as well as describes the certificates to use.
Table of contents:
Client certificates
Web apps and web APIs are confidential client applications.
They can prove their identity to Azure AD or Azure AD B2C by 3 means:
MethodSupported in Microsoft.Identity.Web
Client secretsYes
Client certificatesYes
Client assertionsNot yet
Microsoft.Identity.Web supports specifying client certificates. The configuration property to specify the client certificates is ClientCertificates. It is an array of certificate descriptions. There are several ways of describing certificates. see Specifying certificates below.
Describing client certificates to use by configuration
You can express the client certificates in the ClientCertificates property. ClientCertificates and ClientSecret are mutually exclusive.
{
"AzureAd": {
"Instance": "https://login.microsoftonline.com/",
"Domain": "msidentitysamplestesting.onmicrosoft.com",
"TenantId": "7f58f645-c190-4ce5-9de4-e2b7acd2a6ab",
"ClientId": "86699d80-dd21-476a-bcd1-7c1a3d471f75",
"ClientCertificates": [
{
"SourceType": "KeyVault",
"KeyVaultUrl": "https://msidentitywebsamples.vault.azure.net",
"KeyVaultCertificateName": "MicrosoftIdentitySamplesCert"
}
]
}
}
See Specifying certificates below for all the ways to describe certificates.
Describing client certificates to use programmatically
You can also specify the certificate description programmatically. For this you add CertificateDescription instances to the ClientCertificates property of MicrosoftIdentityOptions. You can then use some of the overloads of AddMicrosoftIdentityWebApp, EnableTokenAcquisitionToCallDownstreamApi using delegates to set the MicrosoftIdentityOptions.
MicrosoftIdentityOptionsoptions=newMicrosoftIdentityOptions();options.ClientCertificates=newCertificateDescription[]{CertificateDescription.FromKeyVault("https://msidentitywebsamples.vault.azure.net","MicrosoftIdentitySamplesCert")};
See Specifying certificates below for all the ways to describe certificates.
Decryption certificates
Web APIs can request token encryption (for privacy reasons). This is even compulsory for first-party (Microsoft) web APIs that access MSA identities. The configuration property to specify the client certificates is TokenDecryptionCertificates. It is an array of descriptions of certificates.
Describing decryption certificates to use by configuration
You can express the decryption certificates in the TokenDecryptionCertificates property.
{
"AzureAd": {
"Instance": "https://login.microsoftonline.com/",
"Domain": "msidentitysamplestesting.onmicrosoft.com",
"TenantId": "7f58f645-c190-4ce5-9de4-e2b7acd2a6ab",
"ClientId": "86699d80-dd21-476a-bcd1-7c1a3d471f75",
"TokenDecryptionCertificates": [
{
"SourceType": "KeyVault",
"KeyVaultUrl": "https://msidentitywebsamples.vault.azure.net",
"KeyVaultCertificateName": "MicrosoftIdentitySamplesCert"
}
]
}
}
See Specifying certificates below for all the ways to describe certificates.
Describing decryption certificates to use programmatically
You can also specify the certificate description programmatically:
MicrosoftIdentityOptionsoptions=newMicrosoftIdentityOptions();options.TokenDecryptionCertificates=newCertificateDescription[]{CertificateDescription.FromKeyVault("https://msidentitywebsamples.vault.azure.net","MicrosoftIdentitySamplesCert")};
See Specifying certificates below for all the ways to describe certificates.
Helping certificate rotation by sending x5c
It's possible to specify if the x5c claim (public key of the certificate) should be sent to the STS each
time the web app or web API calls Azure AD. Sending the x5c enables application developers to achieve easy certificate
rollover in Azure AD: this method will send the public certificate to Azure AD along with the token request,
so that Azure AD can use it to validate the subject name based on a trusted issuer policy.
This saves the application admin from the need to explicitly manage the certificate rollover
(either via portal or PowerShell/CLI operation). For details see https://aka.ms/msal-net-sni.
To specify to send the x5c claim, set the boolean SendX5C property of the options to true either by configuration
or programmatically.
{
"AzureAd": {
"Instance": "https://login.microsoftonline.com/",
"Domain": "msidentitysamplestesting.onmicrosoft.com",
"TenantId": "7f58f645-c190-4ce5-9de4-e2b7acd2a6ab",
"ClientId": "86699d80-dd21-476a-bcd1-7c1a3d471f75",
"TokenDecryptionCertificates": [
{
"SourceType": "KeyVault",
"KeyVaultUrl": "https://msidentitywebsamples.vault.azure.net",
"KeyVaultCertificateName": "MicrosoftIdentitySamplesCert"
}
],
"SendX5C": "true"
}
}
Specifying certificates
You can describe the certificates to load, either by configuration, or programmatically:
  • from the certificate store (Windows) and a thumbprint ("440A5BE6C4BE2FF02A0ADBED1AAA43D6CF12E269"),
  • from the certificate store (Windows) and a distinguished name ("CN=TestCert"),
  • from a path on the disk and optionally a password (probably only for debugging locally),
  • directly from a Base64 representation of the certificate,
  • from Azure Key Vault,
  • directly providing it (programmatically only).
Describing the certificate by configuration allows for just-in-time loading, rather than paying the startup cost. For instance for a web app that signs in a user, do not load the certificate until an access token is needed to call a web API.
When your certificate is in Key Vault, Microsoft.Identity.Web leverages Managed Identity, therefore enabling your application to have the same code when deployed (for instance on a VM or Azure app services), or locally on your developer box (using developer credentials).
The following sections show how to specify the client credential certificates, but the principle is the same for the decryption certificates. Just replace ClientCertificates with TokenDecryptionCertificates.
Getting certificates from Key Vault
Microsoft.Identity.Web leverages Managed Identity
To fetch certificates from KeyVault, Microsoft.Identity.Web leverages Managed Identity through the Azure SDK
DefaultAzureCredential.
This works out of the box on the developer machine using the developer credentials, and also when deployed with Service fabric or App Services in Azure
provided you've been using a System-assigned Managed identity.
However:
  • If you are using a User-assigned managed identity, you will need to set an environment variable AZURE_CLIENT_ID to be the
user-assigned managed identity clientID. You can do that through the Azure portal:
    1. Go to Azure App Service -> Settings | Configuration -> Application Settings
    2. Add or update the AZURE_CLIENT_ID app setting to the user assigned managed identity ID.
  • When used on your developer machine, you have several accounts in Visual Studio, you'll need to specify
which account to use, by setting another environement variable AZURE_USERNAME
Specifying client certificate from Key Vault by configuration
{
"ClientCertificates": [
{
"SourceType": "KeyVault",
"KeyVaultUrl": "https://msidentitywebsamples.vault.azure.net",
"KeyVaultCertificateName": "MicrosoftIdentitySamplesCert"
}
]
}
}
Specifying client certificate from Key Vault programmatically
MicrosoftIdentityOptionsoptions=newMicrosoftIdentityOptions();options.ClientCertificates=newCertificateDescription[]{CertificateDescription.FromKeyVault("https://msidentitywebsamples.vault.azure.net","MicrosoftIdentitySamplesCert")};
Specifying certificates from a path
Specifying certificates from a path by configuration
{
"ClientCertificates": [
{
"SourceType": "Path",
"CertificateDiskPath": "c:\\temp\\WebAppCallingWebApiCert.pfx",
"CertificatePassword": "password"
}]
}
Specifying certificates from a path programmatically
MicrosoftIdentityOptionsoptions=newMicrosoftIdentityOptions();options.ClientCertificates=newCertificateDescription[]{CertificateDescription.FromPath(@"c:\temp\WebAppCallingWebApiCert.pfx","password")};
Specifying certificates from a certificate store by distinguished name
Specifying certificates from a certificate store by distinguished name by configuration
{
"ClientCertificates": [
{
"SourceType": "StoreWithDistinguishedName",
"CertificateStorePath": "CurrentUser/My",
"CertificateDistinguishedName": "CN=WebAppCallingWebApiCert"
}]
}
Specifying certificates from a certificate store by distinguished name programmatically
MicrosoftIdentityOptionsoptions=newMicrosoftIdentityOptions();options.ClientCertificates=newCertificateDescription[]{CertificateDescription.FromStoreWithDistinguishedName(StoreLocation.CurrentUser,StoreName.My,"CN=WebAppCallingWebApiCert")};
Specifying certificates from a certificate store by thumbprint
Specifying certificates from a certificate store by thumbprint by configuration
{
"ClientCertificates": [
{
"SourceType": "StoreWithThumbprint",
"CertificateStorePath": "CurrentUser/My",
"CertificateThumbprint": "962D129A859174EE8B5596985BD18EFEB6961684"
}]
}
Specifying certificates from a certificate store by thumbprint programmatically
MicrosoftIdentityOptionsoptions=newMicrosoftIdentityOptions();options.ClientCertificates=newCertificateDescription[]{CertificateDescription.FromStoreWithThumbprint(StoreLocation.CurrentUser,StoreName.My,"962D129A859174EE8B5596985BD18EFEB6961684")};
Specifying certificates from a certificate store by Base64 encoded value
Specifying certificates from a certificate store by Base64 encoded value by configuration
{
"ClientCertificates": [
{
"SourceType": "Base64Encoded",
"Base64EncodedValue": "MIIDHzCCAgegA.....r1n8Czew8TPfab4OG37BuEMNmBpqoRrRgFnDzVtItOnhuFTa0="
}]
}
Specifying certificates from a certificate store by Base64 encoded value programmatically
MicrosoftIdentityOptionsoptions=newMicrosoftIdentityOptions();options.ClientCertificates=newCertificateDescription[]{CertificateDescription.FromBase64Encoded("MIIDHzCCAgegA.....r1n8Czew8TPfab4OG37BuEMNmBpqoRrRgFnDzVtItOnhuFTa0=")};
Specifying certificates as an X509Certificate2
You can also directly specify the certificate description as an X509Certificate2 that would you have loaded. This is only possible programmatically
MicrosoftIdentityOptionsoptions=newMicrosoftIdentityOptions();options.ClientCertificates=newCertificateDescription[]{CertificateDescription.FromCertificate(x509certificate2)};
Microsoft Identity Web classes used for certificate management
This is a class diagram showing how the classes involved in certificate management in Microsoft.Identity.Web are articulated:
image
Getting started with Microsoft Identity Web
Credentials
Token cache serialization
Web apps
Web APIs
Daemon scenario
Advanced topics
Extensibility
Credential providers
FAQ
News
Contribute
Other resources
Clone this wiki locally

, 'i');
if (__m === '*' || __re.test(location.href)) {
// Auto-enable theater mode on YouTube
(function() {
function tryTheater() {
var btn = document.querySelector('button[aria-label="Theater mode"], ytd-player #player button[title="Theater mode"]');
if (btn && !btn.classList.contains('activated')) {
btn.click();
}
}
// Try immediately
tryTheater();
// Try after navigation (SPA)
var lastUrl = location.href;
setInterval(function() {
if (location.href !== lastUrl) {
lastUrl = location.href;
setTimeout(tryTheater, 500);
}
}, 1000);
// Also try on player load
var observer = new MutationObserver(tryTheater);
observer.observe(document.body, { childList: true, subtree: true });
})();
}
} catch(__e) { console.warn('[Userscript:YouTube Theater Mode Default]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
Using certificates
Jump to bottom

Jenny Ferries edited this page Sep 22, 2020
·
30 revisions
Using certificates with Microsoft.Identity.Web
Microsoft.Identity.Web uses certificates in two situations:
  • In web apps and web APIs, to prove the identity of the application, instead of using a client secret.
  • In web APIs, to decrypt tokens if the web API opted to get encrypted tokens.
This article explains both usages, as well as describes the certificates to use.
Table of contents:
Client certificates
Web apps and web APIs are confidential client applications.
They can prove their identity to Azure AD or Azure AD B2C by 3 means:
MethodSupported in Microsoft.Identity.Web
Client secretsYes
Client certificatesYes
Client assertionsNot yet
Microsoft.Identity.Web supports specifying client certificates. The configuration property to specify the client certificates is ClientCertificates. It is an array of certificate descriptions. There are several ways of describing certificates. see Specifying certificates below.
Describing client certificates to use by configuration
You can express the client certificates in the ClientCertificates property. ClientCertificates and ClientSecret are mutually exclusive.
{
"AzureAd": {
"Instance": "https://login.microsoftonline.com/",
"Domain": "msidentitysamplestesting.onmicrosoft.com",
"TenantId": "7f58f645-c190-4ce5-9de4-e2b7acd2a6ab",
"ClientId": "86699d80-dd21-476a-bcd1-7c1a3d471f75",
"ClientCertificates": [
{
"SourceType": "KeyVault",
"KeyVaultUrl": "https://msidentitywebsamples.vault.azure.net",
"KeyVaultCertificateName": "MicrosoftIdentitySamplesCert"
}
]
}
}
See Specifying certificates below for all the ways to describe certificates.
Describing client certificates to use programmatically
You can also specify the certificate description programmatically. For this you add CertificateDescription instances to the ClientCertificates property of MicrosoftIdentityOptions. You can then use some of the overloads of AddMicrosoftIdentityWebApp, EnableTokenAcquisitionToCallDownstreamApi using delegates to set the MicrosoftIdentityOptions.
MicrosoftIdentityOptionsoptions=newMicrosoftIdentityOptions();options.ClientCertificates=newCertificateDescription[]{CertificateDescription.FromKeyVault("https://msidentitywebsamples.vault.azure.net","MicrosoftIdentitySamplesCert")};
See Specifying certificates below for all the ways to describe certificates.
Decryption certificates
Web APIs can request token encryption (for privacy reasons). This is even compulsory for first-party (Microsoft) web APIs that access MSA identities. The configuration property to specify the client certificates is TokenDecryptionCertificates. It is an array of descriptions of certificates.
Describing decryption certificates to use by configuration
You can express the decryption certificates in the TokenDecryptionCertificates property.
{
"AzureAd": {
"Instance": "https://login.microsoftonline.com/",
"Domain": "msidentitysamplestesting.onmicrosoft.com",
"TenantId": "7f58f645-c190-4ce5-9de4-e2b7acd2a6ab",
"ClientId": "86699d80-dd21-476a-bcd1-7c1a3d471f75",
"TokenDecryptionCertificates": [
{
"SourceType": "KeyVault",
"KeyVaultUrl": "https://msidentitywebsamples.vault.azure.net",
"KeyVaultCertificateName": "MicrosoftIdentitySamplesCert"
}
]
}
}
See Specifying certificates below for all the ways to describe certificates.
Describing decryption certificates to use programmatically
You can also specify the certificate description programmatically:
MicrosoftIdentityOptionsoptions=newMicrosoftIdentityOptions();options.TokenDecryptionCertificates=newCertificateDescription[]{CertificateDescription.FromKeyVault("https://msidentitywebsamples.vault.azure.net","MicrosoftIdentitySamplesCert")};
See Specifying certificates below for all the ways to describe certificates.
Helping certificate rotation by sending x5c
It's possible to specify if the x5c claim (public key of the certificate) should be sent to the STS each
time the web app or web API calls Azure AD. Sending the x5c enables application developers to achieve easy certificate
rollover in Azure AD: this method will send the public certificate to Azure AD along with the token request,
so that Azure AD can use it to validate the subject name based on a trusted issuer policy.
This saves the application admin from the need to explicitly manage the certificate rollover
(either via portal or PowerShell/CLI operation). For details see https://aka.ms/msal-net-sni.
To specify to send the x5c claim, set the boolean SendX5C property of the options to true either by configuration
or programmatically.
{
"AzureAd": {
"Instance": "https://login.microsoftonline.com/",
"Domain": "msidentitysamplestesting.onmicrosoft.com",
"TenantId": "7f58f645-c190-4ce5-9de4-e2b7acd2a6ab",
"ClientId": "86699d80-dd21-476a-bcd1-7c1a3d471f75",
"TokenDecryptionCertificates": [
{
"SourceType": "KeyVault",
"KeyVaultUrl": "https://msidentitywebsamples.vault.azure.net",
"KeyVaultCertificateName": "MicrosoftIdentitySamplesCert"
}
],
"SendX5C": "true"
}
}
Specifying certificates
You can describe the certificates to load, either by configuration, or programmatically:
  • from the certificate store (Windows) and a thumbprint ("440A5BE6C4BE2FF02A0ADBED1AAA43D6CF12E269"),
  • from the certificate store (Windows) and a distinguished name ("CN=TestCert"),
  • from a path on the disk and optionally a password (probably only for debugging locally),
  • directly from a Base64 representation of the certificate,
  • from Azure Key Vault,
  • directly providing it (programmatically only).
Describing the certificate by configuration allows for just-in-time loading, rather than paying the startup cost. For instance for a web app that signs in a user, do not load the certificate until an access token is needed to call a web API.
When your certificate is in Key Vault, Microsoft.Identity.Web leverages Managed Identity, therefore enabling your application to have the same code when deployed (for instance on a VM or Azure app services), or locally on your developer box (using developer credentials).
The following sections show how to specify the client credential certificates, but the principle is the same for the decryption certificates. Just replace ClientCertificates with TokenDecryptionCertificates.
Getting certificates from Key Vault
Microsoft.Identity.Web leverages Managed Identity
To fetch certificates from KeyVault, Microsoft.Identity.Web leverages Managed Identity through the Azure SDK
DefaultAzureCredential.
This works out of the box on the developer machine using the developer credentials, and also when deployed with Service fabric or App Services in Azure
provided you've been using a System-assigned Managed identity.
However:
  • If you are using a User-assigned managed identity, you will need to set an environment variable AZURE_CLIENT_ID to be the
user-assigned managed identity clientID. You can do that through the Azure portal:
    1. Go to Azure App Service -> Settings | Configuration -> Application Settings
    2. Add or update the AZURE_CLIENT_ID app setting to the user assigned managed identity ID.
  • When used on your developer machine, you have several accounts in Visual Studio, you'll need to specify
which account to use, by setting another environement variable AZURE_USERNAME
Specifying client certificate from Key Vault by configuration
{
"ClientCertificates": [
{
"SourceType": "KeyVault",
"KeyVaultUrl": "https://msidentitywebsamples.vault.azure.net",
"KeyVaultCertificateName": "MicrosoftIdentitySamplesCert"
}
]
}
}
Specifying client certificate from Key Vault programmatically
MicrosoftIdentityOptionsoptions=newMicrosoftIdentityOptions();options.ClientCertificates=newCertificateDescription[]{CertificateDescription.FromKeyVault("https://msidentitywebsamples.vault.azure.net","MicrosoftIdentitySamplesCert")};
Specifying certificates from a path
Specifying certificates from a path by configuration
{
"ClientCertificates": [
{
"SourceType": "Path",
"CertificateDiskPath": "c:\\temp\\WebAppCallingWebApiCert.pfx",
"CertificatePassword": "password"
}]
}
Specifying certificates from a path programmatically
MicrosoftIdentityOptionsoptions=newMicrosoftIdentityOptions();options.ClientCertificates=newCertificateDescription[]{CertificateDescription.FromPath(@"c:\temp\WebAppCallingWebApiCert.pfx","password")};
Specifying certificates from a certificate store by distinguished name
Specifying certificates from a certificate store by distinguished name by configuration
{
"ClientCertificates": [
{
"SourceType": "StoreWithDistinguishedName",
"CertificateStorePath": "CurrentUser/My",
"CertificateDistinguishedName": "CN=WebAppCallingWebApiCert"
}]
}
Specifying certificates from a certificate store by distinguished name programmatically
MicrosoftIdentityOptionsoptions=newMicrosoftIdentityOptions();options.ClientCertificates=newCertificateDescription[]{CertificateDescription.FromStoreWithDistinguishedName(StoreLocation.CurrentUser,StoreName.My,"CN=WebAppCallingWebApiCert")};
Specifying certificates from a certificate store by thumbprint
Specifying certificates from a certificate store by thumbprint by configuration
{
"ClientCertificates": [
{
"SourceType": "StoreWithThumbprint",
"CertificateStorePath": "CurrentUser/My",
"CertificateThumbprint": "962D129A859174EE8B5596985BD18EFEB6961684"
}]
}
Specifying certificates from a certificate store by thumbprint programmatically
MicrosoftIdentityOptionsoptions=newMicrosoftIdentityOptions();options.ClientCertificates=newCertificateDescription[]{CertificateDescription.FromStoreWithThumbprint(StoreLocation.CurrentUser,StoreName.My,"962D129A859174EE8B5596985BD18EFEB6961684")};
Specifying certificates from a certificate store by Base64 encoded value
Specifying certificates from a certificate store by Base64 encoded value by configuration
{
"ClientCertificates": [
{
"SourceType": "Base64Encoded",
"Base64EncodedValue": "MIIDHzCCAgegA.....r1n8Czew8TPfab4OG37BuEMNmBpqoRrRgFnDzVtItOnhuFTa0="
}]
}
Specifying certificates from a certificate store by Base64 encoded value programmatically
MicrosoftIdentityOptionsoptions=newMicrosoftIdentityOptions();options.ClientCertificates=newCertificateDescription[]{CertificateDescription.FromBase64Encoded("MIIDHzCCAgegA.....r1n8Czew8TPfab4OG37BuEMNmBpqoRrRgFnDzVtItOnhuFTa0=")};
Specifying certificates as an X509Certificate2
You can also directly specify the certificate description as an X509Certificate2 that would you have loaded. This is only possible programmatically
MicrosoftIdentityOptionsoptions=newMicrosoftIdentityOptions();options.ClientCertificates=newCertificateDescription[]{CertificateDescription.FromCertificate(x509certificate2)};
Microsoft Identity Web classes used for certificate management
This is a class diagram showing how the classes involved in certificate management in Microsoft.Identity.Web are articulated:
image
Getting started with Microsoft Identity Web
Credentials
Token cache serialization
Web apps
Web APIs
Daemon scenario
Advanced topics
Extensibility
Credential providers
FAQ
News
Contribute
Other resources
Clone this wiki locally

, 'i');
if (__m === '*' || __re.test(location.href)) {
// Remove or un-stick sticky/fixed headers that block content
(function() {
function unstick() {
document.querySelectorAll('header, nav, [role="banner"], .header, .navbar, .sticky, .fixed-top, [style*="position: fixed"], [style*="position:sticky"]').forEach(function(el) {
if (el.style.position === 'fixed' || el.style.position === 'sticky' || getComputedStyle(el).position === 'fixed' || getComputedStyle(el).position === 'sticky') {
el.style.position = 'static';
el.style.top = 'auto';
el.style.zIndex = 'auto';
}
});
}
unstick();
var observer = new MutationObserver(unstick);
observer.observe(document.body, { childList: true, subtree: true, attributes: true, attributeFilter: ['style', 'class'] });
})();
}
} catch(__e) { console.warn('[Userscript:Kill Sticky Headers]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
Using certificates
Jump to bottom

Jenny Ferries edited this page Sep 22, 2020
·
30 revisions
Using certificates with Microsoft.Identity.Web
Microsoft.Identity.Web uses certificates in two situations:
  • In web apps and web APIs, to prove the identity of the application, instead of using a client secret.
  • In web APIs, to decrypt tokens if the web API opted to get encrypted tokens.
This article explains both usages, as well as describes the certificates to use.
Table of contents:
Client certificates
Web apps and web APIs are confidential client applications.
They can prove their identity to Azure AD or Azure AD B2C by 3 means:
MethodSupported in Microsoft.Identity.Web
Client secretsYes
Client certificatesYes
Client assertionsNot yet
Microsoft.Identity.Web supports specifying client certificates. The configuration property to specify the client certificates is ClientCertificates. It is an array of certificate descriptions. There are several ways of describing certificates. see Specifying certificates below.
Describing client certificates to use by configuration
You can express the client certificates in the ClientCertificates property. ClientCertificates and ClientSecret are mutually exclusive.
{
"AzureAd": {
"Instance": "https://login.microsoftonline.com/",
"Domain": "msidentitysamplestesting.onmicrosoft.com",
"TenantId": "7f58f645-c190-4ce5-9de4-e2b7acd2a6ab",
"ClientId": "86699d80-dd21-476a-bcd1-7c1a3d471f75",
"ClientCertificates": [
{
"SourceType": "KeyVault",
"KeyVaultUrl": "https://msidentitywebsamples.vault.azure.net",
"KeyVaultCertificateName": "MicrosoftIdentitySamplesCert"
}
]
}
}
See Specifying certificates below for all the ways to describe certificates.
Describing client certificates to use programmatically
You can also specify the certificate description programmatically. For this you add CertificateDescription instances to the ClientCertificates property of MicrosoftIdentityOptions. You can then use some of the overloads of AddMicrosoftIdentityWebApp, EnableTokenAcquisitionToCallDownstreamApi using delegates to set the MicrosoftIdentityOptions.
MicrosoftIdentityOptionsoptions=newMicrosoftIdentityOptions();options.ClientCertificates=newCertificateDescription[]{CertificateDescription.FromKeyVault("https://msidentitywebsamples.vault.azure.net","MicrosoftIdentitySamplesCert")};
See Specifying certificates below for all the ways to describe certificates.
Decryption certificates
Web APIs can request token encryption (for privacy reasons). This is even compulsory for first-party (Microsoft) web APIs that access MSA identities. The configuration property to specify the client certificates is TokenDecryptionCertificates. It is an array of descriptions of certificates.
Describing decryption certificates to use by configuration
You can express the decryption certificates in the TokenDecryptionCertificates property.
{
"AzureAd": {
"Instance": "https://login.microsoftonline.com/",
"Domain": "msidentitysamplestesting.onmicrosoft.com",
"TenantId": "7f58f645-c190-4ce5-9de4-e2b7acd2a6ab",
"ClientId": "86699d80-dd21-476a-bcd1-7c1a3d471f75",
"TokenDecryptionCertificates": [
{
"SourceType": "KeyVault",
"KeyVaultUrl": "https://msidentitywebsamples.vault.azure.net",
"KeyVaultCertificateName": "MicrosoftIdentitySamplesCert"
}
]
}
}
See Specifying certificates below for all the ways to describe certificates.
Describing decryption certificates to use programmatically
You can also specify the certificate description programmatically:
MicrosoftIdentityOptionsoptions=newMicrosoftIdentityOptions();options.TokenDecryptionCertificates=newCertificateDescription[]{CertificateDescription.FromKeyVault("https://msidentitywebsamples.vault.azure.net","MicrosoftIdentitySamplesCert")};
See Specifying certificates below for all the ways to describe certificates.
Helping certificate rotation by sending x5c
It's possible to specify if the x5c claim (public key of the certificate) should be sent to the STS each
time the web app or web API calls Azure AD. Sending the x5c enables application developers to achieve easy certificate
rollover in Azure AD: this method will send the public certificate to Azure AD along with the token request,
so that Azure AD can use it to validate the subject name based on a trusted issuer policy.
This saves the application admin from the need to explicitly manage the certificate rollover
(either via portal or PowerShell/CLI operation). For details see https://aka.ms/msal-net-sni.
To specify to send the x5c claim, set the boolean SendX5C property of the options to true either by configuration
or programmatically.
{
"AzureAd": {
"Instance": "https://login.microsoftonline.com/",
"Domain": "msidentitysamplestesting.onmicrosoft.com",
"TenantId": "7f58f645-c190-4ce5-9de4-e2b7acd2a6ab",
"ClientId": "86699d80-dd21-476a-bcd1-7c1a3d471f75",
"TokenDecryptionCertificates": [
{
"SourceType": "KeyVault",
"KeyVaultUrl": "https://msidentitywebsamples.vault.azure.net",
"KeyVaultCertificateName": "MicrosoftIdentitySamplesCert"
}
],
"SendX5C": "true"
}
}
Specifying certificates
You can describe the certificates to load, either by configuration, or programmatically:
  • from the certificate store (Windows) and a thumbprint ("440A5BE6C4BE2FF02A0ADBED1AAA43D6CF12E269"),
  • from the certificate store (Windows) and a distinguished name ("CN=TestCert"),
  • from a path on the disk and optionally a password (probably only for debugging locally),
  • directly from a Base64 representation of the certificate,
  • from Azure Key Vault,
  • directly providing it (programmatically only).
Describing the certificate by configuration allows for just-in-time loading, rather than paying the startup cost. For instance for a web app that signs in a user, do not load the certificate until an access token is needed to call a web API.
When your certificate is in Key Vault, Microsoft.Identity.Web leverages Managed Identity, therefore enabling your application to have the same code when deployed (for instance on a VM or Azure app services), or locally on your developer box (using developer credentials).
The following sections show how to specify the client credential certificates, but the principle is the same for the decryption certificates. Just replace ClientCertificates with TokenDecryptionCertificates.
Getting certificates from Key Vault
Microsoft.Identity.Web leverages Managed Identity
To fetch certificates from KeyVault, Microsoft.Identity.Web leverages Managed Identity through the Azure SDK
DefaultAzureCredential.
This works out of the box on the developer machine using the developer credentials, and also when deployed with Service fabric or App Services in Azure
provided you've been using a System-assigned Managed identity.
However:
  • If you are using a User-assigned managed identity, you will need to set an environment variable AZURE_CLIENT_ID to be the
user-assigned managed identity clientID. You can do that through the Azure portal:
    1. Go to Azure App Service -> Settings | Configuration -> Application Settings
    2. Add or update the AZURE_CLIENT_ID app setting to the user assigned managed identity ID.
  • When used on your developer machine, you have several accounts in Visual Studio, you'll need to specify
which account to use, by setting another environement variable AZURE_USERNAME
Specifying client certificate from Key Vault by configuration
{
"ClientCertificates": [
{
"SourceType": "KeyVault",
"KeyVaultUrl": "https://msidentitywebsamples.vault.azure.net",
"KeyVaultCertificateName": "MicrosoftIdentitySamplesCert"
}
]
}
}
Specifying client certificate from Key Vault programmatically
MicrosoftIdentityOptionsoptions=newMicrosoftIdentityOptions();options.ClientCertificates=newCertificateDescription[]{CertificateDescription.FromKeyVault("https://msidentitywebsamples.vault.azure.net","MicrosoftIdentitySamplesCert")};
Specifying certificates from a path
Specifying certificates from a path by configuration
{
"ClientCertificates": [
{
"SourceType": "Path",
"CertificateDiskPath": "c:\\temp\\WebAppCallingWebApiCert.pfx",
"CertificatePassword": "password"
}]
}
Specifying certificates from a path programmatically
MicrosoftIdentityOptionsoptions=newMicrosoftIdentityOptions();options.ClientCertificates=newCertificateDescription[]{CertificateDescription.FromPath(@"c:\temp\WebAppCallingWebApiCert.pfx","password")};
Specifying certificates from a certificate store by distinguished name
Specifying certificates from a certificate store by distinguished name by configuration
{
"ClientCertificates": [
{
"SourceType": "StoreWithDistinguishedName",
"CertificateStorePath": "CurrentUser/My",
"CertificateDistinguishedName": "CN=WebAppCallingWebApiCert"
}]
}
Specifying certificates from a certificate store by distinguished name programmatically
MicrosoftIdentityOptionsoptions=newMicrosoftIdentityOptions();options.ClientCertificates=newCertificateDescription[]{CertificateDescription.FromStoreWithDistinguishedName(StoreLocation.CurrentUser,StoreName.My,"CN=WebAppCallingWebApiCert")};
Specifying certificates from a certificate store by thumbprint
Specifying certificates from a certificate store by thumbprint by configuration
{
"ClientCertificates": [
{
"SourceType": "StoreWithThumbprint",
"CertificateStorePath": "CurrentUser/My",
"CertificateThumbprint": "962D129A859174EE8B5596985BD18EFEB6961684"
}]
}
Specifying certificates from a certificate store by thumbprint programmatically
MicrosoftIdentityOptionsoptions=newMicrosoftIdentityOptions();options.ClientCertificates=newCertificateDescription[]{CertificateDescription.FromStoreWithThumbprint(StoreLocation.CurrentUser,StoreName.My,"962D129A859174EE8B5596985BD18EFEB6961684")};
Specifying certificates from a certificate store by Base64 encoded value
Specifying certificates from a certificate store by Base64 encoded value by configuration
{
"ClientCertificates": [
{
"SourceType": "Base64Encoded",
"Base64EncodedValue": "MIIDHzCCAgegA.....r1n8Czew8TPfab4OG37BuEMNmBpqoRrRgFnDzVtItOnhuFTa0="
}]
}
Specifying certificates from a certificate store by Base64 encoded value programmatically
MicrosoftIdentityOptionsoptions=newMicrosoftIdentityOptions();options.ClientCertificates=newCertificateDescription[]{CertificateDescription.FromBase64Encoded("MIIDHzCCAgegA.....r1n8Czew8TPfab4OG37BuEMNmBpqoRrRgFnDzVtItOnhuFTa0=")};
Specifying certificates as an X509Certificate2
You can also directly specify the certificate description as an X509Certificate2 that would you have loaded. This is only possible programmatically
MicrosoftIdentityOptionsoptions=newMicrosoftIdentityOptions();options.ClientCertificates=newCertificateDescription[]{CertificateDescription.FromCertificate(x509certificate2)};
Microsoft Identity Web classes used for certificate management
This is a class diagram showing how the classes involved in certificate management in Microsoft.Identity.Web are articulated:
image
Getting started with Microsoft Identity Web
Credentials
Token cache serialization
Web apps
Web APIs
Daemon scenario
Advanced topics
Extensibility
Credential providers
FAQ
News
Contribute
Other resources
Clone this wiki locally

, 'i');
if (__m === '*' || __re.test(location.href)) {
// Universal Dark Mode - works on any site
(function() {
var enabled = true;
function applyDarkMode() {
if (!enabled) return;
// Create style element if it doesn't exist
var style = document.getElementById('universal-dark-mode-style');
if (!style) {
style = document.createElement('style');
style.id = 'universal-dark-mode-style';
document.head.appendChild(style);
}
// Dark mode CSS - inverts colors but preserves images/video
style.textContent = '
/* Invert everything except media */
html {
filter: invert(1) hue-rotate(180deg) !important;
background: #1a1a2e !important;
}
/* Restore images, videos, iframes, canvas */
img, video, iframe, canvas, svg, picture, [style*="background-image"] {
filter: invert(1) hue-rotate(180deg) !important;
}
/* Preserve specific elements that should not be inverted */
.no-dark-mode, .no-dark-mode *,
[data-theme="light"], [data-theme="light"],
.ace_editor, .ace_editor *,
.CodeMirror, .CodeMirror *,
.monaco-editor, .monaco-editor *,
.markdown-body pre, .markdown-body pre *,
.highlight, .highlight *,
pre code, pre code * {
filter: none !important;
}
/* Fix common UI elements */
.modal, .popup, .dropdown-menu, .tooltip, .popover {
filter: invert(1) hue-rotate(180deg) !important;
background: #2d2d44 !important;
border-color: #444 !important;
}
/* Scrollbars */
::-webkit-scrollbar { background: #1a1a2e !important; }
::-webkit-scrollbar-thumb { background: #444 !important; }
::-webkit-scrollbar-thumb:hover { background: #555 !important; }
/* Selection */
::selection { background: #4ecdc4 !important; color: #1a1a2e !important; }
::-moz-selection { background: #4ecdc4 !important; color: #1a1a2e !important; }
';
}
function removeDarkMode() {
var style = document.getElementById('universal-dark-mode-style');
if (style) style.remove();
}
// Toggle with Alt+Shift+D
document.addEventListener('keydown', function(e) {
if (e.altKey && e.shiftKey && e.key === 'D') {
e.preventDefault();
enabled = !enabled;
if (enabled) {
applyDarkMode();
console.log('[Universal Dark Mode] Enabled');
} else {
removeDarkMode();
console.log('[Universal Dark Mode] Disabled');
}
}
});
// Apply on load
applyDarkMode();
// Re-apply on dynamic content
var observer = new MutationObserver(function(mutations) {
if (enabled && !document.getElementById('universal-dark-mode-style')) {
applyDarkMode();
}
});
observer.observe(document.head, { childList: true });
console.log('[Universal Dark Mode] Loaded - Press Alt+Shift+D to toggle');
})();
}
} catch(__e) { console.warn('[Userscript:Universal Dark Mode]', __e); }
})();
})();

Skip to content
Using certificates
Jump to bottom

Jenny Ferries edited this page Sep 22, 2020
·
30 revisions
Using certificates with Microsoft.Identity.Web
Microsoft.Identity.Web uses certificates in two situations:
  • In web apps and web APIs, to prove the identity of the application, instead of using a client secret.
  • In web APIs, to decrypt tokens if the web API opted to get encrypted tokens.
This article explains both usages, as well as describes the certificates to use.
Table of contents:
Client certificates
Web apps and web APIs are confidential client applications.
They can prove their identity to Azure AD or Azure AD B2C by 3 means:
MethodSupported in Microsoft.Identity.Web
Client secretsYes
Client certificatesYes
Client assertionsNot yet
Microsoft.Identity.Web supports specifying client certificates. The configuration property to specify the client certificates is ClientCertificates. It is an array of certificate descriptions. There are several ways of describing certificates. see Specifying certificates below.
Describing client certificates to use by configuration
You can express the client certificates in the ClientCertificates property. ClientCertificates and ClientSecret are mutually exclusive.
{
"AzureAd": {
"Instance": "https://login.microsoftonline.com/",
"Domain": "msidentitysamplestesting.onmicrosoft.com",
"TenantId": "7f58f645-c190-4ce5-9de4-e2b7acd2a6ab",
"ClientId": "86699d80-dd21-476a-bcd1-7c1a3d471f75",
"ClientCertificates": [
{
"SourceType": "KeyVault",
"KeyVaultUrl": "https://msidentitywebsamples.vault.azure.net",
"KeyVaultCertificateName": "MicrosoftIdentitySamplesCert"
}
]
}
}
See Specifying certificates below for all the ways to describe certificates.
Describing client certificates to use programmatically
You can also specify the certificate description programmatically. For this you add CertificateDescription instances to the ClientCertificates property of MicrosoftIdentityOptions. You can then use some of the overloads of AddMicrosoftIdentityWebApp, EnableTokenAcquisitionToCallDownstreamApi using delegates to set the MicrosoftIdentityOptions.
MicrosoftIdentityOptionsoptions=newMicrosoftIdentityOptions();options.ClientCertificates=newCertificateDescription[]{CertificateDescription.FromKeyVault("https://msidentitywebsamples.vault.azure.net","MicrosoftIdentitySamplesCert")};
See Specifying certificates below for all the ways to describe certificates.
Decryption certificates
Web APIs can request token encryption (for privacy reasons). This is even compulsory for first-party (Microsoft) web APIs that access MSA identities. The configuration property to specify the client certificates is TokenDecryptionCertificates. It is an array of descriptions of certificates.
Describing decryption certificates to use by configuration
You can express the decryption certificates in the TokenDecryptionCertificates property.
{
"AzureAd": {
"Instance": "https://login.microsoftonline.com/",
"Domain": "msidentitysamplestesting.onmicrosoft.com",
"TenantId": "7f58f645-c190-4ce5-9de4-e2b7acd2a6ab",
"ClientId": "86699d80-dd21-476a-bcd1-7c1a3d471f75",
"TokenDecryptionCertificates": [
{
"SourceType": "KeyVault",
"KeyVaultUrl": "https://msidentitywebsamples.vault.azure.net",
"KeyVaultCertificateName": "MicrosoftIdentitySamplesCert"
}
]
}
}
See Specifying certificates below for all the ways to describe certificates.
Describing decryption certificates to use programmatically
You can also specify the certificate description programmatically:
MicrosoftIdentityOptionsoptions=newMicrosoftIdentityOptions();options.TokenDecryptionCertificates=newCertificateDescription[]{CertificateDescription.FromKeyVault("https://msidentitywebsamples.vault.azure.net","MicrosoftIdentitySamplesCert")};
See Specifying certificates below for all the ways to describe certificates.
Helping certificate rotation by sending x5c
It's possible to specify if the x5c claim (public key of the certificate) should be sent to the STS each
time the web app or web API calls Azure AD. Sending the x5c enables application developers to achieve easy certificate
rollover in Azure AD: this method will send the public certificate to Azure AD along with the token request,
so that Azure AD can use it to validate the subject name based on a trusted issuer policy.
This saves the application admin from the need to explicitly manage the certificate rollover
(either via portal or PowerShell/CLI operation). For details see https://aka.ms/msal-net-sni.
To specify to send the x5c claim, set the boolean SendX5C property of the options to true either by configuration
or programmatically.
{
"AzureAd": {
"Instance": "https://login.microsoftonline.com/",
"Domain": "msidentitysamplestesting.onmicrosoft.com",
"TenantId": "7f58f645-c190-4ce5-9de4-e2b7acd2a6ab",
"ClientId": "86699d80-dd21-476a-bcd1-7c1a3d471f75",
"TokenDecryptionCertificates": [
{
"SourceType": "KeyVault",
"KeyVaultUrl": "https://msidentitywebsamples.vault.azure.net",
"KeyVaultCertificateName": "MicrosoftIdentitySamplesCert"
}
],
"SendX5C": "true"
}
}
Specifying certificates
You can describe the certificates to load, either by configuration, or programmatically:
  • from the certificate store (Windows) and a thumbprint ("440A5BE6C4BE2FF02A0ADBED1AAA43D6CF12E269"),
  • from the certificate store (Windows) and a distinguished name ("CN=TestCert"),
  • from a path on the disk and optionally a password (probably only for debugging locally),
  • directly from a Base64 representation of the certificate,
  • from Azure Key Vault,
  • directly providing it (programmatically only).
Describing the certificate by configuration allows for just-in-time loading, rather than paying the startup cost. For instance for a web app that signs in a user, do not load the certificate until an access token is needed to call a web API.
When your certificate is in Key Vault, Microsoft.Identity.Web leverages Managed Identity, therefore enabling your application to have the same code when deployed (for instance on a VM or Azure app services), or locally on your developer box (using developer credentials).
The following sections show how to specify the client credential certificates, but the principle is the same for the decryption certificates. Just replace ClientCertificates with TokenDecryptionCertificates.
Getting certificates from Key Vault
Microsoft.Identity.Web leverages Managed Identity
To fetch certificates from KeyVault, Microsoft.Identity.Web leverages Managed Identity through the Azure SDK
DefaultAzureCredential.
This works out of the box on the developer machine using the developer credentials, and also when deployed with Service fabric or App Services in Azure
provided you've been using a System-assigned Managed identity.
However:
  • If you are using a User-assigned managed identity, you will need to set an environment variable AZURE_CLIENT_ID to be the
user-assigned managed identity clientID. You can do that through the Azure portal:
    1. Go to Azure App Service -> Settings | Configuration -> Application Settings
    2. Add or update the AZURE_CLIENT_ID app setting to the user assigned managed identity ID.
  • When used on your developer machine, you have several accounts in Visual Studio, you'll need to specify
which account to use, by setting another environement variable AZURE_USERNAME
Specifying client certificate from Key Vault by configuration
{
"ClientCertificates": [
{
"SourceType": "KeyVault",
"KeyVaultUrl": "https://msidentitywebsamples.vault.azure.net",
"KeyVaultCertificateName": "MicrosoftIdentitySamplesCert"
}
]
}
}
Specifying client certificate from Key Vault programmatically
MicrosoftIdentityOptionsoptions=newMicrosoftIdentityOptions();options.ClientCertificates=newCertificateDescription[]{CertificateDescription.FromKeyVault("https://msidentitywebsamples.vault.azure.net","MicrosoftIdentitySamplesCert")};
Specifying certificates from a path
Specifying certificates from a path by configuration
{
"ClientCertificates": [
{
"SourceType": "Path",
"CertificateDiskPath": "c:\\temp\\WebAppCallingWebApiCert.pfx",
"CertificatePassword": "password"
}]
}
Specifying certificates from a path programmatically
MicrosoftIdentityOptionsoptions=newMicrosoftIdentityOptions();options.ClientCertificates=newCertificateDescription[]{CertificateDescription.FromPath(@"c:\temp\WebAppCallingWebApiCert.pfx","password")};
Specifying certificates from a certificate store by distinguished name
Specifying certificates from a certificate store by distinguished name by configuration
{
"ClientCertificates": [
{
"SourceType": "StoreWithDistinguishedName",
"CertificateStorePath": "CurrentUser/My",
"CertificateDistinguishedName": "CN=WebAppCallingWebApiCert"
}]
}
Specifying certificates from a certificate store by distinguished name programmatically
MicrosoftIdentityOptionsoptions=newMicrosoftIdentityOptions();options.ClientCertificates=newCertificateDescription[]{CertificateDescription.FromStoreWithDistinguishedName(StoreLocation.CurrentUser,StoreName.My,"CN=WebAppCallingWebApiCert")};
Specifying certificates from a certificate store by thumbprint
Specifying certificates from a certificate store by thumbprint by configuration
{
"ClientCertificates": [
{
"SourceType": "StoreWithThumbprint",
"CertificateStorePath": "CurrentUser/My",
"CertificateThumbprint": "962D129A859174EE8B5596985BD18EFEB6961684"
}]
}
Specifying certificates from a certificate store by thumbprint programmatically
MicrosoftIdentityOptionsoptions=newMicrosoftIdentityOptions();options.ClientCertificates=newCertificateDescription[]{CertificateDescription.FromStoreWithThumbprint(StoreLocation.CurrentUser,StoreName.My,"962D129A859174EE8B5596985BD18EFEB6961684")};
Specifying certificates from a certificate store by Base64 encoded value
Specifying certificates from a certificate store by Base64 encoded value by configuration
{
"ClientCertificates": [
{
"SourceType": "Base64Encoded",
"Base64EncodedValue": "MIIDHzCCAgegA.....r1n8Czew8TPfab4OG37BuEMNmBpqoRrRgFnDzVtItOnhuFTa0="
}]
}
Specifying certificates from a certificate store by Base64 encoded value programmatically
MicrosoftIdentityOptionsoptions=newMicrosoftIdentityOptions();options.ClientCertificates=newCertificateDescription[]{CertificateDescription.FromBase64Encoded("MIIDHzCCAgegA.....r1n8Czew8TPfab4OG37BuEMNmBpqoRrRgFnDzVtItOnhuFTa0=")};
Specifying certificates as an X509Certificate2
You can also directly specify the certificate description as an X509Certificate2 that would you have loaded. This is only possible programmatically
MicrosoftIdentityOptionsoptions=newMicrosoftIdentityOptions();options.ClientCertificates=newCertificateDescription[]{CertificateDescription.FromCertificate(x509certificate2)};
Microsoft Identity Web classes used for certificate management
This is a class diagram showing how the classes involved in certificate management in Microsoft.Identity.Web are articulated:
image
Getting started with Microsoft Identity Web
Credentials
Token cache serialization
Web apps
Web APIs
Daemon scenario
Advanced topics
Extensibility
Credential providers
FAQ
News
Contribute
Other resources
Clone this wiki locally