Using certificates

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.

  

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:

• client secrets
• client certificates
• client assertions

In addition to Client secrets, Microsoft.Identity.Web supports specifying client certificates in many different ways (See Specifying certificates below)

The configuration property to specify the client certificates is ClientCertificates it's an array of description of certificates

By configuration

You can express the client certificates in the ClientCertificates property, which is exclusive with ClientSecret.

{
  "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

Programmatically

You can also specify the certificate description programmatically:

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

Decrypt certificates

Web APIs can request token encryption (for privacy reasons). This is even compulsory for 1P Web APIs that access MSA identities. The configuration property to specify the client certificates is TokenDecryptionCertificates it's an array of description of certificates

By configuration

You can express the client certificates in the TokenDecryptionCertificatesproperty

{
  "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

Programmatically

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

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 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. Jut replace ClientCertificates by TokenDecryptionCertificates.

Getting certificates from KeyVault

Specifying client certificate from KeyVault by configuration

{
    "ClientCertificates": [
      {
        "SourceType": "KeyVault",
        "KeyVaultUrl": "https://msidentitywebsamples.vault.azure.net",
        "KeyVaultCertificateName": "MicrosoftIdentitySamplesCert"
      }
     ]
  }
}

Specifying client certificate from KeyVault programmatically

MicrosoftIdentityOptions options = new MicrosoftIdentityOptions();
options.ClientCertificates = new CertificateDescription[] {
 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

MicrosoftIdentityOptions options = new MicrosoftIdentityOptions();
options.ClientCertificates = new CertificateDescription[] {
 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

MicrosoftIdentityOptions options = new MicrosoftIdentityOptions();
options.ClientCertificates = new CertificateDescription[] {
 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

MicrosoftIdentityOptions options = new MicrosoftIdentityOptions();
options.ClientCertificates = new CertificateDescription[] {
 CertificateDescription.FromStoreWithThumprint(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

MicrosoftIdentityOptions options = new MicrosoftIdentityOptions();
options.ClientCertificates = new CertificateDescription[] {
 CertificateDescription.FromBase64Encoded("MIIDHzCCAgegA.....r1n8Czew8TPfab4OG37BuEMNmBpqoRrRgFnDzVtItOnhuFTa0=")
};