Skip to content

Document how to enable sha256 for client credential #833

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 2 commits into
base: dev
Choose a base branch
from
+19 −31
Open

Document how to enable sha256 for client credential #833

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
8535c96
Document how to use sha256 for client credential
rayluo Jun 19, 2025
3093816
Consolidate 6 boxes into 4
rayluo Jun 24, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
50 changes: 19 additions & 31 deletions msal/application.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -280,12 +280,17 @@ def __init__(

.. admonition:: Support using a certificate in X.509 (.pem) format

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.
Expand All @@ -296,25 +301,11 @@ def __init__(
The thumbprint is available in your app's registration in Azure Portal.
Alternatively, you can `calculate the thumbprint <https://github.com/Azure/azure-sdk-for-python/blob/07d10639d7e47f4852eaeb74aef5d569db499d6e/sdk/identity/azure-identity/azure/identity/_credentials/certificate.py#L94-L97>`_.

.. admonition:: Support Subject Name/Issuer Auth with a cert in .pem

`Subject Name/Issuer Auth
<https://github.com/AzureAD/microsoft-authentication-library-for-python/issues/60>`_
is an approach to allow easier certificate rotation.

*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
<https://github.com/AzureAD/microsoft-authentication-library-for-python/issues/60>`_
which is an approach to allow easier certificate rotation.
Per `specs <https://tools.ietf.org/html/rfc7515#section-4.1.6>`_,
"the certificate containing
the public key corresponding to the key used to digitally sign the
Expand All @@ -338,29 +329,26 @@ 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::

{
"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)",
}

The following command will generate a .pfx file from your .key and .pem file::

openssl pkcs12 -export -out certificate.pfx -inkey privateKey.key -in certificate.pem

.. admonition:: Support Subject Name/Issuer Auth with a cert in .pfx

*Added in version 1.30.0*:
`Subject Name/Issuer Auth
<https://github.com/AzureAD/microsoft-authentication-library-for-python/issues/60>`_
is an approach to allow easier certificate rotation.
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]

Expand Down