ConfidentialClientApplication Класс

То же самое, что <xref:ClientApplication.__init__>и этот allow_broker параметр, должен остаться None.

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

Конструктор

ConfidentialClientApplication(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> По умолчанию для экземпляра сеанса запросов. Так как 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_for_client

Получает маркер для текущего конфиденциального клиента, а не для конечного пользователя.

Так как MSAL Python 1.23, он будет автоматически искать маркер из кэша и отправлять запрос только поставщику удостоверений при отсутствии кэша.
acquire_token_on_behalf_of

Получает маркер с помощью потока от имени (OBO).

Текущее приложение — это служба среднего уровня, которая была вызвана маркером, представляющим конечного пользователя. Текущее приложение может использовать такой маркер (a.k.a. утверждение пользователя) для запроса другого маркера для доступа к нижестоящему веб-API от имени этого пользователя. Дополнительные сведения см. здесь.

Текущее приложение среднего уровня не имеет взаимодействия с пользователем для получения согласия. Узнайте, как получить согласие для вашего приложения среднего уровня из этой статьи. https://docs.microsoft.com/en-us/azure/active-directory/develop/v2-oauth2-on-behalf-of-flow#gaining-consent-for-the-middle-tier-application
remove_tokens_for_client

Удалите все маркеры, которые ранее были приобретены через acquire_token_for_client текущий клиент.

acquire_token_for_client

Получает маркер для текущего конфиденциального клиента, а не для конечного пользователя.

Так как MSAL Python 1.23, он будет автоматически искать маркер из кэша и отправлять запрос только поставщику удостоверений при отсутствии кэша.

acquire_token_for_client(scopes, claims_challenge=None, fmi_path=None, **kwargs)

Параметры

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

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

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

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

Optional. Путь к учетным данным федеративного управляемого удостоверения (FMI). При указании он отправляется в качестве fmi_path параметра в тексте запроса маркера, а полученный маркер кэшируется отдельно, чтобы разные пути FMI не совместно используют кэшированные маркеры. Пример использования:


   result = cca.acquire_token_for_client(
       scopes=["api://resource/.default"],
       fmi_path="SomeFmiPath/FmiCredentialPath",
   )
Значение по умолчанию: None

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

Тип Описание

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

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

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

acquire_token_on_behalf_of

Получает маркер с помощью потока от имени (OBO).

Текущее приложение — это служба среднего уровня, которая была вызвана маркером, представляющим конечного пользователя. Текущее приложение может использовать такой маркер (a.k.a. утверждение пользователя) для запроса другого маркера для доступа к нижестоящему веб-API от имени этого пользователя. Дополнительные сведения см. здесь.

Текущее приложение среднего уровня не имеет взаимодействия с пользователем для получения согласия. Узнайте, как получить согласие для вашего приложения среднего уровня из этой статьи. https://docs.microsoft.com/en-us/azure/active-directory/develop/v2-oauth2-on-behalf-of-flow#gaining-consent-for-the-middle-tier-application

acquire_token_on_behalf_of(user_assertion, scopes, claims_challenge=None, **kwargs)

Параметры

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

Входящие маркеры, уже полученные этим приложением
scopes
Обязательно
list[str]

Области, необходимые нижестоящим API (ресурс).
claims_challenge

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

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

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

Тип Описание

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

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

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

remove_tokens_for_client

Удалите все маркеры, которые ранее были приобретены через acquire_token_for_client текущий клиент.

remove_tokens_for_client()