Using certificates
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 in the web API opted to get encrypted tokens.
This article explains both usages, as well as how to describe the certificates to use.
Table of content:
-
Using certificates with Microsoft.Identity.Web
- Client certificates
- Decrypt certificates
-
Specifying certificates
- Getting certificates from Key Vault
- Specifying Certificates from a Path
- Specifying Certificates from a certificate store by distinguished name
- Specifying Certificates from a certificate store by thumbprint
- Specifying Certificates from a certificate store by base64 encoded value
- Specifying Certificates as an X509Certificate2
- Microsoft Identity Web classes used for certificate management
Web apps and Web APIs are confidential client applications.
They can prove their identity to Azure AD or Azure AD B2C by 3 means:
| mean | Supported in Microsoft.Identity.Web |
|---|---|
| client secrets | Yes |
| client certificates | Yes |
| client assertions | Not yet |
Microsoft.Identity.Web supports specifying client certificates. The configuration property to specify the client certificates is ClientCertificates it's an array of description of certificates descriptions. There are several ways of describing certificates (See Specifying certificates below.)
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.
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 AddSignIn, AddWebAppCallsProtectedWebApi and AddWebApiCallsProtectedWebApi using delegates to set the microsoft identity options.
MicrosoftIdentityOptions options = new MicrosoftIdentityOptions();
options.ClientCertificates = new CertificateDescription[] {
CertificateDescription.FromKeyVault("https://msidentitywebsamples.vault.azure.net",
"MicrosoftIdentitySamplesCert")
};See Specifying certificates below for all the ways to describe 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's an array of description of certificates.
You can express the client 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.
You can also specify the certificate description programmatically:
MicrosoftIdentityOptions options = new MicrosoftIdentityOptions();
options.TokenDecryptionCertificates = new CertificateDescription[] {
CertificateDescription.FromKeyVault("https://msidentitywebsamples.vault.azure.net",
"MicrosoftIdentitySamplesCert")
};See Specifying certificates below for all the ways to describe 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 KeyVault,
- 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, not load the certificate until an access token is needed to call a Web API.
When your certificate is in KeyVault, 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 decrypt certificates. Just replace ClientCertificates by TokenDecryptionCertificates.
{
"ClientCertificates": [
{
"SourceType": "KeyVault",
"KeyVaultUrl": "https://msidentitywebsamples.vault.azure.net",
"KeyVaultCertificateName": "MicrosoftIdentitySamplesCert"
}
]
}
}MicrosoftIdentityOptions options = new MicrosoftIdentityOptions();
options.ClientCertificates = new CertificateDescription[] {
CertificateDescription.FromKeyVault("https://msidentitywebsamples.vault.azure.net",
"MicrosoftIdentitySamplesCert")
};{
"ClientCertificates": [
{
"SourceType": "Path",
"CertificateDiskPath": "c:\\temp\\WebAppCallingWebApiCert.pfx",
"CertificatePassword": "password"
}]
}MicrosoftIdentityOptions options = new MicrosoftIdentityOptions();
options.ClientCertificates = new CertificateDescription[] {
CertificateDescription.FromPath(@"c:\temp\WebAppCallingWebApiCert.pfx",
"password")
};{
"ClientCertificates": [
{
"SourceType": "StoreWithDistinguishedName",
"CertificateStorePath": "CurrentUser/My",
"CertificateDistinguishedName": "CN=WebAppCallingWebApiCert"
}]
}MicrosoftIdentityOptions options = new MicrosoftIdentityOptions();
options.ClientCertificates = new CertificateDescription[] {
CertificateDescription.FromStoreWithDistinguishedName(StoreLocation.CurrentUser,
StoreName.My,
"CN=WebAppCallingWebApiCert")
};{
"ClientCertificates": [
{
"SourceType": "StoreWithThumbprint",
"CertificateStorePath": "CurrentUser/My",
"CertificateThumbprint": "962D129A859174EE8B5596985BD18EFEB6961684"
}]
}MicrosoftIdentityOptions options = new MicrosoftIdentityOptions();
options.ClientCertificates = new CertificateDescription[] {
CertificateDescription.FromStoreWithThumbprint(StoreLocation.CurrentUser,
StoreName.My,
"962D129A859174EE8B5596985BD18EFEB6961684")
};{
"ClientCertificates": [
{
"SourceType": "Base64Encoded",
"Base64EncodedValue": "MIIDHzCCAgegA.....r1n8Czew8TPfab4OG37BuEMNmBpqoRrRgFnDzVtItOnhuFTa0="
}]
}MicrosoftIdentityOptions options = new MicrosoftIdentityOptions();
options.ClientCertificates = new CertificateDescription[] {
CertificateDescription.FromBase64Encoded("MIIDHzCCAgegA.....r1n8Czew8TPfab4OG37BuEMNmBpqoRrRgFnDzVtItOnhuFTa0=")
};You can also directly specify the certificate description as an X509Certificate2 that would you have loaded. This is only possible programmatically
MicrosoftIdentityOptions options = new MicrosoftIdentityOptions();
options.ClientCertificates = new CertificateDescription[] {
CertificateDescription.FromCertificate(x509certificate2)
};This is a class diagram showing how the classes involved in certificate management in Microsoft.Identity.Web are articulated:
