ConfidentialClientApplication 클래스

Microsoft Entra 관리 센터 등록한 후 앱에 client_id 있습니다.

여기서PublicClientApplication는 None을 사용합니다.

예를 ConfidentialClientApplication들어 다양한 시나리오에 대해 다양한 입력 형식을 지원합니다.

클라이언트 비밀 사용을 지원합니다. 와 같은 "your client secret"문자열에 피드하기만 하면됩니다.

SHA-1 지문을 사용하기 때문에 X.509(.pem) 형식의 인증서 사용을 지원합니다.

SHA-1 지문만 지원하는 ADFS를 계속 사용하지 않는 한 이 페이지의 뒷부분에 설명된 .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 PEM 형식의 "private_key"이 필요합니다. 인증서가 PKCS12(.pfx) 형식인 경우 X.509(.pem) 형식으로 변환할 openssl pkcs12 -in file.pfx -out file.pem -nodes수 있습니다. 지문은 Azure Portal 앱 등록에서 사용할 수 있습니다. 또는 지문을 계산할 수 있습니다. public_certificate (선택 사항)은 'x5c' JWT 헤더를 통해 전송되는 공개 키 인증서입니다. 이는 인증서 회전을 더 쉽게 허용하는 방법인 주체 이름/발급자 인증 을 사용할 때 유용합니다. 사양별로 "JWS에 디지털 서명하는 데 사용되는 키에 해당하는 공개 키가 포함된 인증서는 첫 번째 인증서여야 합니다. 이후 각 후속 인증서가 이전 인증서를 인증하는 데 사용되는 인증서로 추가될 수 있습니다." 그러나 인증서의 발급자는 다른 순서를 사용할 수 있습니다. 따라서 "제공된 서명 값이 예상된 서명 값과 일치하지 않음"이라는 오류 AADSTS700027 오류가 발생하면 리프 인증서(PEM/str 형식)만 대신 사용할 수 있습니다.

버전 1.13.0에 추가된 다른 위치에서 가져온 원시 어설션 지원:

직접 어셈블한 완전히 미리 서명된 어설션일 수도 있습니다. 다음과 같이 "client_assertion" 키만 포함하는 컨테이너를 전달하기만 하면 됩니다.

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

PFX 파일에서 클라이언트 인증서 읽기 지원이 사용되면 인증서의 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)",
   }

다음 명령은 .key 및 .pem 파일에서 .pfx 파일을 생성합니다.

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

주체 이름/발급자 인증 은 인증서 회전을 쉽게 허용하는 방법입니다. .pfx 파일에 프라이빗 키와 공용 인증서가 모두 포함된 경우 "public_certificate"을 로 설정하여 주체 이름/발급자 인증을 옵트인할 True수 있습니다.

버전 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
   }

토큰 기관을 식별하는 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, ...)

(선택 사항) 권한 유효성 검사를 켜거나 끕니다. 이 매개 변수는 기본적으로 true입니다.

이 ClientApplication 인스턴스에서 사용하는 토큰 캐시를 설정합니다. 기본적으로 메모리 내 캐시가 만들어지고 사용됩니다.

(선택 사항) 추상 클래스 HttpClient <msal.oauth2cli.http.http_client> 구현은 요청 세션 인스턴스에 기본값입니다. MSAL 1.11.0부터 연결 오류 시 다시 시도하도록 기본 세션이 구성됩니다. 고유한 http_client 제공하는 경우 재시도 여부를 결정하는 것이 http_client 의무입니다.

(선택 사항) 기본 요청 라이브러리의 verify 매개 변수에 전달됩니다. 사용자 고유의 Http 클라이언트를 전달하도록 선택한 경우에는 적용되지 않습니다.

(선택 사항) 기본 요청 라이브러리의 프록시 매개 변수에 전달됩니다. 사용자 고유의 Http 클라이언트를 전달하도록 선택한 경우에는 적용되지 않습니다.

(선택 사항) 기본 요청 라이브러리의 시간 제한 매개 변수에 전달됩니다. 사용자 고유의 Http 클라이언트를 전달하도록 선택한 경우에는 적용되지 않습니다.

(선택 사항) Microsoft 원격 분석을 위해 애플리케이션 이름을 제공할 수 있습니다. 기본값은 None입니다. 즉, Microsoft 전달되지 않습니다.

(선택 사항) Microsoft 원격 분석을 위해 애플리케이션 버전을 제공할 수 있습니다. 기본값은 None입니다. 즉, Microsoft 전달되지 않습니다.

(선택 사항) 하나 이상의 클라이언트 기능(예: ["CP1"])을 구성할 수 있습니다.

클라이언트 기능은 이 클라이언트가 수행할 수 있는 기능을 STS(Microsoft ID 플랫폼)에 알리기 위한 것이므로 STS는 특정 기능을 켤 수 있습니다. 예를 들어 클라이언트가 클레임 챌린지를 처리할 수 있는 경우 STS는 리소스가 클레임 챌린지를 내보낼 때 클라이언트가 이러한 문제를 처리할 수 있다는 것을 알고 리소스에 CAE(지속적인 액세스 평가) 액세스 토큰을 발급할 수 있습니다.

구현 세부 정보: 클라이언트 기능은 현재 유선에서 "클레임" 매개 변수를 사용하여 구현됩니다. MSAL은 나중에 획득 토큰 요청 중 하나를 통해 제공할 클레임 매개 변수 로 결합합니다.

(선택 사항) 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이 지역을 사용하지 않음을 의미합니다.

버전 1.12.0의 새로운 기능

(선택 사항) 지금까지 MSAL 하드 코드는 범위 offline_access 앱이 사용자의 데이터에 장기간 액세스할 수 있도록 합니다. 앱에 불필요하거나 바람직하지 않은 경우 이제 이 매개 변수를 사용하여 범위의 제외 목록(예: exclude_scopes = ["offline_access"])을 제공할 수 있습니다.

MSAL은 오랫동안 .에서 token_cache토큰을 캐싱해 왔습니다. 최근에 MSAL은 몇 가지 유한량의 http_cache비 토큰 http 응답을 자동으로 캐싱하여 수 명이PublicClientApplication 길고 일부 상황에서 더 성능이 뛰어나고 ConfidentialClientApplication 응답성이 뛰어난 개념을 도입했습니다.

이 http_cache 매개 변수는 dict와 유사한 개체를 허용합니다. 제공되지 않은 경우 MSAL은 메모리 내 받아쓰기를 사용합니다.

앱이 CLI(명령줄 앱)인 경우 여러 CLI 실행에서 http_cache 유지하려고 합니다. 지속형 파일의 형식은 불안정한 프로토콜로 인해 변경될 수 있지만 이에 국한되지 않으므로 구현에서 예기치 않은 로드 오류를 허용할 수 있습니다. 다음 레시피는 이렇게 하는 방법을 보여줍니다.

   # 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의 새로운 기능

지금까지 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의 새로운 기능

Deprecated. 대신 enable_broker_on_windows를 사용하십시오.

사용하도록 설정하면 로그에 PII(개인 식별 가능 정보)가 포함될 수 있습니다. 브로커 동작 문제 해결에 유용할 수 있습니다. 기본 동작은 False입니다.

버전 1.24.0의 새로운 기능

버전 1.28.0에 추가됨: 형식 https://contoso.com/tenant의 OIDC(OpenID Connect) 권한을 식별하는 URL입니다. MSAL은 ".well-known/openid-configuration"을 기관에 추가하고 여기에서 OIDC 메타데이터를 검색하여 엔드포인트를 파악합니다.

참고: Broker는 OIDC 기관에 사용되지 않습니다.