Skip to content

Commit 06679f5

Browse files
Dickson-MwendiaDickson-Mwendia
authored
Merge pull request #141 from MicrosoftDocs/main
Sync main with live branch
2 parents 7d7620c + b0ef9a0 commit 06679f5

6 files changed

Lines changed: 2183 additions & 408 deletions

‎python/docs-ref-autogen/msal/msal.application.ClientApplication.yml‎

Lines changed: 84 additions & 60 deletions
Original file line numberDiff line numberDiff line change
@@ -27,32 +27,28 @@ constructor:
2727
\ here.\n\nFor <xref:msal.application.ConfidentialClientApplication>,\nit supports\
2828
\ many different input formats for different scenarios.\n\n\n\n## Support using\
2929
\ a client secret.Just feed in a string, such as `\"your client secret\"`.\n\
30-
\n\n\n## Support using a certificate in X.509 (.pem) formatFeed in a dict in\
31-
\ this form:\n\n<!-- literal_block {\"ids\": [], \"classes\": [], \"names\"\
32-
: [], \"dupnames\": [], \"backrefs\": [], \"xml:space\": \"preserve\", \"language\"\
33-
: \"default\", \"force\": false, \"linenos\": false} -->\n\n````default\n\n\
34-
\ {\n \"private_key\": \"...-----BEGIN PRIVATE KEY-----... in PEM format\"\
35-
,\n \"thumbprint\": \"A1B2C3D4E5F6...\",\n \"passphrase\": \"Passphrase\
36-
\ if the private_key is encrypted (Optional. Added in version 1.6.0)\",\n \
37-
\ }\n ````\n\nMSAL Python requires a \"private_key\" in PEM format.\nIf your\
38-
\ cert is in PKCS12 (.pfx) format,\nyou can convert it to X.509 (.pem) format,\n\
39-
by `openssl pkcs12 -in file.pfx -out file.pem -nodes`.The thumbprint is available\
40-
\ in your app's registration in Azure Portal.\nAlternatively, you can [calculate\
41-
\ the thumbprint](https://github.com/Azure/azure-sdk-for-python/blob/07d10639d7e47f4852eaeb74aef5d569db499d6e/sdk/identity/azure-identity/azure/identity/_credentials/certificate.py#L94-L97).\n\
42-
\n\n\n## Support Subject Name/Issuer Auth with a cert in .pem[Subject Name/Issuer\
43-
\ Auth](https://github.com/AzureAD/microsoft-authentication-library-for-python/issues/60)\n\
44-
is an approach to allow easier certificate rotation.*Added in version 0.5.0*:\n\
45-
\n<!-- literal_block {\"ids\": [], \"classes\": [], \"names\": [], \"dupnames\"\
46-
: [], \"backrefs\": [], \"xml:space\": \"preserve\", \"language\": \"default\"\
47-
, \"force\": false, \"linenos\": false} -->\n\n````default\n\n {\n \"\
48-
private_key\": \"...-----BEGIN PRIVATE KEY-----... in PEM format\",\n \
49-
\ \"thumbprint\": \"A1B2C3D4E5F6...\",\n \"public_certificate\": \"...-----BEGIN\
50-
\ CERTIFICATE-----...\",\n \"passphrase\": \"Passphrase if the private_key\
51-
\ is encrypted (Optional. Added in version 1.6.0)\",\n }\n ````\n\n`public_certificate`\
30+
\n\n\n## Support using a certificate in X.509 (.pem) formatDeprecated because\
31+
\ it uses SHA-1 thumbprint,\nunless you are still using ADFS which supports\
32+
\ SHA-1 thumbprint only.\nPlease use the .pfx option documented later in this\
33+
\ page.Feed in a dict in this form:\n\n<!-- literal_block {\"ids\": [], \"classes\"\
34+
: [], \"names\": [], \"dupnames\": [], \"backrefs\": [], \"xml:space\": \"preserve\"\
35+
, \"language\": \"default\", \"force\": false, \"linenos\": false} -->\n\n````default\n\
36+
\n {\n \"private_key\": \"...-----BEGIN PRIVATE KEY-----... in PEM format\"\
37+
,\n \"thumbprint\": \"An SHA-1 thumbprint such as A1B2C3D4E5F6...\"\n\
38+
\ \"Changed in version 1.35.0, if thumbprint is absent\"\n \
39+
\ \"and a public_certificate is present, MSAL will\"\n \"automatically\
40+
\ calculate an SHA-256 thumbprint instead.\",\n \"passphrase\": \"Needed\
41+
\ if the private_key is encrypted (Added in version 1.6.0)\",\n \"public_certificate\"\
42+
: \"...-----BEGIN CERTIFICATE-----...\", # Needed if you use Subject Name/Issuer\
43+
\ auth. Added in version 0.5.0.\n }\n ````\n\nMSAL Python requires a \"\
44+
private_key\" in PEM format.\nIf your cert is in PKCS12 (.pfx) format,\nyou\
45+
\ can convert it to X.509 (.pem) format,\nby `openssl pkcs12 -in file.pfx -out\
46+
\ file.pem -nodes`.The thumbprint is available in your app's registration in\
47+
\ Azure Portal.\nAlternatively, 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).`public_certificate`\
5248
\ (optional) is public key certificate\nwhich will be sent through 'x5c' JWT\
53-
\ header only for\nsubject name and issuer authentication to support cert auto\
54-
\ rolls.Per [specs](https://tools.ietf.org/html/rfc7515#section-4.1.6),\n\"\
55-
the certificate containing\nthe public key corresponding to the key used to\
49+
\ header.\nThis is useful when you use [Subject Name/Issuer Authentication](https://github.com/AzureAD/microsoft-authentication-library-for-python/issues/60)\n\
50+
which is an approach to allow easier certificate rotation.\nPer [specs](https://tools.ietf.org/html/rfc7515#section-4.1.6),\n\
51+
\"the certificate containing\nthe public key corresponding to the key used to\
5652
\ digitally sign the\nJWS MUST be the first certificate. This MAY be followed\
5753
\ by\nadditional certificates, with each subsequent certificate being the\n\
5854
one used to certify the previous one.\"\nHowever, your certificate's issuer\
@@ -66,26 +62,25 @@ constructor:
6662
: [], \"backrefs\": [], \"xml:space\": \"preserve\", \"language\": \"default\"\
6763
, \"force\": false, \"linenos\": false} -->\n\n````default\n\n {\n \"\
6864
client_assertion\": \"...a JWT with claims aud, exp, iss, jti, nbf, and sub...\"\
69-
\n }\n ````\n\n\n\n## Supporting reading client cerficates from PFX files*Added\
65+
\n }\n ````\n\n\n\n## Supporting reading client certificates from PFX filesThis\
66+
\ usage will automatically use SHA-256 thumbprint of the certificate.*Added\
7067
\ in version 1.29.0*:\nFeed in a dictionary containing the path to a PFX file:\n\
7168
\n<!-- literal_block {\"ids\": [], \"classes\": [], \"names\": [], \"dupnames\"\
7269
: [], \"backrefs\": [], \"xml:space\": \"preserve\", \"language\": \"default\"\
7370
, \"force\": false, \"linenos\": false} -->\n\n````default\n\n {\n \"\
74-
private_key_pfx_path\": \"/path/to/your.pfx\",\n \"passphrase\": \"Passphrase\
75-
\ if the private_key is encrypted (Optional)\",\n }\n ````\n\nThe following\
76-
\ command will generate a .pfx file from your .key and .pem file:\n\n<!-- literal_block\
71+
private_key_pfx_path\": \"/path/to/your.pfx\", # Added in version 1.29.0\n\
72+
\ \"public_certificate\": True, # Only needed if you use Subject Name/Issuer\
73+
\ auth. Added in version 1.30.0\n \"passphrase\": \"Passphrase if the\
74+
\ private_key is encrypted (Optional)\",\n }\n ````\n\nThe following command\
75+
\ will generate a .pfx file from your .key and .pem file:\n\n<!-- literal_block\
7776
\ {\"ids\": [], \"classes\": [], \"names\": [], \"dupnames\": [], \"backrefs\"\
7877
: [], \"xml:space\": \"preserve\", \"language\": \"default\", \"force\": false,\
7978
\ \"linenos\": false} -->\n\n````default\n\n openssl pkcs12 -export -out certificate.pfx\
80-
\ -inkey privateKey.key -in certificate.pem\n ````\n\n\n\n## Support Subject\
81-
\ Name/Issuer Auth with a cert in .pfx*Added in version 1.30.0*:\nIf your .pfx\
82-
\ file contains both the private key and public cert,\nyou can opt in for Subject\
83-
\ Name/Issuer Auth like this:\n\n<!-- literal_block {\"ids\": [], \"classes\"\
84-
: [], \"names\": [], \"dupnames\": [], \"backrefs\": [], \"xml:space\": \"preserve\"\
85-
, \"language\": \"default\", \"force\": false, \"linenos\": false} -->\n\n````default\n\
86-
\n {\n \"private_key_pfx_path\": \"/path/to/your.pfx\",\n \"public_certificate\"\
87-
: True,\n \"passphrase\": \"Passphrase if the private_key is encrypted\
88-
\ (Optional)\",\n }\n ````"
79+
\ -inkey privateKey.key -in certificate.pem\n ````\n\n[Subject Name/Issuer\
80+
\ Auth](https://github.com/AzureAD/microsoft-authentication-library-for-python/issues/60)\n\
81+
is an approach to allow easier certificate rotation.\nIf your .pfx file contains\
82+
\ both the private key and public cert,\nyou can opt in for Subject Name/Issuer\
83+
\ Auth by setting \"public_certificate\" to `True`."
8984
defaultValue: None
9085
types:
9186
- <xref:typing.Union>[<xref:dict>, <xref:str>, <xref:None>]
@@ -267,25 +262,30 @@ constructor:
267262
\ in some situations.\n\nThis `http_cache` parameter accepts any dict-like object.\n\
268263
If not provided, MSAL will use an in-memory dict.\n\nIf your app is a command-line\
269264
\ app (CLI),\nyou would want to persist your http_cache across different CLI\
270-
\ runs.\nThe following recipe shows a way to do so:\n\n<!-- literal_block {\"\
271-
ids\": [], \"classes\": [], \"names\": [], \"dupnames\": [], \"backrefs\": [],\
272-
\ \"xml:space\": \"preserve\", \"language\": \"default\", \"force\": false,\
273-
\ \"linenos\": false} -->\n\n````default\n\n # Just add the following lines\
274-
\ at the beginning of your CLI script\n import sys, atexit, pickle\n http_cache_filename\
275-
\ = sys.argv[0] + \".http_cache\"\n try:\n with open(http_cache_filename,\
276-
\ \"rb\") as f:\n persisted_http_cache = pickle.load(f) # Take a\
277-
\ snapshot\n except (\n FileNotFoundError, # Or IOError in Python\
278-
\ 2\n pickle.UnpicklingError, # A corrupted http cache file\n \
279-
\ ):\n persisted_http_cache = {} # Recover by starting afresh\n\
280-
\ atexit.register(lambda: pickle.dump(\n # When exit, flush it back\
281-
\ to the file.\n # It may occasionally overwrite another process's concurrent\
282-
\ write,\n # but that is fine. Subsequent runs will reach eventual consistency.\n\
283-
\ persisted_http_cache, open(http_cache_file, \"wb\")))\n\n # And then\
284-
\ you can implement your app as you normally would\n app = msal.PublicClientApplication(\n\
285-
\ \"your_client_id\",\n ...,\n http_cache=persisted_http_cache,\
286-
\ # Utilize persisted_http_cache\n ...,\n #token_cache=..., #\
287-
\ You may combine the old token_cache trick\n # Please refer to token_cache\
288-
\ recipe at\n # https://msal-python.readthedocs.io/en/latest/#msal.SerializableTokenCache\n\
265+
\ runs.\nThe persisted file's format may change due to, but not limited to,\n\
266+
[unstable protocol](https://docs.python.org/3/library/pickle.html#data-stream-format),\n\
267+
so your implementation shall tolerate unexpected loading errors.\nThe following\
268+
\ recipe shows a way to do so:\n\n<!-- literal_block {\"ids\": [], \"classes\"\
269+
: [], \"names\": [], \"dupnames\": [], \"backrefs\": [], \"xml:space\": \"preserve\"\
270+
, \"language\": \"default\", \"force\": false, \"linenos\": false} -->\n\n````default\n\
271+
\n # Just add the following lines at the beginning of your CLI script\n \
272+
\ import sys, atexit, pickle, logging\n http_cache_filename = sys.argv[0]\
273+
\ + \".http_cache\"\n try:\n with open(http_cache_filename, \"rb\")\
274+
\ as f:\n persisted_http_cache = pickle.load(f) # Take a snapshot\n\
275+
\ except (\n FileNotFoundError, # Or IOError in Python 2\n \
276+
\ pickle.UnpicklingError, # A corrupted http cache file\n AttributeError,\
277+
\ # Cache created by a different version of MSAL\n ):\n persisted_http_cache\
278+
\ = {} # Recover by starting afresh\n except: # Unexpected exceptions\n\
279+
\ logging.exception(\"You may want to debug this\")\n persisted_http_cache\
280+
\ = {} # Recover by starting afresh\n atexit.register(lambda: pickle.dump(\n\
281+
\ # When exit, flush it back to the file.\n # It may occasionally\
282+
\ overwrite another process's concurrent write,\n # but that is fine.\
283+
\ Subsequent runs will reach eventual consistency.\n persisted_http_cache,\
284+
\ open(http_cache_file, \"wb\")))\n\n # And then you can implement your app\
285+
\ as you normally would\n app = msal.PublicClientApplication(\n \"your_client_id\"\
286+
,\n ...,\n http_cache=persisted_http_cache, # Utilize persisted_http_cache\n\
287+
\ ...,\n #token_cache=..., # You may combine the old token_cache\
288+
\ trick\n # Please refer to token_cache recipe at\n # https://msal-python.readthedocs.io/en/latest/#msal.SerializableTokenCache\n\
289289
\ )\n app.acquire_token_interactive([\"your\", \"scope\"], ...)\n \
290290
\ ````\n\nContent inside `http_cache` are cheap to obtain.\nThere is no need\
291291
\ to share them among different apps.\n\nContent inside `http_cache` will contain\
@@ -531,7 +531,14 @@ methods:
531531
532532
See this page for constraints of Username Password Flow.
533533
534-
[https://github.com/AzureAD/microsoft-authentication-library-for-python/wiki/Username-Password-Authentication](https://github.com/AzureAD/microsoft-authentication-library-for-python/wiki/Username-Password-Authentication)'
534+
[https://github.com/AzureAD/microsoft-authentication-library-for-python/wiki/Username-Password-Authentication](https://github.com/AzureAD/microsoft-authentication-library-for-python/wiki/Username-Password-Authentication)
535+
536+
537+
[Deprecated] This API is deprecated for public client flows and will be
538+
539+
removed in a future release. Use a more secure flow instead.
540+
541+
Migration guide: [https://aka.ms/msal-ropc-migration](https://aka.ms/msal-ropc-migration)'
535542
signature: acquire_token_by_username_password(username, password, scopes, claims_challenge=None,
536543
auth_scheme=None, **kwargs)
537544
parameters:
@@ -879,7 +886,7 @@ methods:
879886
description: 'OPTIONAL. Specifies the method with which response parameters should
880887
be returned.
881888
882-
The default value is equivalent to `query`, which is still secure enough in
889+
The default value is equivalent to `query`, which was still secure enough in
883890
MSAL Python
884891
885892
(because MSAL Python does not transfer tokens via query parameter in the first
@@ -902,7 +909,24 @@ methods:
902909
903910
*here <https://openid.net/specs/oauth-v2-multiple-response-types-1_0.html#ResponseModes>*
904911
905-
and *here <https://openid.net/specs/oauth-v2-form-post-response-mode-1_0.html#FormPostResponseMode>*'
912+
and *here <https://openid.net/specs/oauth-v2-form-post-response-mode-1_0.html#FormPostResponseMode>*
913+
914+
915+
916+
> [!NOTE]
917+
918+
> You should configure your web framework to accept form_post responses instead
919+
of query responses.
920+
921+
>
922+
923+
> While this parameter still works, it will be removed in a future version.
924+
925+
>
926+
927+
> Using query-based response modes is less secure and should be avoided.
928+
929+
>'
906930
defaultValue: None
907931
types:
908932
- <xref:str>

0 commit comments

Comments
 (0)