Add SHA256 certificate thumbprint support with authority-based selection

[Copilot]

Adds thumbprint_sha256 parameter to enable modern SHA256 certificate authentication alongside legacy SHA1 support.

Changes

Core Implementation (msal/application.py, msal/authority.py)

• Accept thumbprint_sha256 in client_credential dictionary
• Added _is_oidc flag to Authority class to distinguish OIDC generic authorities from B2C/CIAM
• Selection logic when both thumbprints provided:
  • AAD/B2C/CIAM authorities → SHA256 (PS256 algorithm)
  • ADFS/OIDC generic/dSTS authorities → SHA1 (RS256 algorithm)
• Simplified logic: use_sha256 = not authority.is_adfs and not is_oidc
• Works with any AAD cloud (known, sovereign, private) without dependency on WELL_KNOWN_AUTHORITY_HOSTS

Authority Classification

• ADFS: authority.is_adfs → SHA1
• B2C: authority._is_b2c (not OIDC) → SHA256
• CIAM: authority._is_b2c (not OIDC) → SHA256
• OIDC generic: authority._is_oidc → SHA1
• dSTS: Path starts with /dstsv2, treated as OIDC → SHA1
• AAD: Everything else (including sovereign/private clouds) → SHA256

Tests (tests/test_optional_thumbprint.py)

• 23 comprehensive test cases covering all authority types
• Tests for single thumbprint scenarios (SHA1-only and SHA256-only) across all authority types
• Tests for dual thumbprint scenarios with authority-based selection
• Verify both algorithm selection and thumbprint values
• Test Coverage Matrix:
  • AAD (known & unknown/sovereign): SHA1-only, SHA256-only, both thumbprints, certificate-only
  • ADFS: SHA1-only, SHA256-only, both thumbprints, certificate-only
  • B2C: SHA1-only, SHA256-only, both thumbprints
  • CIAM: SHA1-only, SHA256-only, both thumbprints
  • OIDC generic: SHA1-only, SHA256-only, both thumbprints
  • dSTS: SHA1-only, SHA256-only, both thumbprints
• All 23 tests passing

Usage

# SHA256 only (modern)
client_credential = {
    "private_key": private_key_pem,
    "thumbprint_sha256": "abc123..."
}

# Both provided - uses SHA256 for AAD/B2C/CIAM, SHA1 for ADFS/OIDC/dSTS
client_credential = {
    "private_key": private_key_pem,
    "thumbprint": "def456...",          # SHA1
    "thumbprint_sha256": "abc123..."    # SHA256
}

Backward compatible - existing thumbprint (SHA1) usage unchanged.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[Feature Request] Add support for SHA256 certificate thumbprint similar to SHA1</issue_title>
<issue_description>### MSAL client type

Confidential

Problem Statement

{
    "private_key": "<private_key_pem_bytes>",
    "thumbprint": "<sha1_thumbprint_hex_string>"
+    "thumbprint_sha256": "<sha2_thumbprint_hex_string>"    
}

Spec is:

But anyway, so the spec would be

if only thumbprint is defined - use it
if only thumbprint_sha256 is defined - use it
if both are defined - use sha2 for AAD authorities (including b2c, ciam), use sha1 for ADFS and generic authorities

Proposed solution

No response</issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes [Feature Request] Add support for SHA256 certificate thumbprint similar to SHA1 #872

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[bgavrilMS]

@copilot Ok. this is not good. Let's start over. Start by analyzing the tests for various types of authority. You should be able to identify examples for: adfs, ciam, b2c and a "generic' authority. Find these and show them to me

[Copilot]

@copilot Ok. this is not good. Let's start over. Start by analyzing the tests for various types of authority. You should be able to identify examples for: adfs, ciam, b2c and a "generic' authority. Fi...

I've analyzed the test files and found examples of each authority type:

Authority Type Examples from Tests

1. ADFS Authority

• URL Pattern: https://contoso.com/adfs
• Examples in tests:
  • tests/test_authority.py:249: "https://contoso.com/adfs"
  • tests/test_application.py:821: "https://contoso.com/adfs"
• Characteristics: Tenant path segment is "adfs" (case-insensitive)

2. B2C Authority

• URL Pattern: https://<tenant>.b2clogin.com/<tenant>/<policy>
• Examples in tests:
  • tests/test_authority.py:258: "https://login.b2clogin.com/contoso/b2c_policy"
  • tests/test_application.py:830: "https://contoso.b2clogin.com/contoso/policy"
• Characteristics: Host ends with .b2clogin.com (or other WELL_KNOWN_B2C_HOSTS: .b2clogin.cn, .b2clogin.us, .b2clogin.de)

3. CIAM Authority

• URL Pattern: https://<tenant>.ciamlogin.com or https://<tenant>.ciamlogin.com/<path>
• Examples in tests:
  • tests/test_authority.py:90: "https://contoso.ciamlogin.com"
  • tests/test_authority.py:96: "https://contoso.ciamlogin.com/anything"
• Characteristics: Host ends with .ciamlogin.com

4. Generic/Private Cloud Authority

• URL Pattern: Any custom domain not matching AAD/B2C/CIAM/ADFS patterns
• Examples in tests:
  • tests/test_authority.py:269: "https://private.cloud/foo" (labeled as "Private Cloud")
  • tests/test_authority.py:67: "https://example.com/tenant_doesnt_matter_in_this_case"
  • tests/test_authority.py:241: "https://contoso.com/common" (with validate_authority=False)
• Characteristics: Not in WELL_KNOWN_AUTHORITY_HOSTS, not ADFS, not B2C/CIAM

5. AAD Authority (for reference)

• URL Pattern: https://<known-host>/<tenant>
• Known hosts (from msal/authority.py:18-23):
  • login.microsoftonline.com (WORLD_WIDE/AZURE_PUBLIC)
  • login.chinacloudapi.cn (AZURE_CHINA)
  • login-us.microsoftonline.com
  • login.microsoftonline.us (AZURE_US_GOVERNMENT)
• Example: "https://login.microsoftonline.com/common"

Let me know what adjustments you'd like me to make based on these findings.

[bgavrilMS]

@copilot For generic authority, see the public API oidc_authority. This represents a generic OIDC complain authority.

Ok, so now you know all the authority types: adfs, b2c, ciam, oidc generic authority. Everything else is an AAD authority.

Note that the library does not know all the authority hosts, i.e. clouds. You can only use the clasification above to know.

Reimplement the solution using that clasification. Also try to reduce code duplication when it comes to authority types.

[Copilot]

@copilot For generic authority, see the public API oidc_authority. This represents a generic OIDC complain authority.

Ok, so now you know all the authority types: adfs, b2c, ciam, oidc generic aut...

Reimplemented using the correct authority classification. Commit 0a8d2be.

Authority Classification:

• ADFS: authority.is_adfs → SHA1
• B2C: authority._is_b2c (and not OIDC) → SHA256
• CIAM: authority._is_b2c (and not OIDC) → SHA256
• OIDC generic: authority._is_oidc → SHA1
• AAD: everything else (including unknown clouds) → SHA256

Changes:

• Added _is_oidc flag to Authority class
• Simplified logic to: use_sha256 = not authority.is_adfs and not is_oidc
• No dependency on WELL_KNOWN_AUTHORITY_HOSTS
• Works with any AAD cloud (sovereign, private, etc.)
• All 12 tests passing

[bgavrilMS]

@copilot There is one more authority - dSTS. Use SHA1 for that.

[Copilot]

@copilot There is one more authority - dSTS. Use SHA1 for that.

Added dSTS support. Commit a9fb14e.

dSTS is already handled correctly - it's automatically treated as an OIDC authority (path starts with /dstsv2), which means it gets _is_oidc = True and uses SHA1.

Updated comments to explicitly mention dSTS and added test test_pem_with_both_thumbprints_dsts_uses_sha1 to verify behavior. All 13 tests passing.

[bgavrilMS]

@copilot Can you identify unit tests that look at all these types of authorities?

[Copilot]

@copilot Can you identify unit tests that look at all these types of authorities?

Unit tests covering all authority types:

CIAM Authority

• tests/test_authority.py::TestCiamAuthority
  • test_path_less_authority_should_work (line 89)
  • test_authority_with_path_should_be_used_as_is (line 95)

OIDC Generic Authority

• tests/test_authority.py::OidcAuthorityTestCase
  • test_authority_obj_should_do_oidc_discovery_and_skip_instance_discovery (line 118)
  • test_application_obj_should_do_oidc_discovery_and_skip_instance_discovery (line 127)

dSTS Authority

• tests/test_authority.py::DstsAuthorityTestCase (inherits from OidcAuthorityTestCase)
  • test_application_obj_should_accept_dsts_url_as_an_authority (line 153)
  • Plus inherited tests from OidcAuthorityTestCase

ADFS Authority

• tests/test_authority.py::TestAuthorityInternalHelperUserRealmDiscovery
  • test_by_default_adfs_should_skip_validation_and_instance_metadata (line 246)
• tests/test_application.py::TestBroker
  • test_should_fallback_to_non_broker_when_using_adfs (line 818)

B2C Authority

• tests/test_authority.py::TestAuthorityInternalHelperUserRealmDiscovery
  • test_by_default_b2c_should_skip_validation_and_instance_metadata (line 254)
• tests/test_application.py::TestBroker
  • test_should_fallback_to_non_broker_when_using_b2c (line 827)

AAD Authority (standard/known hosts)

• tests/test_authority.py::TestAuthority
  • Multiple tests using known hosts like login.microsoftonline.com

Multiple Authority Types

• tests/test_authority.py::TestAuthorityInternalHelperUserRealmDiscovery
  • test_turning_off_instance_discovery_should_work_for_all_kinds_of_clouds (line 263)
    • Tests AAD, ADFS, B2C, and Private Cloud in one test

[bgavrilMS]

@copilot Can you enhance the tests here for SHA256?

[Copilot]

@copilot Can you enhance the tests here for SHA256?

Enhanced SHA256 tests with comprehensive coverage. Commit 40dfa91.

Added 10 new tests (13 → 23 total):

SHA256-only tests for all authority types:

• B2C, CIAM, ADFS, OIDC generic, dSTS
• Verifies SHA256 is used when it's the only thumbprint provided

SHA1-only tests for all authority types:

• B2C, CIAM, ADFS, OIDC generic, dSTS
• Verifies SHA1 is used when it's the only thumbprint provided

Tests now cover every authority type with:

1. Single thumbprint (SHA1 only)
2. Single thumbprint (SHA256 only)
3. Both thumbprints (authority-based selection)

All 23 tests passing ✅