diff --git a/README.md b/README.md
index 496999c..baa2bb2 100644
--- a/README.md
+++ b/README.md
@@ -274,13 +274,15 @@ classDiagram
CredentialDescription *-- "CredentialType" CredentialType : Has
IdentityApplicationOptions --> "ClientCredentials" CredentialDescription : Has many
IdentityApplicationOptions --> "TokenDecryptionCredentials" CredentialDescription : Has many
-
+
```
+For details about Credentials, see [CredentialDecription](./docs/credentialdescription.md)
+
### Credential loaders
An important part of the application options are the credentials. In addition to the credential descriptions, the
library offers extensibility mechanisms so that implementers can add their own credential source loaders.
-
+
```mermaid
classDiagram
class CredentialSourceLoaderParameters {
@@ -318,9 +320,9 @@ you would probably prefer to call downstream web APIs without having to be preoc
really want to use the lower level API, you should:
- get hold of a ITokenAcquirerFactory. Implementations can provide a TokenAcquirerFactory for instance, with a singleton.
- get a ITokenAcquirer (by its name, for instance). This corresponds to the application options
-- From the token acquirer get a token for on behalf of the user, or the app. If you don't specify any AcquireTokenOptions,
+- From the token acquirer get a token for on behalf of the user, or the app. If you don't specify any AcquireTokenOptions,
the implementation should do its best effort. The AcquireTokenOptions enable you to override the defaults.
-
+
```mermaid
classDiagram
class AcquireTokenOptions {
@@ -496,8 +498,8 @@ contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additio
## Trademarks
-This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft
-trademarks or logos is subject to and must follow
+This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft
+trademarks or logos is subject to and must follow
[Microsoft's Trademark & Brand Guidelines](https://www.microsoft.com/en-us/legal/intellectualproperty/trademarks/usage/general).
Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship.
Any use of third-party trademarks or logos are subject to those third-party's policies.
diff --git a/docs/credentialdescription.md b/docs/credentialdescription.md
new file mode 100644
index 0000000..a7f6a5b
--- /dev/null
+++ b/docs/credentialdescription.md
@@ -0,0 +1,391 @@
+# CredentialDescription Documentation
+
+The `CredentialDescription` class is used to describe credentials for Microsoft Identity applications. These credentials support both traditional certificate-based and certificateless authentication approaches, and can be used for two purposes:
+1. Client Credentials - to prove the identity of the application
+2. Token Decryption Credentials - to decrypt tokens
+
+These are typically used int configuration for Entra ID applications:
+
+```json
+{
+ "AzureAd": {
+ "Instance": "https://login.microsoftonline.com/",
+ "TenantId": "msidlab4.onmicrosoft.com",
+ "ClientId": "f6b698c0-140c-448f-8155-4aa9bf77ceba",
+ "ClientCredentials": [
+ {
+ "SourceType": "KeyVault",
+ "KeyVaultUrl": "https://webappsapistests.vault.azure.net",
+ "KeyVaultCertificateName": "MyVerifyCertificate"
+ }
+ ],
+ "TokenDecryptCredentials": [
+ {
+ "SourceType": "KeyVault",
+ "KeyVaultUrl": "https://webappsapistests.vault.azure.net",
+ "KeyVaultCertificateName": "MyVerifyCertificate"
+ }
+ ]
+ }
+}
+```
+
+This document explains the possible client credentials types, as well as when use them, and how to express them, by configuration and by code.
+
+## App authentication Approaches
+
+### Client secrets
+
+Uses an app password shared between the Identity Provider (Entra ID) and the code of the app. This is simple, but not usable in production. Certain organizations even prevent its usage.
+
+### Traditional Certificate-Based Authentication
+Uses X.509 certificates for strong cryptographic identity verification. This is the traditional approach that relies on certificate management.
+
+### Certificateless Authentication
+Provides authentication without the overhead of certificate management. This modern approach is particularly useful for:
+- Cloud-native applications
+- Scenarios where certificate management is challenging
+- Environments with limited PKI infrastructure
+- Rapid deployment requirements
+
+This is the recommended approach
+
+## When to Use Which Credential Type
+
+| Credential Type | What Is It | When to Use | Advantages | Considerations |
+|----------------|------------|-------------|------------|----------------|
+| **Federation identity credential with Managed Identity (FIC+MSI)**
(`SignedAssertionFromManagedIdentity`) | Azure Managed Identity | • Production on Azure
• Zero cert management
• Cloud-native apps
_System-assigned_: Resource lifecycle
_User-assigned_: Share across resources | • No secret management
• Automatic rotation
• Azure integration
• Enhanced security | Best choice for Azure workloads |
+| **Key Vault**
(`SourceType = KeyVault`) | Certificate stored in Azure Key Vault | • Production environments
• Need for centralized management
• Require automatic rotation
• Share across services | • Secure storage & access control
• Automatic renewal
• Audit logging
• Managed backup/recovery | Best choice for production workloads not hosted on an Azure compute supporting managed identity|
+| **Certificate Store**
(`StoreWithThumbprint` or `StoreWithDistinguishedName`) | Certificate in Windows Certificate Store | • Production on Windows
• Using Windows cert management
_Thumbprint_: Target specific version
_DistinguishedName_: Auto rollover | • Native Windows management
• Windows security integration
• HSM support | Ideal for Windows production environments |
+| **File Path**
(`SourceType = Path`) | PFX/P12 file on disk | • Development/testing
• Simple deployment
• File-based config preferred | • Simple setup
• Easy deployment
• Direct file access | **Not for production:**
• Password in config
• Manual management
• Less secure storage |
+| **Base64 Encoded**
(`SourceType = Base64Encoded`) | Certificate as base64 string | • Development/testing
• Config-embedded certificates | • Simple configuration
• No file system dependency | **Not for production:**
• Exposed in config
• Manual management
• Less secure |
+| **Client Secret**
(`SourceType = ClientSecret`) | Simple shared secret string | • Development/testing
• Basic security requirements | • Simple to use
• Easy to configure | **Not for production:**
• Less secure
• No auto-rotation
• Easy to expose |
+| **Auto Decrypt Keys**
(`SourceType = AutoDecryptKeys`) | Automatic key retrieval | • Encrypted token scenarios
• Automatic token decryption | • Automatic key management
• Key rotation support
• Simplified workflow | Specific to token decryption scenarios |
+
+## JSON Configuration
+
+
+### 1. FIC+MSI
+```json
+{
+ "ClientCredentials": [
+ {
+ "SourceType": "SignedAssertionFromManagedIdentity",
+ "ManagedIdentityClientId": "12345", // Optional for system-assigned managed identity
+ "TokenExchangeUrl": "api://AzureADTokenExchangeChina", // Optional
+ "TokenExchangeAuthority": "https://login.microsoftonline.cloud2/33e01921-4d64-4f8c-a055-5bdaffd5e33d/v2.0" // Optional
+ }]
+}
+```
+
+### 2. Certificate Credentials
+
+This is the case where the client credentials are a certificate.
+
+#### From Key Vault
+```json
+{
+ "ClientCredentials": [
+ {
+ "SourceType": "KeyVault",
+ "KeyVaultUrl": "https://msidentitywebsamples.vault.azure.net",
+ "KeyVaultCertificateName": "MicrosoftIdentitySamplesCert"
+ }
+ ]
+}
+```
+
+#### From Certificate Store (Using Thumbprint)
+```json
+{
+ "ClientCredentials": [
+ {
+ "SourceType": "StoreWithThumbprint",
+ "CertificateStorePath": "CurrentUser/My",
+ "CertificateThumbprint": "962D129A...D18EFEB6961684"
+ }]
+}
+```
+
+#### From Certificate Store (Using Distinguished Name)
+```json
+{
+ "ClientCredentials": [
+ {
+ "SourceType": "StoreWithDistinguishedName",
+ "CertificateStorePath": "CurrentUser/My",
+ "CertificateDistinguishedName": "CN=WebAppCallingWebApiCert"
+ }]
+}
+```
+
+#### From File Path
+```json
+{
+ "ClientCredentials": [
+ {
+ "SourceType": "Path",
+ "CertificateDiskPath": "c:\\temp\\WebAppCallingWebApiCert.pfx",
+ "CertificatePassword": "password"
+ }]
+}
+```
+
+#### Base64 Encoded
+```json
+{
+ "ClientCredentials": [
+ {
+ "SourceType": "Base64Encoded",
+ "Base64EncodedValue": "MIIDHzCgegA.....r1n8Ta0="
+ }]
+}
+```
+
+### 3. Client Secret
+```json
+{
+ "ClientCredentials": [
+ {
+ "SourceType": "ClientSecret",
+ "ClientSecret": "your-secret-here"
+ }]
+}
+```
+
+
+### 4. Auto Decrypt Keys (for Token Decryption)
+```json
+{
+ "TokenDecryptionCredentials": [
+ {
+ "SourceType": "AutoDecryptKeys",
+ "DecryptKeysAuthenticationOptions": {
+ "ProtocolScheme": "Bearer",
+ "AcquireTokenOptions": {
+ "Tenant": "mytenant.onmicrosoftonline.com"
+ }
+ }
+ }]
+}
+```
+
+## C# Code Usage
+
+
+### 1. Managed Identity Credentials
+```csharp
+var credentialDescription = new CredentialDescription
+{
+ SourceType = CredentialSource.SignedAssertionFromManagedIdentity,
+ ManagedIdentityClientId = "GUID", // Optional for system-assigned managed identity
+ TokenExchangeUrl = "api://AzureADTokenExchangeSomeCloud1", // Optional
+ TokenExchangeAuthority = "https://login.microsoftonline.cloud2/33e01921-4d64-4f8c-a055-5bdaffd5e33d/v2.0" // Optional
+};
+```
+
+### 2. Certificate Credentials
+
+#### From Key Vault
+```csharp
+// Using property initialization
+var credentialDescription = new CredentialDescription
+{
+ SourceType = CredentialSource.KeyVault,
+ KeyVaultUrl = "https://msidentitywebsamples.vault.azure.net",
+ KeyVaultCertificateName = "MicrosoftIdentitySamplesCert"
+};
+
+// Using FromKeyVault method
+var credentialDescription = CredentialDescription.FromKeyVault(
+ "https://msidentitywebsamples.vault.azure.net",
+ "MicrosoftIdentitySamplesCert");
+```
+
+#### From Certificate Store (Using Thumbprint)
+```csharp
+// Using property initialization
+var credentialDescription = new CredentialDescription
+{
+ SourceType = CredentialSource.StoreWithThumbprint,
+ CertificateStorePath = "LocalMachine/My",
+ CertificateThumbprint = "962D129A...D18EFEB6961684"
+};
+
+// Using FromCertificateStore method
+var credentialDescription = CredentialDescription.FromCertificateStore(
+ "LocalMachine/My",
+ thumbprint: "962D129A...D18EFEB6961684");
+```
+
+#### From Certificate Store (Using Distinguished Name)
+```csharp
+// Using property initialization
+var credentialDescription = new CredentialDescription
+{
+ SourceType = CredentialSource.StoreWithDistinguishedName,
+ CertificateStorePath = "LocalMachine/My",
+ CertificateDistinguishedName = "CN=WebAppCallingWebApiCert"
+};
+
+// Using FromCertificateStore method
+var credentialDescription = CredentialDescription.FromCertificateStore(
+ "LocalMachine/My",
+ distinguishedName: "CN=WebAppCallingWebApiCert");
+```
+
+#### From File Path
+```csharp
+// Using property initialization
+var credentialDescription = new CredentialDescription
+{
+ SourceType = CredentialSource.Path,
+ CertificateDiskPath = "c:\\temp\\WebAppCallingWebApiCert.pfx",
+ CertificatePassword = "password"
+};
+
+// Using FromCertificatePath method
+var credentialDescription = CredentialDescription.FromCertificatePath(
+ "c:\\temp\\WebAppCallingWebApiCert.pfx",
+ "password");
+```
+
+#### Base64 Encoded
+```csharp
+// Using property initialization
+var credentialDescription = new CredentialDescription
+{
+ SourceType = CredentialSource.Base64Encoded,
+ Base64EncodedValue = "MIIDHzCgegA.....r1n8Ta0="
+};
+
+// Using FromBase64String method
+var credentialDescription = CredentialDescription.FromBase64String(
+ "MIIDHzCgegA.....r1n8Ta0=");
+```
+
+### 3. Client Secret
+```csharp
+var credentialDescription = new CredentialDescription
+{
+ SourceType = CredentialSource.ClientSecret,
+ ClientSecret = "your-secret-here"
+};
+```
+
+### 4. Auto Decrypt Keys (for Token Decryption)
+```csharp
+var credentialDescription = new CredentialDescription
+{
+ SourceType = CredentialSource.AutoDecryptKeys,
+ DecryptKeysAuthenticationOptions = new AuthorizationHeaderProviderOptions
+ {
+ ProtocolScheme = "Bearer",
+ AcquireTokenOptions = new AcquireTokenOptions
+ {
+ Tenant = "appHomeTenant.onmicrosoftonline.com"
+ }
+ }
+};
+```
+
+## Important Notes
+
+1. **Credential Types**:
+ - `Certificate`: Can be used for both client credentials and token decryption
+ - `Secret`: Only for client credentials
+ - `SignedAssertion`: Only for client credentials
+ - `DecryptKeys`: Only for token decryption
+
+2. **Security Best Practices**:
+ - For production environments:
+ A. Certificateless Authentication:
+ 1. Managed Identities (when running on Azure)
+ 2. Other certificateless authentication methods
+ - Benefits:
+ * No certificate management overhead
+ * Automatic credential rotation
+ * Reduced operational complexity
+ * Lower risk of credential exposure
+
+ B. Certificate-based Authentication:
+ 1. Azure Key Vault (most secure, recommended)
+ 2. Certificate Store (for Windows environments)
+ - Benefits:
+ * Strong cryptographic identity proof
+ * Compliance with PKI requirements
+ * Suitable for air-gapped environments
+ * Hardware security module (HSM) support
+
+ - For development/testing only:
+ - Client Secrets
+ - File-based certificates
+ - Base64 encoded certificates
+
+ Key considerations:
+ - Choose certificateless authentication when possible for simplified operations
+ - Use certificate-based authentication when:
+ * Regulatory compliance requires it
+ * You need cryptographic proof of identity
+ * Your environment has established PKI infrastructure
+ * You're working in air-gapped scenarios
+
+3. **Certificate Store Paths**:
+ - Format: `{StoreLocation}/{StoreName}`
+ - Common values:
+ - `CurrentUser/My`: User certificates
+ - `LocalMachine/My`: Computer certificates
+
+4. **Federation Identity Credential with Managed Identity**:
+ - For system-assigned managed identity, use `SignedAssertionFromManagedIdentity` source type without specifying `ManagedIdentityClientId`
+ - For user-assigned managed identity, specify the `ManagedIdentityClientId`
+
+5. **Custom Provider Extension**:
+ - Use `CredentialSource.CustomSignedAssertion` with:
+ - `CustomSignedAssertionProviderName`
+ - `CustomSignedAssertionProviderData` (Dictionary)
+
+## Decision Flow for Choosing Authentication Approach
+
+1. Do you want to avoid certificate management complexity?
+ - Yes: Consider certificateless authentication
+ * Ideal for cloud-native applications
+ * Simpler deployment and maintenance
+ * No certificate lifecycle management
+ - No: Continue with traditional certificate-based approach
+
+2. Are you running on Azure?
+ - Yes: Consider these options in order:
+ 1. Federation Identity Credential with Managed Identity (certificateless)
+ 2. Key Vault (certificate-based)
+ - No: Continue to next question
+
+3. Is this for production?
+ - Yes: Choose between:
+ 1. Certificateless authentication (if supported in your environment)
+ 2. Key Vault (preferred for certificate-based)
+ 3. Certificate Store (Windows environments)
+ - No: You can use any option, including client secrets and file-based certificates, but keep your secrets safe.
+
+4. Do you need credential rotation?
+ - Yes: Consider these options:
+ * Certificateless authentication (automatic rotation)
+ * Key Vault with managed certificates
+ * Certificate Store with Distinguished Name
+ - No: Any authentication option will work
+
+5. Do you need to share credentials across services?
+ - Yes: Use:
+ * User-assigned Managed Identity (certificateless)
+ * Key Vault (certificate-based)
+ - No: Any option suitable for your environment will work
+
+6. Are you implementing token decryption?
+ - Yes: Use:
+ * AutoDecryptKeys (preferred). This requires client credentials
+ * decrypt certificate using the Certificate-based options
+ - Yes: No
+
+7. Do you have compliance requirements for cryptographic proof of identity?
+ - Yes: Use traditional certificate-based authentication
+ - No: Consider certificateless authentication for simplified operations