ClientApplication クラス

アプリを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) 形式の場合は、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 に設定してサブジェクト名/発行者認証をオプトインできます。

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

(省略可能) これは、基になる要求ライブラリの verify パラメーターに 渡されます。これは、独自の Http クライアントを渡すように選択した場合は適用されません。

(省略可能) 基になる要求ライブラリのプロキシ パラメーター に渡されます。これは、独自の Http クライアントを渡すように選択した場合は適用されません。

(省略可能) 基になる要求ライブラリのタイムアウト パラメーター に渡されます。これは、独自の Http クライアントを渡すように選択した場合は適用されません。

(省略可能)Microsoftテレメトリの目的でアプリケーション名を指定できます。 既定値は None で、Microsoftに渡されないことを意味します。

(省略可能)アプリケーションのバージョンは、Microsoftテレメトリの目的で提供できます。 既定値は None で、Microsoftに渡されないことを意味します。

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

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

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

(省略可能)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 ではリージョンが使用されません。

バージョン 1.12.0 の新機能。

(省略可能)これまで、MSAL は スコープoffline_access ハードコードします。これにより、アプリはユーザーのデータに長時間アクセスできるようになります。 アプリで不要または望ましくない場合は、このパラメーターを使用して、 exclude_scopes = ["offline_access"]などのスコープの除外リストを指定できます。

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

これまで、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の OpenID Connect (OIDC) 機関を識別する URL です。 MSAL は、".well-known/openid-configuration" を機関に追加し、そこから OIDC メタデータを取得してエンドポイントを特定します。

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