ConfidentialClientApplication クラス

<xref:ClientApplication.__init__>と同じですが、パラメーターallow_brokerNone残る点が異なります。

アプリケーションのインスタンスを作成します。

コンストラクター

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

アプリをMicrosoft Entra 管理センターに登録した後、アプリにclient_idがあります。
client_credential
Union[dict, str, None]

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) 形式の場合は、openssl pkcs12 -in file.pfx -out file.pem -nodesして X.509 (.pem) 形式に変換できます。拇印は、アプリの登録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 に設定してサブジェクト名/発行者認証をオプトインできます。

規定値: 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 以降では、接続エラー時に 1 回の再試行を試行するように既定のセッションが構成されます。 独自のhttp_clientを提供する場合、再試行を実行するかどうかを決定するのはhttp_clientの義務です。

規定値: None
verify

(省略可能) これは、基になる要求ライブラリの 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]

(省略可能)1 つ以上のクライアント機能 (例: [CP1") の構成を許可します。

クライアント機能は、このクライアントが何に対応できるかをMicrosoft ID プラットフォーム (STS) に通知することを目的としているため、STS は特定の機能を有効にすることを決定できます。 たとえば、クライアントが 要求チャレンジを処理できる場合、STS はリソース に対して継続的アクセス評価 (CAE) アクセス トークンを発行し、リソースが 要求チャレンジ を出力するときにクライアントがそれらのチャレンジを処理できることを認識できます。

実装の詳細: クライアント機能は、現時点では、ネットワーク上の "claims" パラメーターを使用して実装されています。 MSAL は、それらを 要求パラメーター に結合します。このパラメーターは、後で取得トークン要求の 1 つを介して指定します。

規定値: None
azure_region
str

(省略可能)Entra リージョン トークン サービスを使用するように MSAL に指示します。 このレガシ機能は、ファースト パーティのアプリケーションでのみ使用できます。 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

リージョンの自動検出は、VM とAzure Functionsでテストされています。 信頼性が低い。

このオプションを使用するアプリケーションでは、短いタイムアウトを構成する必要があります。

詳細とリージョン文字列の値については、

見る 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 応答の有限量を自動的にキャッシュすることで、http_cacheの概念も導入しました。そのため、一部の状況では、有効期間が長くPublicClientApplicationConfidentialClientApplicationのパフォーマンスが向上し、応答性が向上します。

この 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 の新機能。

規定値: 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>

有効にすると、ログに PII (個人を特定できる情報) が含まれる場合があります。 これは、ブローカーの動作のトラブルシューティングに役立ちます。 既定の動作は False です。

バージョン 1.24.0 の新機能。

規定値: None
oidc_authority
str

バージョン 1.28.0 で追加: https://contoso.com/tenant形式の OpenID Connect (OIDC) 機関を識別する URL です。 MSAL は、".well-known/openid-configuration" を機関に追加し、そこから OIDC メタデータを取得してエンドポイントを特定します。

注: ブローカーは OIDC 権限には使用されません。

規定値: None

メソッド

acquire_token_for_client

エンド ユーザーではなく、現在の機密クライアントのトークンを取得します。

MSAL Python 1.23 であるため、キャッシュからトークンが自動的に検索され、キャッシュミス時にのみ ID プロバイダーに要求が送信されます。
acquire_token_on_behalf_of

代理 (OBO) フローを使用してトークンを取得します。

現在のアプリは、エンド ユーザーを表すトークンを使用して呼び出された中間層サービスです。 現在のアプリでは、このようなトークン (ユーザー アサーションなど) を使用して、そのユーザーの代わりにダウンストリーム Web 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 であるため、キャッシュからトークンが自動的に検索され、キャッシュミス時にのみ ID プロバイダーに要求が送信されます。

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

パラメーター

名前 説明
scopes
必須
list[str]

(必須)保護された API (リソース) へのアクセスを要求されたスコープ。
claims_challenge

claims_challenge パラメーターは、リソース プロバイダーによって要求された特定の要求を、www-authenticate ヘッダーの claims_challenge ディレクティブの形式で、UserInfo エンドポイントまたは ID トークンまたはアクセス トークンから返されるように要求します。 これは、これらの場所から要求される要求の一覧を含む JSON オブジェクトの文字列です。

規定値: None
fmi_path
str

オプション。 フェデレーション マネージド ID (FMI) 資格情報パス。 指定すると、トークン要求本文で fmi_path パラメーターとして送信され、結果のトークンは個別にキャッシュされるため、異なる FMI パスでキャッシュされたトークンが共有されません。 使用例:


   result = cca.acquire_token_for_client(
       scopes=["api://resource/.default"],
       fmi_path="SomeFmiPath/FmiCredentialPath",
   )
規定値: None

返品

型 説明

Microsoft Entraからの json 応答を表すディクテーション:

  • 成功した応答には、"access_token" キーが含まれます。

  • エラー応答には、"error" と通常は "error_description" が含まれます。

acquire_token_on_behalf_of

代理 (OBO) フローを使用してトークンを取得します。

現在のアプリは、エンド ユーザーを表すトークンを使用して呼び出された中間層サービスです。 現在のアプリでは、このようなトークン (ユーザー アサーションなど) を使用して、そのユーザーの代わりにダウンストリーム Web 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 パラメーターは、リソース プロバイダーによって要求された特定の要求を、www-authenticate ヘッダーの claims_challenge ディレクティブの形式で、UserInfo エンドポイントまたは ID トークンまたはアクセス トークンから返されるように要求します。 これは、これらの場所から要求される要求の一覧を含む JSON オブジェクトの文字列です。

規定値: None

返品

型 説明

Microsoft Entraからの json 応答を表すディクテーション:

  • 成功した応答には、"access_token" キーが含まれます。

  • エラー応答には、"error" と通常は "error_description" が含まれます。

remove_tokens_for_client

現在のクライアントの acquire_token_for_client を使用して以前に取得したすべてのトークンを削除します。

remove_tokens_for_client()