Document how to enable sha256 for client credential

[rayluo]

This PR updates the documentation for how to enable SHA-256 thumbprint for client credentials.

Note that the current interface does not take an explicit SHA-256 thumbprint. It will automatically use the SHA-256 thumbprint of the certificate when reading client certificates from PFX files.

The new doc can be read from this doc staging site. The new sentences are scattered in 4 different purple boxes.

This PR will resolve #832 .

[Robbie-Microsoft]

It's deprecated, but does it still work for backwards compatibility? Should you note that?

[rayluo]

My understanding of the term Deprecation is aligned with this answer:

Deprecated means that it is still in use, but only for historical purposes and it will be removed probably in the next big release. It is recommended that you do not use deprecated functions or features - even if they are present in the current library for example.

So, yes, it still works for backwards compatibility. If that is OK with you, I intend to not add a "it still works for backwards compatibility" statement to the docs here, otherwise we might need to retrofit the same sentence into maybe a dozen deprecated parameters here and there in our docs.

[bgavrilMS]

Robbie is right though. ADFS still uses this. So it's not fully deprecated.

The pfx solution is not yet fit for purpose, since it requires the cert to be on disk.

How about adding a thumbprintSha256 to the dictionary and adding a note that thumbprint is deprecated except for ADFS instead?

Internally, MSAL will choose thumbpritnSha256 if it is set, or fallback to thumbprint if it is not set.

[Robbie-Microsoft]

I'm confused as to how this all works... the changes in this PR are reflected on the document staging site? Is that correct?

There are 6 purple boxes there btw, not 4 like you've indicted above. And the changes in this PR don't seem to line up with the content of the purple boxes.

[rayluo]

The new doc can be read from this doc staging site. The new sentences are scattered in 4 different purple boxes.

I'm confused as to how this all works... the changes in this PR are reflected on the document staging site? Is that correct?

There are 6 purple boxes there btw, not 4 like you've indicted above. And the changes in this PR don't seem to line up with the content of the purple boxes.

Sorry about the confusion. There are 6 purple boxes for 6 scenarios. This PR deprecates 2 of them and added SHA-2 content into another 2, so the changes are "scattered in FOUR (not among six) different purple boxes".

Yes, the changes in this PR are reflected on the document staging site. If necessary, you can compare it with the current status-quo doc.
Before (i.e. the current latest): https://msal-python.readthedocs.io/en/latest/#msal.ClientApplication.params.client_credential
After (i.e. the staging): https://msal-python.readthedocs.io/en/docs-staging/#msal.ClientApplication.params.client_credential

[bgavrilMS]

The x509 from disk is not a good solution, as per our advisors.

[bgavrilMS]

The new doc can be read from this doc staging site. The new sentences are scattered in 4 different purple boxes.

I'm confused as to how this all works... the changes in this PR are reflected on the document staging site? Is that correct?
There are 6 purple boxes there btw, not 4 like you've indicted above. And the changes in this PR don't seem to line up with the content of the purple boxes.

Sorry about the confusion. There are 6 purple boxes for 6 scenarios. This PR deprecates 2 of them and added SHA-2 content into another 2, so the changes are "scattered in FOUR (not six) different purple boxes".

Yes, the changes in this PR are reflected on the document staging site. If necessary, you can compare it with the current status-quo doc. Before (i.e. the current latest): https://msal-python.readthedocs.io/en/latest/#msal.ClientApplication.params.client_credential After (i.e. the staging): https://msal-python.readthedocs.io/en/docs-staging/#msal.ClientApplication.params.client_credential

suggestion: I agree with @Robbie-Microsoft that there are too many boxes. Maybe you should combine the "normal cert" with the "sn/i cert" boxes?

[rayluo]

• Good point on the deprecation is only for non-ADFS. With ADFS, customer still needs to use SHA-1. Docs has been modified accordingly.
• Those 6 boxes were historically added in some 5 or 6 different versions, so they became that way. But you are both right that 6 sounds too much. The latest commit consolidated them into 4.
• I have updated the PR accordingly, and the doc staging site is also updated.
• Yes, we shall also support loading a cert without a file. Shall we create a dedicate github issue to track that enhancement? Meanwhile, this PR correctly represents the status quo of the current certificate usage of the MSAL Python versions already shipped. So, this PR in itself does not make situation any worse. Perhaps we can still review and merge this PR first. Shall we?

[rayluo]

• Good point on the deprecation is only for non-ADFS. With ADFS, customer still needs to use SHA-1. Docs has been modified accordingly.
• Those 6 boxes were historically added in some 5 or 6 different versions, so they became that way. But you are both right that 6 sounds too much. The latest commit consolidated them into 4.
• I have updated the PR accordingly, and the doc staging site is also updated.
• Yes, we shall also support loading a cert without a file. Shall we create a dedicate github issue to track that enhancement? Meanwhile, this PR correctly represents the status quo of the current certificate usage of the MSAL Python versions already shipped. So, this PR in itself does not make situation any worse. Perhaps we can still review and merge this PR first. Shall we?

Hi @bgavrilMS , this PR improves the docs for the existing MSAL Python behaviors. May I get your approval to merge this PR as-is and get back to other improvement ideas in new PRs?