Python için ADAL'dan MSAL'ye geçiş kılavuzu

Bu makalede, Microsoft Authentication Library (MSAL) kullanmak için Azure Active Directory Kimlik Doğrulama Kitaplığı'nı (ADAL) kullanan bir uygulamayı geçirmek için yapmanız gereken değişiklikler vurgulanır.

MSAL hakkında daha fazla bilgi edinebilir ve Python için Microsoft Kimlik Doğrulama Kitaplığı genel bakışını kullanmaya başlayabilirsiniz.

Fark vurguları

ADAL, Azure Active Directory (Azure AD) v1.0 uç noktasıyla çalışır. Microsoft Authentication Library (MSAL), eski adıyla Azure Active Directory v2.0 uç noktası olarak bilinen Microsoft kimlik platformu ile çalışır. Microsoft kimlik platformu, Azure AD v1.0'dan farklıdır:

Destekler:

  • İş ve okul hesapları (Microsoft Entra ID sağlanan hesaplar)

  • Kişisel hesaplar (Outlook.com veya Hotmail.com gibi)

  • Azure AD B2C teklifi aracılığıyla kendi e-posta veya sosyal kimliğini (LinkedIn, Facebook, Google gibi) getiren müşterileriniz

  • Standartların uyumlu olup olmadığını:

    • OAuth v2.0
    • OpenID Connect (OIDC)

MSAL hakkında daha fazla bilgi için bkz. MSAL'ye genel bakış.

Kapsamlar, kaynaklar değildir

ADAL Python kaynaklar için belirteçler alır, ancak MSAL Python kapsamlar için belirteçler alır. MSAL Python'daki API yüzeyinin artık kaynak parametresi yoktur. İstenen izinleri ve istenen kaynakları bildiren dizelerin listesi olarak kapsamlar sağlamanız gerekir. Kapsamların bazı örneklerini görmek için bkz. Microsoft Graph kapsamları.

Uygulamalarınızı v1.0 uç noktasından (ADAL) Microsoft kimlik platformuna (MSAL) geçirmenize yardımcı olmak için kaynağa /.default kapsam sonekini ekleyebilirsiniz. Örneğin, kaynak değeri https://graph.microsoft.comiçin eşdeğer kapsam değeri şeklindedir https://graph.microsoft.com/.default. Kaynak URL biçiminde değilse, ancak XXXXXXXX-XXXX-XXXX-XXXXXXXXXXXX biçiminde bir kaynak kimliğiyse, kapsam değerini yine de XXXXXXXX-XXXX-XXXX-XXXXXXXXXXXX/.default olarak kullanabilirsiniz.

Farklı kapsam türleri hakkında daha fazla ayrıntı için Microsoft kimlik platformu İzinler ve onay konusuna ve v1.0 belirteçlerini kabul eden bir Web API'sinin Kapsamları makalelerine bakın.

Hata yönetimi

Python için ADAL, bir sorun olduğunu belirtmek için özel durumu AdalError kullanır. Python için MSAL genellikle bunun yerine hata kodlarını kullanır. Daha fazla bilgi için bkz. Python hata işleme için MSAL.

API değişiklikleri

Aşağıdaki tabloda, Python için ADAL'daki API ile bunun yerine Python için MSAL'de kullanılacak API listelenmektedir:

Python API için ADAL Python API için MSAL
AuthenticationContext PublicClientApplication veya ConfidentialClientApplication
N/A acquire_token_interactive
N/A get_authorization_request_url
N/A initiate_auth_code_flow
acquire_token_with_authorization_code() acquire_token_by_auth_code_flow
acquire_token() acquire_token_silent
acquire_token_with_refresh_token() Bu iki yardımcının yalnızca geçiş sırasında kullanılması amaçlanmıştır: acquire_token_by_refresh_token
acquire_user_code() initiate_device_flow
acquire_token_with_device_code() ve cancel_request_to_get_token_with_device_code() acquire_token_by_device_flow
acquire_token_with_username_password() acquire_token_by_username_password
acquire_token_with_client_credentials() ve acquire_token_with_client_certificate() acquire_token_for_client
N/A acquire_token_on_behalf_of
TokenCache() SerializableTokenCache
N/A MSAL Uzantılarından edinilebilen kalıcı önbellek

MSAL Python için mevcut yenileme belirteçlerini geçirme

MSAL, yenileme belirteçleri kavramını soyutlar. MSAL Python, yenileme belirteçlerini depolamanız, aramanız veya güncelleştirmeniz gerekmeyecek şekilde varsayılan olarak bir bellek içi belirteç önbelleği sağlar. Yenileme belirteçleri genellikle kullanıcı müdahalesi olmadan güncelleştirilebileceğinden kullanıcılar daha az oturum açma istemi de görür. Belirteç önbelleği hakkında daha fazla bilgi için bkz. Python için MSAL'de özel belirteç önbelleği serileştirme.

Aşağıdaki kod, Python için MSAL tarafından yönetilecek başka bir OAuth2 kitaplığı (ADAL Python dahil ancak bunlarla sınırlı olmamak üzere) tarafından yönetilen yenileme belirteçlerinizi geçirmenize yardımcı olur. Bu yenileme belirteçlerini geçirmenin bir nedeni, uygulamanızı Python için MSAL'ye geçirirken mevcut kullanıcıların yeniden oturum açma gereksinimini önlemektir.

Yenileme belirtecini geçirme yöntemi, önceki yenileme belirtecini kullanarak yeni bir erişim belirteci almak üzere Python için MSAL kullanmaktır. Yeni yenileme belirteci döndürülürken, Python için MSAL bunu önbellekte depolar. MSAL Python 1.3.0'dan bu yana bu amaçla MSAL içinde bir API sağlıyoruz. MSAL Python ile yenileme belirteçlerini geçirme işleminin tamamlanmış bir örneğinden alıntılanan aşağıdaki kod parçacığına bakın

import msal
def get_preexisting_rt_and_their_scopes_from_elsewhere():
    # Maybe you have an ADAL-powered app like this
    #   https://github.com/AzureAD/azure-activedirectory-library-for-python/blob/1.2.3/sample/device_code_sample.py#L72
    # which uses a resource rather than a scope,
    # you need to convert your v1 resource into v2 scopes
    # See https://learn.microsoft.com/azure/active-directory/develop/migrate-python-adal-msal#scopes-not-resources
    # You may be able to append "/.default" to your v1 resource to form a scope
    # See https://learn.microsoft.com/azure/active-directory/develop/v2-permissions-and-consent#the-default-scope

    # Or maybe you have an app already talking to the Microsoft identity platform,
    # powered by some 3rd-party auth library, and persist its tokens somehow.

    # Either way, you need to extract RTs from there, and return them like this.
    return [
        ("old_rt_1", ["scope1", "scope2"]),
        ("old_rt_2", ["scope3", "scope4"]),
        ]


# We will migrate all the old RTs into a new app powered by MSAL
app = msal.PublicClientApplication(
    "client_id", authority="...",
    # token_cache=...  # Default cache is in memory only.
                       # You can learn how to use SerializableTokenCache from
                       # https://msal-python.readthedocs.io/en/latest/#msal.SerializableTokenCache
    )

# We choose a migration strategy of migrating all RTs in one loop
for old_rt, scopes in get_preexisting_rt_and_their_scopes_from_elsewhere():
    result = app.acquire_token_by_refresh_token(old_rt, scopes)
    if "error" in result:
        print("Discarding unsuccessful RT. Error: ", json.dumps(result, indent=2))

print("Migration completed")
  • Last updated on