ClientApplication Класс

Обычно этот класс не используется напрямую. Используйте вместо него подклассы: PublicClientApplication и ConfidentialClientApplication.

Создайте экземпляр приложения.

Конструктор

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)

Параметры

Имя Описание
client_id
Обязательно
str

Приложение имеет client_id после регистрации его на Центр администрирования Microsoft Entra.
client_credential
Union[dict, str, None]

Для PublicClientApplicationэтого вы используете None здесь.

Для ConfidentialClientApplicationэтого он поддерживает множество различных форматов входных данных для различных сценариев.

Поддержка использования секрета клиента. Просто веб-канал в строке, например "your client secret".

Поддержка использования сертификата в формате X.509 (PEM), так как она использует отпечаток SHA-1,

Если вы по-прежнему используете ADFS, поддерживающий только отпечаток SHA-1. Используйте параметр PFX, описанный далее на этой странице. Веб-канал в диктовке в этой форме:


   {
       "private_key": "...-----BEGIN PRIVATE KEY-----... in PEM format",
       "thumbprint": "An SHA-1 thumbprint such as A1B2C3D4E5F6..."
           "Changed in version 1.35.0, if thumbprint is absent"
           "and a public_certificate is present, MSAL will"
           "automatically calculate an SHA-256 thumbprint instead.",
       "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 требуется private_key в формате PEM. Если сертификат находится в формате PKCS12 (PFX), его можно преобразовать в формат X.509 (PEM) по.openssl pkcs12 -in file.pfx -out file.pem -nodes Отпечаток доступен в регистрации приложения в портал Azure. Кроме того, можно вычислить отпечаток. public_certificate (необязательно) — это сертификат открытого ключа, который будет отправлен через заголовок JWT x5c. Это полезно при использовании проверки подлинности субъекта или издателя , которая позволяет упростить смену сертификатов. Для спецификаций сертификат, содержащий открытый ключ, соответствующий ключу, используемому для цифровой подписи JWS, должен быть первым сертификатом. За этим МОЖЕТ следовать дополнительные сертификаты, причем каждый последующий сертификат используется для сертификации предыдущего". Однако издатель сертификата может использовать другой порядок. Таким образом, если попытка заканчивается ошибкой AADSTS700027 - "Указанное значение подписи не совпадает с ожидаемым значением подписи", можно попробовать использовать только конечный сертификат (в формате PEM/str).

Поддержка необработанного утверждения, полученного из другого места, добавленного в версии 1.13.0:

Это также может быть полностью предварительно подписанное утверждение, которое вы собрали самостоятельно. Просто передайте контейнер, содержащий только ключ "client_assertion", как показано ниже.


   {
       "client_assertion": "...a JWT with claims aud, exp, iss, jti, nbf, and sub..."
   }

Поддержка чтения сертификатов клиента из PFX-файловThis будет автоматически использовать отпечаток SHA-256 сертификата. Добавлено в версию 1.29.0:

Веб-канал в словаре, содержащий путь к 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)",
   }

Следующая команда создаст PFX-файл из .key и PEM-файла:


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

Имя субъекта или проверка подлинности издателя — это подход, позволяющий упростить смену сертификатов. Если PFX-файл содержит закрытый ключ и открытый сертификат, вы можете выбрать проверку имени субъекта или издателя, установив для параметра "public_certificate" значение True.

Значение по умолчанию: None
client_claims
dict

Добавлено в версию 0.5.0: это словарь дополнительных утверждений, подписанных этим закрытым ключом ConfidentialClientApplication . Например, можно использовать {"client_ip": "x.x.x.x".}. Вы также можете переопределить любое из следующих утверждений по умолчанию:


   {
       "aud": the_token_endpoint,
       "iss": self.client_id,
       "sub": same_as_issuer,
       "exp": now + 10_min,
       "iat": now,
       "jti": a_random_uuid
   }
Значение по умолчанию: None
authority
str

URL-адрес, определяющий центр маркера. Он должен иметь формат https://login.microsoftonline.com/your_tenant По умолчанию мы будем использовать https://login.microsoftonline.com/common

Изменено в версии 1.17: можно также использовать предопределенную константу и построитель, как показано ниже:


   from msal.authority import (
       AuthorityBuilder,
       AZURE_US_GOVERNMENT, AZURE_CHINA, AZURE_PUBLIC)
   my_authority = AuthorityBuilder(AZURE_PUBLIC, "contoso.onmicrosoft.com")
   # Now you get an equivalent of
   # "https://login.microsoftonline.com/contoso.onmicrosoft.com"

   # You can feed such an authority to msal's ClientApplication
   from msal import PublicClientApplication
   app = PublicClientApplication("my_client_id", authority=my_authority, ...)
Значение по умолчанию: None
validate_authority
bool

(необязательно) Включает или отключает проверку центра. Этот параметр по умолчанию имеет значение true.

Значение по умолчанию: True
token_cache
TokenCache

Задает кэш маркеров, используемый этим экземпляром ClientApplication. По умолчанию кэш в памяти будет создан и использован.

Значение по умолчанию: None
http_client

(необязательно) Реализация абстрактного класса HttpClient <msal.oauth2cli.http.http_client> Defaults для экземпляра сеанса запросов. Так как MSAL 1.11.0 сеанс по умолчанию будет настроен для попытки одного повтора при ошибке подключения. Если вы предоставляете свой собственный http_client, это будет ваша обязанность http_client решить, следует ли выполнять повторную попытку.

Значение по умолчанию: None
verify

(необязательно) Он будет передан в параметр проверки в базовой библиотеке запросов , если вы решили передать собственный http-клиент.

Значение по умолчанию: True
proxies

(необязательно) Он будет передан параметру прокси-серверов в базовой библиотеке запросов , если вы решили передать собственный http-клиент.

Значение по умолчанию: None
timeout

(необязательно) Он будет передан параметру времени ожидания в базовой библиотеке запросов , если вы решили передать собственный http-клиент.

Значение по умолчанию: None
app_name

(необязательно) Вы можете указать имя приложения для Microsoft целей телеметрии. Значение по умолчанию — None, означает, что он не будет передан в Microsoft.

Значение по умолчанию: None
app_version

(необязательно) Вы можете предоставить версию приложения для Microsoft целей телеметрии. Значение по умолчанию — None, означает, что он не будет передан в Microsoft.

Значение по умолчанию: None
client_capabilities
list[str]

(необязательно) Разрешает настройку одного или нескольких клиентских возможностей, например ["CP1"].

Возможность клиента предназначена для информирования платформа удостоверений Майкрософт (STS) о том, что этот клиент может использовать, поэтому stS может решить включить определенные функции. Например, если клиент способен справиться с вызовом утверждений, служба STS может выдавать маркеры доступа к ресурсам непрерывной оценки доступа (CAE), зная, что при вызове утверждений клиент сможет справиться с этими проблемами.

Сведения о реализации: возможности клиента реализованы с помощью параметра claims в проводной сети. MSAL объединяет их в параметр утверждений , который вы будете предоставлять через один из запросов на получение маркера.

Значение по умолчанию: None
azure_region
str

(необязательно) Указывает MSAL использовать региональную службу токенов Entra. Эта устаревшая функция доступна только для сторонних приложений. Поддерживается только acquire_token_for_client().

Поддерживает 4 значения:

  1. azure_region=None — Это значение по умолчанию означает, что регион не настроен. MSAL будет использовать регион, определенный в env var MSAL_FORCE_REGION.

  2. azure_region="some_region" — означает, что используется указанный регион.

  3. azure_region=True — это означает, что MSAL попытается автоматически обнаружить регион. Это не рекомендуется.

  4. azure_region=False — означает, что MSAL не будет использовать ни одного региона.

Note

Автоматическое обнаружение региона было проверено на виртуальных машинах и на Функции Azure. Это ненадежно.

Приложения, использующие этот параметр, должны настроить короткое время ожидания.

Дополнительные сведения и значения строки региона

см. https://learn.microsoft.com/entra/msal/dotnet/resources/region-discovery-troubleshooting

Новые возможности в версии 1.12.0.

Значение по умолчанию: None
exclude_scopes
list[str]

(необязательно) Исторически жесткие коды MSAL offline_access области, что позволит приложению иметь длительный доступ к данным пользователя. Если это необязательно или нежелательно для приложения, теперь этот параметр можно использовать для предоставления списка исключений областей, таких как exclude_scopes = ["offline_access"].

Значение по умолчанию: None
http_cache
dict

MSAL уже давно кэширование маркеров в token_cache. В последнее время MSAL также представила концепцию http_cache, автоматически кэширование некоторого конечного количества ответов http, не являющихся маркерами, чтобы долгоеPublicClientApplication время и ConfidentialClientApplication было бы более эффективной и быстродействующей в некоторых ситуациях.

Этот http_cache параметр принимает любой объект, похожий на дикт. Если это не указано, MSAL будет использовать дикт в памяти.

Если приложение является приложением командной строки (CLI), вы хотите сохранить http_cache в разных запусках CLI. Формат сохраненного файла может измениться из-за отсутствия ограничений на неустойчивый протокол, поэтому реализация должна допускать непредвиденные ошибки загрузки. В следующем рецепте показано, как это сделать:


   # Just add the following lines at the beginning of your CLI script
   import sys, atexit, pickle, logging
   http_cache_filename = sys.argv[0] + ".http_cache"
   try:
       with open(http_cache_filename, "rb") as f:
           persisted_http_cache = pickle.load(f)  # Take a snapshot
   except (
           FileNotFoundError,  # Or IOError in Python 2
           pickle.UnpicklingError,  # A corrupted http cache file
           AttributeError,  # Cache created by a different version of MSAL
           ):
       persisted_http_cache = {}  # Recover by starting afresh
   except:  # Unexpected exceptions
       logging.exception("You may want to debug this")
       persisted_http_cache = {}  # Recover by starting afresh
   atexit.register(lambda: pickle.dump(
       # When exit, flush it back to the file.
       # It may occasionally overwrite another process's concurrent write,
       # but that is fine. Subsequent runs will reach eventual consistency.
       persisted_http_cache, open(http_cache_file, "wb")))

   # And then you can implement your app as you normally would
   app = msal.PublicClientApplication(
       "your_client_id",
       ...,
       http_cache=persisted_http_cache,  # Utilize persisted_http_cache
       ...,
       #token_cache=...,  # You may combine the old token_cache trick
           # Please refer to token_cache recipe at
           # https://msal-python.readthedocs.io/en/latest/#msal.SerializableTokenCache
       )
   app.acquire_token_interactive(["your", "scope"], ...)

Содержимое внутри http_cache дешево, чтобы получить. Нет необходимости совместно использовать их между различными приложениями.

Содержимое внутри http_cache не будет содержать маркеров и личных сведений (PII). Шифрование не требуется.

Новые возможности версии 1.16.0.

Значение по умолчанию: None
instance_discovery
<xref:boolean>

Исторически MSAL подключается к центральной конечной точке, расположенной https://login.microsoftonline.com для получения некоторых метаданных, особенно при использовании незнакомого центра. Это поведение называется обнаружением экземпляров.

Этот параметр по умолчанию использует значение None, которое включает обнаружение экземпляров.

Если вы знаете некоторые органы, которые позволяют MSAL работать с as-is, без участия обнаружения экземпляров рекомендуется:


   known_authorities = frozenset([  # Treat your known authorities as const
       "https://contoso.com/adfs", "https://login.azs/foo"])
   ...
   authority = "https://contoso.com/adfs"  # Assuming your app will use this
   app1 = PublicClientApplication(
       "client_id",
       authority=authority,
       # Conditionally disable Instance Discovery for known authorities
       instance_discovery=authority not in known_authorities,
       )

Если вы не знаете некоторые органы заранее, но по-прежнему хотите, чтобы MSAL принял какие-либо полномочия, которые вы предоставите, вы можете использовать для безусловного False отключения обнаружения экземпляров.

Новая версия 1.19.0.

Значение по умолчанию: None
allow_broker
<xref:boolean>

Deprecated. Взамен рекомендуется использовать enable_broker_on_windows.

Значение по умолчанию: None
enable_pii_log
<xref:boolean>

При включении журналы могут включать личные данные (персональные данные). Это может быть полезно при устранении неполадок с поведением брокера. По умолчанию используется значение False.

Новая версия 1.24.0.

Значение по умолчанию: None
oidc_authority
str

Добавлено в версию 1.28.0: это URL-адрес, определяющий центр OpenID Connect (OIDC) формата https://contoso.com/tenant. MSAL добавит .well-known/openid-configuration" в центр и извлекает метаданные OIDC из него, чтобы выяснить конечные точки.

Примечание. Брокер не будет использоваться для центра OIDC.

Значение по умолчанию: None

Методы

acquire_token_by_auth_code_flow

Проверьте перенаправление ответа проверки подлинности обратно и получите маркеры.

Он автоматически обеспечивает защиту от неce.
acquire_token_by_authorization_code

Вторая половина предоставления кода авторизации.
acquire_token_by_refresh_token

Получение маркеров на основе маркера обновления (RT), полученного в другом месте.

Этот метод используется только в том случае, если у вас есть старые RTS из другого места, и теперь вы хотите перенести их в MSAL. Вызов этого метода приводит к автоматическому хранению новых маркеров в MSAL.

Этот метод не требуется использовать, если вы уже используете MSAL. MSAL автоматически поддерживает RT внутри кэша маркеров, а маркер доступа можно получить при вызове acquire_token_silent.
acquire_token_by_username_password

Получает маркер для данного ресурса с помощью учетных данных пользователя.

На этой странице приведены ограничения потока паролей имени пользователя. https://github.com/AzureAD/microsoft-authentication-library-for-python/wiki/Username-Password-Authentication

[Не рекомендуется] Этот API устарел для потоков общедоступных клиентов и будет удален в будущем выпуске. Вместо этого используйте более безопасный поток. Руководство по миграции: https://aka.ms/msal-ropc-migration
acquire_token_silent

Получение маркера доступа для данной учетной записи без взаимодействия с пользователем.

Он имеет те же параметры, что и acquire_token_silent_with_error. Разница заключается в поведении возвращаемого значения. Этот метод объединяет пустую ошибку кэша и обновляется в одно возвращаемое значение , None. Если приложение не заботится о точной ошибке обновления маркера во время поиска кэша маркеров, этот метод проще и рекомендуется.
acquire_token_silent_with_error

Получение маркера доступа для данной учетной записи без взаимодействия с пользователем.

Это делается либо путем поиска допустимого маркера доступа из кэша, либо путем поиска допустимого маркера обновления из кэша, а затем автоматически использовать его для активации нового маркера доступа.

Этот метод отличает кэш пусто от ошибки обновления маркера. Если приложение заботится об ошибке точного обновления маркера во время поиска кэша маркеров, этот метод подходит. В противном случае рекомендуется использовать другой метод acquire_token_silent .
get_accounts

Получите список учетных записей, которые ранее вошли в систему, т. е. существуют в кэше.

Позже учетная запись может использоваться для acquire_token_silent поиска его маркеров.
get_authorization_request_url

Создает URL-адрес для запуска предоставления кода авторизации.
initiate_auth_code_flow

Инициируйте поток кода проверки подлинности.

Позже, когда ответ достигнет redirect_uri, можно использовать acquire_token_by_auth_code_flow для завершения проверки подлинности или авторизации.
is_pop_supported

Возвращает значение True, если этот клиент поддерживает маркер доступа проверки владения.
remove_account

Выйдите и забудите меня из кэша токенов

acquire_token_by_auth_code_flow

Проверьте перенаправление ответа проверки подлинности обратно и получите маркеры.

Он автоматически обеспечивает защиту от неce.

acquire_token_by_auth_code_flow(auth_code_flow, auth_response, scopes=None, **kwargs)

Параметры

Имя Описание
auth_code_flow
Обязательно
dict

Тот же дикт, возвращенный initiate_auth_code_flow.
auth_response
Обязательно
dict

Дикт строки запроса, полученной от сервера проверки подлинности.
scopes
list[str]

Области, запрошенные для доступа к защищенному API (ресурсу).

Большую часть времени можно оставить пустым.

Если вы запросили согласие пользователя для нескольких ресурсов, вам потребуется указать подмножество необходимых ресурсов initiate_auth_code_flow.

OAuth2 был разработан в основном для одноэлементных служб, где маркеры всегда предназначены для одного ресурса, и только изменения находятся в областях. В Microsoft Entra маркеры можно выдавать для нескольких сторонних ресурсов. Вы можете запросить код авторизации для нескольких ресурсов, но при его активации маркер предназначен только для одного предполагаемого получателя, называемого аудиторией. Поэтому разработчику необходимо указать область, чтобы мы могли ограничить выдачу маркера для соответствующей аудитории.

Значение по умолчанию: None

Возвращаемое значение

Тип Описание

  • Дикт, содержащий "access_token" и /или "id_token", среди прочего, зависит от используемой области. (См. )https://tools.ietf.org/html/rfc6749#section-5.1

  • Дикт, содержащий "error", при необходимости "error_description", "error_uri". (Это либо это или то)

  • Большинство ошибок данных на стороне клиента приведет к исключению ValueError. Таким образом, шаблон использования может быть без каких-либо сведений о протоколе:

    
   def authorize():  # A controller in a web app
       try:
           result = msal_app.acquire_token_by_auth_code_flow(
               session.get("flow", {}), request.args)
           if "error" in result:
               return render_template("error.html", result)
           use(result)  # Token(s) are available in result and cache
       except ValueError:  # Usually caused by CSRF
           pass  # Simply ignore them
       return redirect(url_for("index"))

acquire_token_by_authorization_code

Вторая половина предоставления кода авторизации.

acquire_token_by_authorization_code(code, scopes, redirect_uri=None, nonce=None, claims_challenge=None, **kwargs)

Параметры

Имя Описание
code
Обязательно

Код авторизации, возвращенный сервером авторизации.
scopes
Обязательно
list[str]

(обязательно) Области, запрошенные для доступа к защищенному API (ресурсу).

Если вы запросили согласие пользователя для нескольких ресурсов, здесь обычно требуется предоставить подмножество необходимых в AuthCode.

OAuth2 был разработан в основном для одноэлементных служб, где маркеры всегда предназначены для одного ресурса, и только изменения находятся в областях. В Microsoft Entra маркеры можно выдавать для нескольких сторонних ресурсов. Вы можете запросить код авторизации для нескольких ресурсов, но при его активации маркер предназначен только для одного предполагаемого получателя, называемого аудиторией. Поэтому разработчику необходимо указать область, чтобы мы могли ограничить выдачу маркера для соответствующей аудитории.
nonce

Если при вызове get_authorization_request_urlвы предоставили nonce, то здесь также должен быть указан тот же nonce, чтобы мы проверили его. Исключение будет возникать, если значение nonce в маркере идентификатора не совпадает.

Значение по умолчанию: None
claims_challenge

Параметр claims_challenge запрашивает определенные утверждения, запрашиваемые поставщиком ресурсов, в виде директивы claims_challenge в заголовке www-authentication, возвращаемого из конечной точки UserInfo и (или) маркера идентификатора и (или) маркера доступа. Это строка объекта JSON, содержащего списки утверждений, запрашиваемых из этих расположений.

Значение по умолчанию: None
redirect_uri
Значение по умолчанию: None

Возвращаемое значение

Тип Описание

Дикт, представляющий ответ JSON из Microsoft Entra:

  • Успешный ответ будет содержать ключ "access_token",

  • Ответ на ошибку будет содержать "error" и обычно "error_description".

acquire_token_by_refresh_token

Получение маркеров на основе маркера обновления (RT), полученного в другом месте.

Этот метод используется только в том случае, если у вас есть старые RTS из другого места, и теперь вы хотите перенести их в MSAL. Вызов этого метода приводит к автоматическому хранению новых маркеров в MSAL.

Этот метод не требуется использовать, если вы уже используете MSAL. MSAL автоматически поддерживает RT внутри кэша маркеров, а маркер доступа можно получить при вызове acquire_token_silent.

acquire_token_by_refresh_token(refresh_token, scopes, **kwargs)

Параметры

Имя Описание
refresh_token
Обязательно
str

Старый маркер обновления в виде строки.
scopes
Обязательно
list

Области, сопоставленные с этим старым RT. Каждая область должна находиться в формате платформа удостоверений Майкрософт (версия 2). См. области, не связанные с ресурсами.

Возвращаемое значение

Тип Описание

  • Дикт содержит "error" и некоторые другие ключи, когда произошла ошибка.

  • Дикт не содержит ключа error, означает, что миграция прошла успешно.

acquire_token_by_username_password

Получает маркер для данного ресурса с помощью учетных данных пользователя.

На этой странице приведены ограничения потока паролей имени пользователя. https://github.com/AzureAD/microsoft-authentication-library-for-python/wiki/Username-Password-Authentication

[Не рекомендуется] Этот API устарел для потоков общедоступных клиентов и будет удален в будущем выпуске. Вместо этого используйте более безопасный поток. Руководство по миграции: https://aka.ms/msal-ropc-migration

acquire_token_by_username_password(username, password, scopes, claims_challenge=None, auth_scheme=None, **kwargs)

Параметры

Имя Описание
username
Обязательно
str

Обычно имя участника-участника-участника в виде адреса электронной почты.
password
Обязательно
str

Пароль.
scopes
Обязательно
list[str]

Области, запрошенные для доступа к защищенному API (ресурсу).
claims_challenge

Параметр claims_challenge запрашивает определенные утверждения, запрашиваемые поставщиком ресурсов, в виде директивы claims_challenge в заголовке www-authentication, возвращаемого из конечной точки UserInfo и (или) маркера идентификатора и (или) маркера доступа. Это строка объекта JSON, который содержит списки утверждений, запрашиваемых из этих расположений.

Значение по умолчанию: None
auth_scheme
object

Вы можете предоставить msal.auth_scheme.PopAuthScheme объект, чтобы MSAL получил маркер проверки владения (POP).

Новая версия 1.26.0.

Значение по умолчанию: None

Возвращаемое значение

Тип Описание

Дикт, представляющий ответ JSON из Microsoft Entra:

  • Успешный ответ будет содержать ключ "access_token",

  • Ответ на ошибку будет содержать "error" и обычно "error_description".

acquire_token_silent

Получение маркера доступа для данной учетной записи без взаимодействия с пользователем.

Он имеет те же параметры, что и acquire_token_silent_with_error. Разница заключается в поведении возвращаемого значения. Этот метод объединяет пустую ошибку кэша и обновляется в одно возвращаемое значение , None. Если приложение не заботится о точной ошибке обновления маркера во время поиска кэша маркеров, этот метод проще и рекомендуется.

acquire_token_silent(scopes, account, authority=None, force_refresh=False, claims_challenge=None, auth_scheme=None, **kwargs)

Параметры

Имя Описание
scopes
Обязательно
account
Обязательно
authority
Значение по умолчанию: None
force_refresh
Значение по умолчанию: False
claims_challenge
Значение по умолчанию: None
auth_scheme
Значение по умолчанию: None

Возвращаемое значение

Тип Описание

  • Дикт, содержащий ключ error, и обычно содержит ключ "access_token", если поиск кэша выполнен успешно.

  • Нет, если поиск кэша не дает маркера.

acquire_token_silent_with_error

Получение маркера доступа для данной учетной записи без взаимодействия с пользователем.

Это делается либо путем поиска допустимого маркера доступа из кэша, либо путем поиска допустимого маркера обновления из кэша, а затем автоматически использовать его для активации нового маркера доступа.

Этот метод отличает кэш пусто от ошибки обновления маркера. Если приложение заботится об ошибке точного обновления маркера во время поиска кэша маркеров, этот метод подходит. В противном случае рекомендуется использовать другой метод acquire_token_silent .

acquire_token_silent_with_error(scopes, account, authority=None, force_refresh=False, claims_challenge=None, auth_scheme=None, **kwargs)

Параметры

Имя Описание
scopes
Обязательно
list[str]

(обязательно) Области, запрошенные для доступа к защищенному API (ресурсу).
account
Обязательно

(обязательно) Один из возвращаемых get_accountsобъектом учетной записи. Начиная с MSAL Python 1.23 входные None данные становятся NO-OP и всегда возвращаютсяNone.
force_refresh

Если значение true, он пропустит поиск маркера доступа и попытается найти маркер обновления для получения нового маркера доступа.

Значение по умолчанию: False
claims_challenge

Параметр claims_challenge запрашивает определенные утверждения, запрашиваемые поставщиком ресурсов, в виде директивы claims_challenge в заголовке www-authentication, возвращаемого из конечной точки UserInfo и (или) маркера идентификатора и (или) маркера доступа. Это строка объекта JSON, содержащего списки утверждений, запрашиваемых из этих расположений.

Значение по умолчанию: None
auth_scheme
object

Вы можете предоставить msal.auth_scheme.PopAuthScheme объект, чтобы MSAL получил маркер проверки владения (POP).

Новая версия 1.26.0.

Значение по умолчанию: None
authority
Значение по умолчанию: None

Возвращаемое значение

Тип Описание

  • Дикт, содержащий ключ error, и обычно содержит ключ "access_token", если поиск кэша выполнен успешно.

  • Нет, если в кэше просто нет маркера.

  • Дикт, содержащий ключ error, при сбое обновления маркера.

get_accounts

Получите список учетных записей, которые ранее вошли в систему, т. е. существуют в кэше.

Позже учетная запись может использоваться для acquire_token_silent поиска его маркеров.

get_accounts(username=None)

Параметры

Имя Описание
username

Фильтрация учетных записей только с этим именем пользователя. Без учета регистра.

Значение по умолчанию: None

Возвращаемое значение

Тип Описание

Список объектов учетной записи. Каждая учетная запись — это дикт. Сейчас мы задокументируем только его поле "имя пользователя". Ваше приложение может отобразить эти сведения для конечного пользователя и разрешить пользователю выбрать одну из своих учетных записей.

get_authorization_request_url

Создает URL-адрес для запуска предоставления кода авторизации.

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)

Параметры

Имя Описание
scopes
Обязательно
list[str]

(обязательно) Области, запрошенные для доступа к защищенному API (ресурсу).
state
str

Рекомендуется OAuth2 для защиты CSRF.

Значение по умолчанию: None
login_hint
str

Идентификатор пользователя. Как правило, имя участника-пользователя (UPN).

Значение по умолчанию: None
redirect_uri
str

Адрес для возврата после получения ответа от органа.

Значение по умолчанию: None
response_type
str

Значение по умолчанию — "код" для предоставления кода авторизации OAuth2.

Вы можете использовать другое содержимое, например "id_token" или "token", которое активирует неявное предоставление, но это не рекомендуется.

Значение по умолчанию: code
prompt
str

По умолчанию значение запроса не будет отправлено, даже строковое значение не будет отправлено "none". Необходимо явно указать значение. Допустимые значения — это константы, определенные в <xref:msal.Prompt>.

Значение по умолчанию: None
nonce

Криптографически случайное значение, используемое для устранения атак воспроизведения. См. также спецификации OIDC.

Значение по умолчанию: None
domain_hint

Может быть одним из "потребителей" или "организаций" или домена клиента "contoso.com". Если он включен, он пропустит процесс обнаружения на основе электронной почты, который пользователь проходит на странице входа, что приводит к немного более упрощенной пользовательской среде. Дополнительные сведения о возможных значениях, доступных в документации по потоку проверки подлинности и domain_hint документации.

Значение по умолчанию: None
claims_challenge

Параметр claims_challenge запрашивает определенные утверждения, запрашиваемые поставщиком ресурсов, в виде директивы claims_challenge в заголовке www-authentication, возвращаемого из конечной точки UserInfo и (или) маркера идентификатора и (или) маркера доступа. Это строка объекта JSON, содержащего списки утверждений, запрашиваемых из этих расположений.

Значение по умолчанию: None

Возвращаемое значение

Тип Описание

URL-адрес авторизации в виде строки.

initiate_auth_code_flow

Инициируйте поток кода проверки подлинности.

Позже, когда ответ достигнет redirect_uri, можно использовать acquire_token_by_auth_code_flow для завершения проверки подлинности или авторизации.

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)

Параметры

Имя Описание
scopes
Обязательно
list

Это список строк с учетом регистра.
redirect_uri
str

Optional. Если он не указан, сервер будет использовать предварительно зарегистрированный.

Значение по умолчанию: None
state
str

Непрозрачное значение, используемое клиентом для поддержания состояния между запросом и обратным вызовом. Если эта библиотека отсутствует, эта библиотека автоматически создаст ее внутренне.

Значение по умолчанию: None
prompt
str

По умолчанию значение запроса не будет отправлено, даже строковое значение не будет отправлено "none". Необходимо явно указать значение. Допустимые значения — это константы, определенные в <xref:msal.Prompt>.

Значение по умолчанию: None
login_hint
str

Optional. Идентификатор пользователя. Как правило, имя участника-пользователя (UPN).

Значение по умолчанию: None
domain_hint

Может быть одним из "потребителей" или "организаций" или домена клиента "contoso.com". Если он включен, он пропустит процесс обнаружения на основе электронной почты, который пользователь проходит на странице входа, что приводит к немного более упрощенной пользовательской среде. Дополнительные сведения о возможных значениях, доступных в документации по потоку проверки подлинности и domain_hint документации.

Значение по умолчанию: None
max_age
int

Необязательно. Максимальный возраст проверки подлинности. Указывает допустимое время в секундах с момента последнего проверки подлинности End-User. Если истекшее время больше этого значения, платформа удостоверений Майкрософт будет активно повторно проходить проверку подлинности конечного пользователя.

MSAL Python также автоматически проверяет auth_time в маркере идентификатора.

Новые возможности версии 1.15.

Значение по умолчанию: None
response_mode
str

Необязательно. Указывает метод, с помощью которого должны быть возвращены параметры ответа. Значение по умолчанию эквивалентно queryтому, что по-прежнему достаточно безопасно в MSAL Python (так как MSAL Python не передает маркеры с помощью параметра запроса в первую очередь). Для повышения безопасности рекомендуется использовать значение form_post. В режиме "form_post" параметры ответа будут закодированы как значения формы HTML, передаваемые через метод HTTP POST и закодированные в тексте с помощью формата application/x-www-form-urlencoded. Допустимые значения могут быть "form_post" для HTTP POST для обратного вызова URI или "query" (по умолчанию) для HTTP GET с параметрами, закодированными в строке запроса. Дополнительные сведения о возможных значениях здесь https://openid.net/specs/oauth-v2-multiple-response-types-1_0.html#ResponseModes и здесь https://openid.net/specs/oauth-v2-form-post-response-mode-1_0.html#FormPostResponseMode

Note

Необходимо настроить веб-платформу, чтобы принимать form_post ответы вместо ответов на запросы.

Хотя этот параметр по-прежнему работает, он будет удален в будущей версии.

Использование режимов отклика на основе запросов является менее безопасным и следует избегать.

Значение по умолчанию: None
claims_challenge
Значение по умолчанию: None

Возвращаемое значение

Тип Описание

Поток кода проверки подлинности. Это дикт в этой форме:


   {
       "auth_uri": "https://...",  // Guide user to visit this
       "state": "...",  // You may choose to verify it by yourself,
                        // or just let acquire_token_by_auth_code_flow()
                        // do that for you.
       "...": "...",  // Everything else are reserved and internal
   }

Ожидается, что вызывающий объект:

  1. как-то хранить это содержимое, как правило, внутри текущего сеанса,

  2. руководство пользователя (т. е. владельца ресурса) для посещения этого auth_uri,

  3. затем ретрансляция этого дикта и последующего ответа acquire_token_by_auth_code_flowпроверки подлинности.

is_pop_supported

Возвращает значение True, если этот клиент поддерживает маркер доступа проверки владения.

is_pop_supported()

remove_account

Выйдите и забудите меня из кэша токенов

remove_account(account)

Параметры

Имя Описание
account
Обязательно

Атрибуты

ACQUIRE_TOKEN_BY_AUTHORIZATION_CODE_ID 

ACQUIRE_TOKEN_BY_AUTHORIZATION_CODE_ID = '832'

ACQUIRE_TOKEN_BY_DEVICE_FLOW_ID 

ACQUIRE_TOKEN_BY_DEVICE_FLOW_ID = '622'

ACQUIRE_TOKEN_BY_REFRESH_TOKEN 

ACQUIRE_TOKEN_BY_REFRESH_TOKEN = '85'

ACQUIRE_TOKEN_BY_USERNAME_PASSWORD_ID 

ACQUIRE_TOKEN_BY_USERNAME_PASSWORD_ID = '301'

ACQUIRE_TOKEN_FOR_CLIENT_ID 

ACQUIRE_TOKEN_FOR_CLIENT_ID = '730'

ACQUIRE_TOKEN_INTERACTIVE 

ACQUIRE_TOKEN_INTERACTIVE = '169'

ACQUIRE_TOKEN_ON_BEHALF_OF_ID 

ACQUIRE_TOKEN_ON_BEHALF_OF_ID = '523'

ACQUIRE_TOKEN_SILENT_ID 

ACQUIRE_TOKEN_SILENT_ID = '84'

ATTEMPT_REGION_DISCOVERY 

ATTEMPT_REGION_DISCOVERY = True

DISABLE_MSAL_FORCE_REGION 

DISABLE_MSAL_FORCE_REGION = False

GET_ACCOUNTS_ID 

GET_ACCOUNTS_ID = '902'

REMOVE_ACCOUNT_ID 

REMOVE_ACCOUNT_ID = '903'