-
Notifications
You must be signed in to change notification settings - Fork 21
Expand file tree
/
Copy pathmsal.application.ClientApplication.yml
More file actions
994 lines (784 loc) Β· 42.7 KB
/
msal.application.ClientApplication.yml
File metadata and controls
994 lines (784 loc) Β· 42.7 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
### YamlMime:PythonClass
uid: msal.application.ClientApplication
name: ClientApplication
fullName: msal.application.ClientApplication
module: msal.application
summary: 'You do not usually directly use this class. Use its subclasses instead:
<xref:msal.application.PublicClientApplication> and <xref:msal.application.ConfidentialClientApplication>.
Create an instance of application.'
constructor:
syntax: ClientApplication(client_id, client_credential=None, authority=None, validate_authority=True,
token_cache=None, http_client=None, verify=True, proxies=None, timeout=None, client_claims=None,
app_name=None, app_version=None, client_capabilities=None, azure_region=None,
exclude_scopes=None, http_cache=None, instance_discovery=None, allow_broker=None,
enable_pii_log=None, oidc_authority=None)
parameters:
- name: client_id
description: Your app has a client_id after you register it on Microsoft Entra
admin center.
isRequired: true
types:
- <xref:str>
- name: client_credential
description: "For <xref:msal.application.PublicClientApplication>, you use *None*\
\ here.\n\nFor <xref:msal.application.ConfidentialClientApplication>,\nit supports\
\ many different input formats for different scenarios.\n\n\n\n## Support using\
\ a client secret.Just feed in a string, such as `\"your client secret\"`.\n\
\n\n\n## Support using a certificate in X.509 (.pem) formatDeprecated because\
\ it uses SHA-1 thumbprint,\nunless you are still using ADFS which supports\
\ SHA-1 thumbprint only.\nPlease use the .pfx option documented later in this\
\ page.Feed in a dict in this form:\n\n<!-- literal_block {\"ids\": [], \"classes\"\
: [], \"names\": [], \"dupnames\": [], \"backrefs\": [], \"xml:space\": \"preserve\"\
, \"language\": \"default\", \"force\": false, \"linenos\": false} -->\n\n````default\n\
\n {\n \"private_key\": \"...-----BEGIN PRIVATE KEY-----... in PEM format\"\
,\n \"thumbprint\": \"An SHA-1 thumbprint such as A1B2C3D4E5F6...\"\n\
\ \"Changed in version 1.35.0, if thumbprint is absent\"\n \
\ \"and a public_certificate is present, MSAL will\"\n \"automatically\
\ calculate an SHA-256 thumbprint instead.\",\n \"passphrase\": \"Needed\
\ if the private_key is encrypted (Added in version 1.6.0)\",\n \"public_certificate\"\
: \"...-----BEGIN CERTIFICATE-----...\", # Needed if you use Subject Name/Issuer\
\ auth. Added in version 0.5.0.\n }\n ````\n\nMSAL Python requires a \"\
private_key\" in PEM format.\nIf your cert is in PKCS12 (.pfx) format,\nyou\
\ can convert it to X.509 (.pem) format,\nby `openssl pkcs12 -in file.pfx -out\
\ file.pem -nodes`.The thumbprint is available in your app's registration in\
\ 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`\
\ (optional) is public key certificate\nwhich will be sent through 'x5c' JWT\
\ header.\nThis is useful when you use [Subject Name/Issuer Authentication](https://github.com/AzureAD/microsoft-authentication-library-for-python/issues/60)\n\
which is an approach to allow easier certificate rotation.\nPer [specs](https://tools.ietf.org/html/rfc7515#section-4.1.6),\n\
\"the certificate containing\nthe public key corresponding to the key used to\
\ digitally sign the\nJWS MUST be the first certificate. This MAY be followed\
\ by\nadditional certificates, with each subsequent certificate being the\n\
one used to certify the previous one.\"\nHowever, your certificate's issuer\
\ may use a different order.\nSo, if your attempt ends up with an error AADSTS700027\
\ -\n\"The provided signature value did not match the expected signature value\"\
,\nyou may try use only the leaf cert (in PEM/str format) instead.\n\n\n\n##\
\ Supporting raw assertion obtained from elsewhere*Added in version 1.13.0*:\n\
It can also be a completely pre-signed assertion that you've assembled yourself.\n\
Simply pass a container containing only the key \"client_assertion\", like this:\n\
\n<!-- literal_block {\"ids\": [], \"classes\": [], \"names\": [], \"dupnames\"\
: [], \"backrefs\": [], \"xml:space\": \"preserve\", \"language\": \"default\"\
, \"force\": false, \"linenos\": false} -->\n\n````default\n\n {\n \"\
client_assertion\": \"...a JWT with claims aud, exp, iss, jti, nbf, and sub...\"\
\n }\n ````\n\n\n\n## Supporting reading client certificates from PFX filesThis\
\ usage will automatically use SHA-256 thumbprint of the certificate.*Added\
\ in version 1.29.0*:\nFeed in a dictionary containing the path to a PFX file:\n\
\n<!-- literal_block {\"ids\": [], \"classes\": [], \"names\": [], \"dupnames\"\
: [], \"backrefs\": [], \"xml:space\": \"preserve\", \"language\": \"default\"\
, \"force\": false, \"linenos\": false} -->\n\n````default\n\n {\n \"\
private_key_pfx_path\": \"/path/to/your.pfx\", # Added in version 1.29.0\n\
\ \"public_certificate\": True, # Only needed if you use Subject Name/Issuer\
\ auth. Added in version 1.30.0\n \"passphrase\": \"Passphrase if the\
\ private_key is encrypted (Optional)\",\n }\n ````\n\nThe following command\
\ will generate a .pfx file from your .key and .pem file:\n\n<!-- literal_block\
\ {\"ids\": [], \"classes\": [], \"names\": [], \"dupnames\": [], \"backrefs\"\
: [], \"xml:space\": \"preserve\", \"language\": \"default\", \"force\": false,\
\ \"linenos\": false} -->\n\n````default\n\n openssl pkcs12 -export -out certificate.pfx\
\ -inkey privateKey.key -in certificate.pem\n ````\n\n[Subject Name/Issuer\
\ Auth](https://github.com/AzureAD/microsoft-authentication-library-for-python/issues/60)\n\
is an approach to allow easier certificate rotation.\nIf your .pfx file contains\
\ both the private key and public cert,\nyou can opt in for Subject Name/Issuer\
\ Auth by setting \"public_certificate\" to `True`."
defaultValue: None
types:
- <xref:typing.Union>[<xref:dict>, <xref:str>, <xref:None>]
- name: client_claims
description: "*Added in version 0.5.0*:\nIt is a dictionary of extra claims that\
\ would be signed by\nby this <xref:msal.application.ConfidentialClientApplication>\
\ 's private key.\nFor example, you can use {\"client_ip\": \"x.x.x.x\"}.\n\
You may also override any of the following default claims:\n\n<!-- literal_block\
\ {\"ids\": [], \"classes\": [], \"names\": [], \"dupnames\": [], \"backrefs\"\
: [], \"xml:space\": \"preserve\", \"language\": \"default\", \"force\": false,\
\ \"linenos\": false} -->\n\n````default\n\n {\n \"aud\": the_token_endpoint,\n\
\ \"iss\": self.client_id,\n \"sub\": same_as_issuer,\n \"\
exp\": now + 10_min,\n \"iat\": now,\n \"jti\": a_random_uuid\n\
\ }\n ````"
defaultValue: None
types:
- <xref:dict>
- name: authority
description: "A URL that identifies a token authority. It should be of the format\n\
`https://login.microsoftonline.com/your_tenant`\nBy default, we will use `https://login.microsoftonline.com/common`\n\
\n*Changed in version 1.17*: you can also use predefined constant\nand a builder\
\ like this:\n\n<!-- literal_block {\"ids\": [], \"classes\": [], \"names\"\
: [], \"dupnames\": [], \"backrefs\": [], \"xml:space\": \"preserve\", \"language\"\
: \"default\", \"force\": false, \"linenos\": false} -->\n\n````default\n\n\
\ from msal.authority import (\n AuthorityBuilder,\n AZURE_US_GOVERNMENT,\
\ AZURE_CHINA, AZURE_PUBLIC)\n my_authority = AuthorityBuilder(AZURE_PUBLIC,\
\ \"contoso.onmicrosoft.com\")\n # Now you get an equivalent of\n # \"https://login.microsoftonline.com/contoso.onmicrosoft.com\"\
\n\n # You can feed such an authority to msal's ClientApplication\n from\
\ msal import PublicClientApplication\n app = PublicClientApplication(\"my_client_id\"\
, authority=my_authority, ...)\n ````"
defaultValue: None
types:
- <xref:str>
- name: validate_authority
description: '(optional) Turns authority validation
on or off. This parameter default to true.'
defaultValue: 'True'
types:
- <xref:bool>
- name: token_cache
description: 'Sets the token cache used by this ClientApplication instance.
By default, an in-memory cache will be created and used.'
defaultValue: None
types:
- <xref:msal.token_cache.TokenCache>
- name: http_client
description: '(optional)
Your implementation of abstract class HttpClient <msal.oauth2cli.http.http_client>
Defaults to a requests session instance.
Since MSAL 1.11.0, the default session would be configured
to attempt one retry on connection error.
If you are providing your own http_client,
it will be your http_client''s duty to decide whether to perform retry.'
defaultValue: None
- name: verify
description: '(optional)
It will be passed to the
[verify parameter in the underlying requests library](http://docs.python-requests.org/en/v2.9.1/user/advanced/#ssl-cert-verification)
This does not apply if you have chosen to pass your own Http client'
defaultValue: 'True'
- name: proxies
description: '(optional)
It will be passed to the
[proxies parameter in the underlying requests library](http://docs.python-requests.org/en/v2.9.1/user/advanced/#proxies)
This does not apply if you have chosen to pass your own Http client'
defaultValue: None
- name: timeout
description: '(optional)
It will be passed to the
[timeout parameter in the underlying requests library](http://docs.python-requests.org/en/v2.9.1/user/advanced/#timeouts)
This does not apply if you have chosen to pass your own Http client'
defaultValue: None
- name: app_name
description: '(optional)
You can provide your application name for Microsoft telemetry purposes.
Default value is None, means it will not be passed to Microsoft.'
defaultValue: None
- name: app_version
description: '(optional)
You can provide your application version for Microsoft telemetry purposes.
Default value is None, means it will not be passed to Microsoft.'
defaultValue: None
- name: client_capabilities
description: '(optional)
Allows configuration of one or more client capabilities, e.g. ["CP1"].
Client capability is meant to inform the Microsoft identity platform
(STS) what this client is capable for,
so STS can decide to turn on certain features.
For example, if client is capable to handle *claims challenge*,
STS may issue
[Continuous Access Evaluation (CAE)](https://learn.microsoft.com/entra/identity/conditional-access/concept-continuous-access-evaluation)
access tokens to resources,
knowing that when the resource emits a *claims challenge*
the client will be able to handle those challenges.
Implementation details:
Client capability is implemented using "claims" parameter on the wire,
for now.
MSAL will combine them into
[claims parameter](https://openid.net/specs/openid-connect-core-1_0-final.html#ClaimsParameter)
which you will later provide via one of the acquire-token request.'
defaultValue: None
types:
- <xref:list>[<xref:str>]
- name: azure_region
description: "(optional)\nInstructs MSAL to use the Entra regional token service.\
\ This legacy feature is only available to\nfirst-party applications. Only `acquire_token_for_client()`\
\ is supported.\n\nSupports 4 values:\n\n1. `azure_region=None` - This default\
\ value means no region is configured. MSAL will use the region defined in env\
\ var `MSAL_FORCE_REGION`. \n\n2. `azure_region=\"some_region\"` - meaning the\
\ specified region is used. \n\n3. `azure_region=True` - meaning MSAL will try\
\ to auto-detect the region. This is not recommended. \n\n4. `azure_region=False`\
\ - meaning MSAL will use no region. \n\n\n> [!NOTE]\n> Region auto-discovery\
\ has been tested on VMs and on Azure Functions. It is unreliable.\n>\n> Applications\
\ using this option should configure a short timeout.\n>\n> \n>\n> For more\
\ details and for the values of the region string\n>\n> \n>\n> see [https://learn.microsoft.com/entra/msal/dotnet/resources/region-discovery-troubleshooting](https://learn.microsoft.com/entra/msal/dotnet/resources/region-discovery-troubleshooting)\n\
>\n\nNew in version 1.12.0."
defaultValue: None
types:
- <xref:str>
- name: exclude_scopes
description: '(optional)
Historically MSAL hardcodes *offline_access* scope,
which would allow your app to have prolonged access to user''s data.
If that is unnecessary or undesirable for your app,
now you can use this parameter to supply an exclusion list of scopes,
such as `exclude_scopes = ["offline_access"]`.'
defaultValue: None
types:
- <xref:list>[<xref:str>]
- name: http_cache
description: "MSAL has long been caching tokens in the `token_cache`.\nRecently,\
\ MSAL also introduced a concept of `http_cache`,\nby automatically caching\
\ some finite amount of non-token http responses,\nso that *long-lived*\n`PublicClientApplication`\
\ and `ConfidentialClientApplication`\nwould be more performant and responsive\
\ in some situations.\n\nThis `http_cache` parameter accepts any dict-like object.\n\
If not provided, MSAL will use an in-memory dict.\n\nIf your app is a command-line\
\ app (CLI),\nyou would want to persist your http_cache across different CLI\
\ runs.\nThe persisted file's format may change due to, but not limited to,\n\
[unstable protocol](https://docs.python.org/3/library/pickle.html#data-stream-format),\n\
so your implementation shall tolerate unexpected loading errors.\nThe following\
\ recipe shows a way to do so:\n\n<!-- literal_block {\"ids\": [], \"classes\"\
: [], \"names\": [], \"dupnames\": [], \"backrefs\": [], \"xml:space\": \"preserve\"\
, \"language\": \"default\", \"force\": false, \"linenos\": false} -->\n\n````default\n\
\n # Just add the following lines at the beginning of your CLI script\n \
\ import sys, atexit, pickle, logging\n http_cache_filename = sys.argv[0]\
\ + \".http_cache\"\n try:\n with open(http_cache_filename, \"rb\")\
\ as f:\n persisted_http_cache = pickle.load(f) # Take a snapshot\n\
\ except (\n FileNotFoundError, # Or IOError in Python 2\n \
\ pickle.UnpicklingError, # A corrupted http cache file\n AttributeError,\
\ # Cache created by a different version of MSAL\n ):\n persisted_http_cache\
\ = {} # Recover by starting afresh\n except: # Unexpected exceptions\n\
\ logging.exception(\"You may want to debug this\")\n persisted_http_cache\
\ = {} # Recover by starting afresh\n atexit.register(lambda: pickle.dump(\n\
\ # When exit, flush it back to the file.\n # It may occasionally\
\ overwrite another process's concurrent write,\n # but that is fine.\
\ Subsequent runs will reach eventual consistency.\n persisted_http_cache,\
\ open(http_cache_file, \"wb\")))\n\n # And then you can implement your app\
\ as you normally would\n app = msal.PublicClientApplication(\n \"your_client_id\"\
,\n ...,\n http_cache=persisted_http_cache, # Utilize persisted_http_cache\n\
\ ...,\n #token_cache=..., # You may combine the old token_cache\
\ trick\n # Please refer to token_cache recipe at\n # https://msal-python.readthedocs.io/en/latest/#msal.SerializableTokenCache\n\
\ )\n app.acquire_token_interactive([\"your\", \"scope\"], ...)\n \
\ ````\n\nContent inside `http_cache` are cheap to obtain.\nThere is no need\
\ to share them among different apps.\n\nContent inside `http_cache` will contain\
\ no tokens nor\nPersonally Identifiable Information (PII). Encryption is unnecessary.\n\
\nNew in version 1.16.0."
defaultValue: None
types:
- <xref:dict>
- name: instance_discovery
description: "Historically, MSAL would connect to a central endpoint located at\n\
`https://login.microsoftonline.com` to acquire some metadata,\nespecially when\
\ using an unfamiliar authority.\nThis behavior is known as Instance Discovery.\n\
\nThis parameter defaults to None, which enables the Instance Discovery.\n\n\
If you know some authorities which you allow MSAL to operate with as-is,\nwithout\
\ involving any Instance Discovery, the recommended pattern is:\n\n<!-- literal_block\
\ {\"ids\": [], \"classes\": [], \"names\": [], \"dupnames\": [], \"backrefs\"\
: [], \"xml:space\": \"preserve\", \"language\": \"default\", \"force\": false,\
\ \"linenos\": false} -->\n\n````default\n\n known_authorities = frozenset([\
\ # Treat your known authorities as const\n \"https://contoso.com/adfs\"\
, \"https://login.azs/foo\"])\n ...\n authority = \"https://contoso.com/adfs\"\
\ # Assuming your app will use this\n app1 = PublicClientApplication(\n \
\ \"client_id\",\n authority=authority,\n # Conditionally disable\
\ Instance Discovery for known authorities\n instance_discovery=authority\
\ not in known_authorities,\n )\n ````\n\nIf you do not know some authorities\
\ beforehand,\nyet still want MSAL to accept any authority that you will provide,\n\
you can use a `False` to unconditionally disable Instance Discovery.\n\nNew\
\ in version 1.19.0."
defaultValue: None
types:
- <xref:boolean>
- name: allow_broker
description: Deprecated. Please use `enable_broker_on_windows` instead.
defaultValue: None
types:
- <xref:boolean>
- name: enable_pii_log
description: 'When enabled, logs may include PII (Personal Identifiable Information).
This can be useful in troubleshooting broker behaviors.
The default behavior is False.
New in version 1.24.0.'
defaultValue: None
types:
- <xref:boolean>
- name: oidc_authority
description: '*Added in version 1.28.0*:
It is a URL that identifies an OpenID Connect (OIDC) authority of
the format `https://contoso.com/tenant`.
MSAL will append ".well-known/openid-configuration" to the authority
and retrieve the OIDC metadata from there, to figure out the endpoints.
Note: Broker will NOT be used for OIDC authority.'
defaultValue: None
types:
- <xref:str>
methods:
- uid: msal.application.ClientApplication.acquire_token_by_auth_code_flow
name: acquire_token_by_auth_code_flow
summary: 'Validate the auth response being redirected back, and obtain tokens.
It automatically provides nonce protection.'
signature: acquire_token_by_auth_code_flow(auth_code_flow, auth_response, scopes=None,
**kwargs)
parameters:
- name: auth_code_flow
description: The same dict returned by <xref:msal.application.ClientApplication.initiate_auth_code_flow>.
isRequired: true
types:
- <xref:dict>
- name: auth_response
description: A dict of the query string received from auth server.
isRequired: true
types:
- <xref:dict>
- name: scopes
description: 'Scopes requested to access a protected API (a resource).
Most of the time, you can leave it empty.
If you requested user consent for multiple resources, here you will
need to provide a subset of what you required in
<xref:msal.application.ClientApplication.initiate_auth_code_flow>.
OAuth2 was designed mostly for singleton services,
where tokens are always meant for the same resource and the only
changes are in the scopes.
In Microsoft Entra, tokens can be issued for multiple 3rd party resources.
You can ask authorization code for multiple resources,
but when you redeem it, the token is for only one intended
recipient, called audience.
So the developer need to specify a scope so that we can restrict the
token to be issued for the corresponding audience.'
defaultValue: None
types:
- <xref:list>[<xref:str>]
return:
description: "* A dict containing \"access_token\" and/or \"id_token\", among\
\ others, depends on what scope was used. (See [https://tools.ietf.org/html/rfc6749#section-5.1](https://tools.ietf.org/html/rfc6749#section-5.1))\
\ \n\n* A dict containing \"error\", optionally \"error_description\", \"error_uri\"\
. (It is either [this](https://tools.ietf.org/html/rfc6749#section-4.1.2.1)\
\ or [that](https://tools.ietf.org/html/rfc6749#section-5.2)) \n\n* Most client-side\
\ data error would result in ValueError exception. So the usage pattern could\
\ be without any protocol details: \n\n <!-- literal_block {\"ids\": [], \"\
classes\": [], \"names\": [], \"dupnames\": [], \"backrefs\": [], \"xml:space\"\
: \"preserve\", \"language\": \"default\", \"force\": false, \"linenos\": false}\
\ -->\n\n ````default\n\n def authorize(): # A controller in a web app\n\
\ try:\n result = msal_app.acquire_token_by_auth_code_flow(\n\
\ session.get(\"flow\", {}), request.args)\n if\
\ \"error\" in result:\n return render_template(\"error.html\"\
, result)\n use(result) # Token(s) are available in result and\
\ cache\n except ValueError: # Usually caused by CSRF\n \
\ pass # Simply ignore them\n return redirect(url_for(\"index\"))\n\
\ ````"
- uid: msal.application.ClientApplication.acquire_token_by_authorization_code
name: acquire_token_by_authorization_code
summary: The second half of the Authorization Code Grant.
signature: acquire_token_by_authorization_code(code, scopes, redirect_uri=None,
nonce=None, claims_challenge=None, **kwargs)
parameters:
- name: code
description: The authorization code returned from Authorization Server.
isRequired: true
- name: scopes
description: '(Required)
Scopes requested to access a protected API (a resource).
If you requested user consent for multiple resources, here you will
typically want to provide a subset of what you required in AuthCode.
OAuth2 was designed mostly for singleton services,
where tokens are always meant for the same resource and the only
changes are in the scopes.
In Microsoft Entra, tokens can be issued for multiple 3rd party resources.
You can ask authorization code for multiple resources,
but when you redeem it, the token is for only one intended
recipient, called audience.
So the developer need to specify a scope so that we can restrict the
token to be issued for the corresponding audience.'
isRequired: true
types:
- <xref:list>[<xref:str>]
- name: nonce
description: 'If you provided a nonce when calling <xref:msal.application.ClientApplication.get_authorization_request_url>,
same nonce should also be provided here, so that we''ll validate it.
An exception will be raised if the nonce in id token mismatches.'
defaultValue: None
- name: claims_challenge
description: 'The claims_challenge parameter requests specific claims requested
by the resource provider
in the form of a claims_challenge directive in the www-authenticate header to
be
returned from the UserInfo Endpoint and/or in the ID Token and/or Access Token.
It is a string of a JSON object which contains lists of claims being requested
from these locations.'
defaultValue: None
- name: redirect_uri
defaultValue: None
return:
description: "A dict representing the json response from Microsoft Entra:\n\n\
* A successful response would contain \"access_token\" key, \n\n* an error response\
\ would contain \"error\" and usually \"error_description\"."
- uid: msal.application.ClientApplication.acquire_token_by_refresh_token
name: acquire_token_by_refresh_token
summary: 'Acquire token(s) based on a refresh token (RT) obtained from elsewhere.
You use this method only when you have old RTs from elsewhere,
and now you want to migrate them into MSAL.
Calling this method results in new tokens automatically storing into MSAL.
You do NOT need to use this method if you are already using MSAL.
MSAL maintains RT automatically inside its token cache,
and an access token can be retrieved
when you call <xref:msal.application.ClientApplication.acquire_token_silent>.'
signature: acquire_token_by_refresh_token(refresh_token, scopes, **kwargs)
parameters:
- name: refresh_token
description: The old refresh token, as a string.
isRequired: true
types:
- <xref:str>
- name: scopes
description: 'The scopes associate with this old RT.
Each scope needs to be in the Microsoft identity platform (v2) format.
See [Scopes not resources](https://docs.microsoft.com/en-us/azure/active-directory/develop/migrate-python-adal-msal#scopes-not-resources).'
isRequired: true
types:
- <xref:list>
return:
description: "* A dict contains \"error\" and some other keys, when error happened.\
\ \n\n* A dict contains no \"error\" key means migration was successful."
- uid: msal.application.ClientApplication.acquire_token_by_username_password
name: acquire_token_by_username_password
summary: 'Gets a token for a given resource via user credentials.
See this page for constraints of Username Password Flow.
[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)
[Deprecated] This API is deprecated for public client flows and will be
removed in a future release. Use a more secure flow instead.
Migration guide: [https://aka.ms/msal-ropc-migration](https://aka.ms/msal-ropc-migration)'
signature: acquire_token_by_username_password(username, password, scopes, claims_challenge=None,
auth_scheme=None, **kwargs)
parameters:
- name: username
description: Typically a UPN in the form of an email address.
isRequired: true
types:
- <xref:str>
- name: password
description: The password.
isRequired: true
types:
- <xref:str>
- name: scopes
description: Scopes requested to access a protected API (a resource).
isRequired: true
types:
- <xref:list>[<xref:str>]
- name: claims_challenge
description: 'The claims_challenge parameter requests specific claims requested
by the resource provider
in the form of a claims_challenge directive in the www-authenticate header to
be
returned from the UserInfo Endpoint and/or in the ID Token and/or Access Token.
It is a string of a JSON object which contains lists of claims being requested
from these locations.'
defaultValue: None
- name: auth_scheme
description: 'You can provide an `msal.auth_scheme.PopAuthScheme` object
so that MSAL will get a Proof-of-Possession (POP) token for you.
New in version 1.26.0.'
defaultValue: None
types:
- <xref:object>
return:
description: "A dict representing the json response from Microsoft Entra:\n\n\
* A successful response would contain \"access_token\" key, \n\n* an error response\
\ would contain \"error\" and usually \"error_description\"."
- uid: msal.application.ClientApplication.acquire_token_silent
name: acquire_token_silent
summary: 'Acquire an access token for given account, without user interaction.
It has same parameters as the <xref:msal.application.ClientApplication.acquire_token_silent_with_error>.
The difference is the behavior of the return value.
This method will combine the cache empty and refresh error
into one return value, *None*.
If your app does not care about the exact token refresh error during
token cache look-up, then this method is easier and recommended.'
signature: acquire_token_silent(scopes, account, authority=None, force_refresh=False,
claims_challenge=None, auth_scheme=None, **kwargs)
parameters:
- name: scopes
isRequired: true
- name: account
isRequired: true
- name: authority
defaultValue: None
- name: force_refresh
defaultValue: 'False'
- name: claims_challenge
defaultValue: None
- name: auth_scheme
defaultValue: None
return:
description: "* A dict containing no \"error\" key, and typically contains an\
\ \"access_token\" key, if cache lookup succeeded. \n\n* None when cache lookup\
\ does not yield a token."
- uid: msal.application.ClientApplication.acquire_token_silent_with_error
name: acquire_token_silent_with_error
summary: 'Acquire an access token for given account, without user interaction.
It is done either by finding a valid access token from cache,
or by finding a valid refresh token from cache and then automatically
use it to redeem a new access token.
This method will differentiate cache empty from token refresh error.
If your app cares the exact token refresh error during
token cache look-up, then this method is suitable.
Otherwise, the other method <xref:msal.application.ClientApplication.acquire_token_silent>
is recommended.'
signature: acquire_token_silent_with_error(scopes, account, authority=None, force_refresh=False,
claims_challenge=None, auth_scheme=None, **kwargs)
parameters:
- name: scopes
description: '(Required)
Scopes requested to access a protected API (a resource).'
isRequired: true
types:
- <xref:list>[<xref:str>]
- name: account
description: '(Required)
One of the account object returned by <xref:msal.application.ClientApplication.get_accounts>.
Starting from MSAL Python 1.23,
a `None` input will become a NO-OP and always return `None`.'
isRequired: true
- name: force_refresh
description: 'If True, it will skip Access Token look-up,
and try to find a Refresh Token to obtain a new Access Token.'
defaultValue: 'False'
- name: claims_challenge
description: 'The claims_challenge parameter requests specific claims requested
by the resource provider
in the form of a claims_challenge directive in the www-authenticate header to
be
returned from the UserInfo Endpoint and/or in the ID Token and/or Access Token.
It is a string of a JSON object which contains lists of claims being requested
from these locations.'
defaultValue: None
- name: auth_scheme
description: 'You can provide an `msal.auth_scheme.PopAuthScheme` object
so that MSAL will get a Proof-of-Possession (POP) token for you.
New in version 1.26.0.'
defaultValue: None
types:
- <xref:object>
- name: authority
defaultValue: None
return:
description: "* A dict containing no \"error\" key, and typically contains an\
\ \"access_token\" key, if cache lookup succeeded. \n\n* None when there is\
\ simply no token in the cache. \n\n* A dict containing an \"error\" key, when\
\ token refresh failed."
- uid: msal.application.ClientApplication.get_accounts
name: get_accounts
summary: 'Get a list of accounts which previously signed in, i.e. exists in cache.
An account can later be used in <xref:msal.application.ClientApplication.acquire_token_silent>
to find its tokens.'
signature: get_accounts(username=None)
parameters:
- name: username
description: Filter accounts with this username only. Case insensitive.
defaultValue: None
return:
description: 'A list of account objects.
Each account is a dict. For now, we only document its "username" field.
Your app can choose to display those information to end user,
and allow user to choose one of his/her accounts to proceed.'
- uid: msal.application.ClientApplication.get_authorization_request_url
name: get_authorization_request_url
summary: Constructs a URL for you to start a Authorization Code Grant.
signature: get_authorization_request_url(scopes, login_hint=None, state=None, redirect_uri=None,
response_type='code', prompt=None, nonce=None, domain_hint=None, claims_challenge=None,
**kwargs)
parameters:
- name: scopes
description: '(Required)
Scopes requested to access a protected API (a resource).'
isRequired: true
types:
- <xref:list>[<xref:str>]
- name: state
description: Recommended by OAuth2 for CSRF protection.
defaultValue: None
types:
- <xref:str>
- name: login_hint
description: Identifier of the user. Generally a User Principal Name (UPN).
defaultValue: None
types:
- <xref:str>
- name: redirect_uri
description: Address to return to upon receiving a response from the authority.
defaultValue: None
types:
- <xref:str>
- name: response_type
description: 'Default value is "code" for an OAuth2 Authorization Code grant.
You could use other content such as "id_token" or "token",
which would trigger an Implicit Grant, but that is
[not recommended](https://docs.microsoft.com/en-us/azure/active-directory/develop/v2-oauth2-implicit-grant-flow#is-the-implicit-grant-suitable-for-my-app).'
defaultValue: code
types:
- <xref:str>
- name: prompt
description: 'By default, no prompt value will be sent, not even string `"none"`.
You will have to specify a value explicitly.
Its valid values are the constants defined in
<xref:msal.Prompt>.'
defaultValue: None
types:
- <xref:str>
- name: nonce
description: 'A cryptographically random value used to mitigate replay attacks.
See also
[OIDC specs](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest).'
defaultValue: None
- name: domain_hint
description: 'Can be one of "consumers" or "organizations" or your tenant domain
"contoso.com".
If included, it will skip the email-based discovery process that user goes
through on the sign-in page, leading to a slightly more streamlined user experience.
More information on possible values available in
[Auth Code Flow doc](https://docs.microsoft.com/en-us/azure/active-directory/develop/v2-oauth2-auth-code-flow#request-an-authorization-code)
and
[domain_hint doc](https://docs.microsoft.com/en-us/openspecs/windows_protocols/ms-oapx/86fb452d-e34a-494e-ac61-e526e263b6d8).'
defaultValue: None
- name: claims_challenge
description: 'The claims_challenge parameter requests specific claims requested
by the resource provider
in the form of a claims_challenge directive in the www-authenticate header to
be
returned from the UserInfo Endpoint and/or in the ID Token and/or Access Token.
It is a string of a JSON object which contains lists of claims being requested
from these locations.'
defaultValue: None
return:
description: The authorization url as a string.
- uid: msal.application.ClientApplication.initiate_auth_code_flow
name: initiate_auth_code_flow
summary: 'Initiate an auth code flow.
Later when the response reaches your redirect_uri,
you can use <xref:msal.application.ClientApplication.acquire_token_by_auth_code_flow>
to complete the authentication/authorization.'
signature: initiate_auth_code_flow(scopes, redirect_uri=None, state=None, prompt=None,
login_hint=None, domain_hint=None, claims_challenge=None, max_age=None, response_mode=None)
parameters:
- name: scopes
description: It is a list of case-sensitive strings.
isRequired: true
types:
- <xref:list>
- name: redirect_uri
description: Optional. If not specified, server will use the pre-registered one.
defaultValue: None
types:
- <xref:str>
- name: state
description: 'An opaque value used by the client to
maintain state between the request and callback.
If absent, this library will automatically generate one internally.'
defaultValue: None
types:
- <xref:str>
- name: prompt
description: 'By default, no prompt value will be sent, not even string `"none"`.
You will have to specify a value explicitly.
Its valid values are the constants defined in
<xref:msal.Prompt>.'
defaultValue: None
types:
- <xref:str>
- name: login_hint
description: Optional. Identifier of the user. Generally a User Principal Name
(UPN).
defaultValue: None
types:
- <xref:str>
- name: domain_hint
description: 'Can be one of "consumers" or "organizations" or your tenant domain
"contoso.com".
If included, it will skip the email-based discovery process that user goes
through on the sign-in page, leading to a slightly more streamlined user experience.
More information on possible values available in
[Auth Code Flow doc](https://docs.microsoft.com/en-us/azure/active-directory/develop/v2-oauth2-auth-code-flow#request-an-authorization-code)
and
[domain_hint doc](https://docs.microsoft.com/en-us/openspecs/windows_protocols/ms-oapx/86fb452d-e34a-494e-ac61-e526e263b6d8).'
defaultValue: None
- name: max_age
description: 'OPTIONAL. Maximum Authentication Age.
Specifies the allowable elapsed time in seconds
since the last time the End-User was actively authenticated.
If the elapsed time is greater than this value,
Microsoft identity platform will actively re-authenticate the End-User.
MSAL Python will also automatically validate the auth_time in ID token.
New in version 1.15.'
defaultValue: None
types:
- <xref:int>
- name: response_mode
description: 'OPTIONAL. Specifies the method with which response parameters should
be returned.
The default value is equivalent to `query`, which was still secure enough in
MSAL Python
(because MSAL Python does not transfer tokens via query parameter in the first
place).
For even better security, we recommend using the value `form_post`.
In "form_post" mode, response parameters
will be encoded as HTML form values that are transmitted via the HTTP POST method
and
encoded in the body using the application/x-www-form-urlencoded format.
Valid values can be either "form_post" for HTTP POST to callback URI or
"query" (the default) for HTTP GET with parameters encoded in query string.
More information on possible values
*here <https://openid.net/specs/oauth-v2-multiple-response-types-1_0.html#ResponseModes>*
and *here <https://openid.net/specs/oauth-v2-form-post-response-mode-1_0.html#FormPostResponseMode>*
> [!NOTE]
> You should configure your web framework to accept form_post responses instead
of query responses.
>
> While this parameter still works, it will be removed in a future version.
>
> Using query-based response modes is less secure and should be avoided.
>'
defaultValue: None
types:
- <xref:str>
- name: claims_challenge
defaultValue: None
return:
description: "The auth code flow. It is a dict in this form:\n\n<!-- literal_block\
\ {\"ids\": [], \"classes\": [], \"names\": [], \"dupnames\": [], \"backrefs\"\
: [], \"xml:space\": \"preserve\", \"language\": \"default\", \"force\": false,\
\ \"linenos\": false} -->\n\n````default\n\n {\n \"auth_uri\": \"https://...\"\
, // Guide user to visit this\n \"state\": \"...\", // You may choose\
\ to verify it by yourself,\n // or just let acquire_token_by_auth_code_flow()\n\
\ // do that for you.\n \"...\": \"...\", // Everything\
\ else are reserved and internal\n }\n ````\n\nThe caller is expected to:\n\
\n1. somehow store this content, typically inside the current session, \n\n\
2. guide the end user (i.e. resource owner) to visit that auth_uri, \n\n3. and\
\ then relay this dict and subsequent auth response to <xref:msal.application.ClientApplication.acquire_token_by_auth_code_flow>."
- uid: msal.application.ClientApplication.is_pop_supported
name: is_pop_supported
summary: Returns True if this client supports Proof-of-Possession Access Token.
signature: is_pop_supported()
- uid: msal.application.ClientApplication.remove_account
name: remove_account
summary: Sign me out and forget me from token cache
signature: remove_account(account)
parameters:
- name: account
isRequired: true
attributes:
- uid: msal.application.ClientApplication.ACQUIRE_TOKEN_BY_AUTHORIZATION_CODE_ID
name: ACQUIRE_TOKEN_BY_AUTHORIZATION_CODE_ID
signature: ACQUIRE_TOKEN_BY_AUTHORIZATION_CODE_ID = '832'
- uid: msal.application.ClientApplication.ACQUIRE_TOKEN_BY_DEVICE_FLOW_ID
name: ACQUIRE_TOKEN_BY_DEVICE_FLOW_ID
signature: ACQUIRE_TOKEN_BY_DEVICE_FLOW_ID = '622'
- uid: msal.application.ClientApplication.ACQUIRE_TOKEN_BY_REFRESH_TOKEN
name: ACQUIRE_TOKEN_BY_REFRESH_TOKEN
signature: ACQUIRE_TOKEN_BY_REFRESH_TOKEN = '85'
- uid: msal.application.ClientApplication.ACQUIRE_TOKEN_BY_USERNAME_PASSWORD_ID
name: ACQUIRE_TOKEN_BY_USERNAME_PASSWORD_ID
signature: ACQUIRE_TOKEN_BY_USERNAME_PASSWORD_ID = '301'
- uid: msal.application.ClientApplication.ACQUIRE_TOKEN_FOR_CLIENT_ID
name: ACQUIRE_TOKEN_FOR_CLIENT_ID
signature: ACQUIRE_TOKEN_FOR_CLIENT_ID = '730'
- uid: msal.application.ClientApplication.ACQUIRE_TOKEN_INTERACTIVE
name: ACQUIRE_TOKEN_INTERACTIVE
signature: ACQUIRE_TOKEN_INTERACTIVE = '169'
- uid: msal.application.ClientApplication.ACQUIRE_TOKEN_ON_BEHALF_OF_ID
name: ACQUIRE_TOKEN_ON_BEHALF_OF_ID
signature: ACQUIRE_TOKEN_ON_BEHALF_OF_ID = '523'
- uid: msal.application.ClientApplication.ACQUIRE_TOKEN_SILENT_ID
name: ACQUIRE_TOKEN_SILENT_ID
signature: ACQUIRE_TOKEN_SILENT_ID = '84'
- uid: msal.application.ClientApplication.ATTEMPT_REGION_DISCOVERY
name: ATTEMPT_REGION_DISCOVERY
signature: ATTEMPT_REGION_DISCOVERY = True
- uid: msal.application.ClientApplication.DISABLE_MSAL_FORCE_REGION
name: DISABLE_MSAL_FORCE_REGION
signature: DISABLE_MSAL_FORCE_REGION = False
- uid: msal.application.ClientApplication.GET_ACCOUNTS_ID
name: GET_ACCOUNTS_ID
signature: GET_ACCOUNTS_ID = '902'
- uid: msal.application.ClientApplication.REMOVE_ACCOUNT_ID
name: REMOVE_ACCOUNT_ID
signature: REMOVE_ACCOUNT_ID = '903'