From 8535c961112c82c7f105c901b8de02808c52a648 Mon Sep 17 00:00:00 2001 From: Ray Luo Date: Thu, 19 Jun 2025 09:33:26 -0700 Subject: [PATCH 1/2] Document how to use sha256 for client credential --- msal/application.py | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/msal/application.py b/msal/application.py index 24ef91d7..3f160a85 100644 --- a/msal/application.py +++ b/msal/application.py @@ -280,6 +280,9 @@ def __init__( .. admonition:: Support using a certificate in X.509 (.pem) format + Deprecated because it uses SHA-1 thumbprint. + Please use the .pfx option documented later in this page. + Feed in a dict in this form:: { @@ -302,6 +305,9 @@ def __init__( `_ is an approach to allow easier certificate rotation. + Deprecated because it uses SHA-1 thumbprint. + Please use the .pfx option documented later in this page. + *Added in version 0.5.0*:: { @@ -338,6 +344,8 @@ def __init__( .. admonition:: Supporting reading client certificates from PFX files + This usage will automatically use SHA-256 thumbprint of the certificate. + *Added in version 1.29.0*: Feed in a dictionary containing the path to a PFX file:: @@ -352,6 +360,12 @@ def __init__( .. admonition:: Support Subject Name/Issuer Auth with a cert in .pfx + `Subject Name/Issuer Auth + `_ + is an approach to allow easier certificate rotation. + + This usage will automatically use SHA-256 thumbprint of the certificate. + *Added in version 1.30.0*: If your .pfx file contains both the private key and public cert, you can opt in for Subject Name/Issuer Auth like this:: From 30938169514383d51ee3841a579c5d3a16205191 Mon Sep 17 00:00:00 2001 From: Ray Luo Date: Mon, 23 Jun 2025 22:50:06 -0700 Subject: [PATCH 2/2] Consolidate 6 boxes into 4 --- msal/application.py | 50 +++++++++++---------------------------------- 1 file changed, 12 insertions(+), 38 deletions(-) diff --git a/msal/application.py b/msal/application.py index 3f160a85..ce003f16 100644 --- a/msal/application.py +++ b/msal/application.py @@ -280,15 +280,17 @@ def __init__( .. admonition:: Support using a certificate in X.509 (.pem) format - Deprecated because it uses SHA-1 thumbprint. + Deprecated because it uses SHA-1 thumbprint, + unless you are still using ADFS which supports SHA-1 thumbprint only. Please use the .pfx option documented later in this page. Feed in a dict in this form:: { "private_key": "...-----BEGIN PRIVATE KEY-----... in PEM format", - "thumbprint": "A1B2C3D4E5F6...", - "passphrase": "Passphrase if the private_key is encrypted (Optional. Added in version 1.6.0)", + "thumbprint": "An SHA-1 thumbprint such as A1B2C3D4E5F6...", + "passphrase": "Needed if the private_key is encrypted (Added in version 1.6.0)", + "public_certificate": "...-----BEGIN CERTIFICATE-----...", # Needed if you use Subject Name/Issuer auth. Added in version 0.5.0. } MSAL Python requires a "private_key" in PEM format. @@ -299,28 +301,11 @@ def __init__( The thumbprint is available in your app's registration in Azure Portal. Alternatively, you can `calculate the thumbprint `_. - .. admonition:: Support Subject Name/Issuer Auth with a cert in .pem - - `Subject Name/Issuer Auth - `_ - is an approach to allow easier certificate rotation. - - Deprecated because it uses SHA-1 thumbprint. - Please use the .pfx option documented later in this page. - - *Added in version 0.5.0*:: - - { - "private_key": "...-----BEGIN PRIVATE KEY-----... in PEM format", - "thumbprint": "A1B2C3D4E5F6...", - "public_certificate": "...-----BEGIN CERTIFICATE-----...", - "passphrase": "Passphrase if the private_key is encrypted (Optional. Added in version 1.6.0)", - } - ``public_certificate`` (optional) is public key certificate - which will be sent through 'x5c' JWT header only for - subject name and issuer authentication to support cert auto rolls. - + which will be sent through 'x5c' JWT header. + This is useful when you use `Subject Name/Issuer Authentication + `_ + which is an approach to allow easier certificate rotation. Per `specs `_, "the certificate containing the public key corresponding to the key used to digitally sign the @@ -350,7 +335,8 @@ def __init__( Feed in a dictionary containing the path to a PFX file:: { - "private_key_pfx_path": "/path/to/your.pfx", + "private_key_pfx_path": "/path/to/your.pfx", # Added in version 1.29.0 + "public_certificate": True, # Only needed if you use Subject Name/Issuer auth. Added in version 1.30.0 "passphrase": "Passphrase if the private_key is encrypted (Optional)", } @@ -358,23 +344,11 @@ def __init__( openssl pkcs12 -export -out certificate.pfx -inkey privateKey.key -in certificate.pem - .. admonition:: Support Subject Name/Issuer Auth with a cert in .pfx - `Subject Name/Issuer Auth `_ is an approach to allow easier certificate rotation. - - This usage will automatically use SHA-256 thumbprint of the certificate. - - *Added in version 1.30.0*: If your .pfx file contains both the private key and public cert, - you can opt in for Subject Name/Issuer Auth like this:: - - { - "private_key_pfx_path": "/path/to/your.pfx", - "public_certificate": True, - "passphrase": "Passphrase if the private_key is encrypted (Optional)", - } + you can opt in for Subject Name/Issuer Auth by setting "public_certificate" to ``True``. :type client_credential: Union[dict, str, None]