Belirteçleri edinin

MSAL Python ile belirteç almanın birçok yolu vardır. Bazıları kullanıcı etkileşimi gerektirirken, diğerleri bunu gerektirmez. Belirteç almak için kullanılan yaklaşım, geliştiricinin bir genel istemci (masaüstü veya mobil) veya gizli bir istemci uygulaması (web uygulaması, web API'si veya Windows hizmeti gibi daemon) oluşturmasına bağlı olarak farklıdır.

Prerequisites

MSAL Python ile belirteçleri almadan önce istemci uygulaması türleri hakkında bilgi edinin.

Kullanıcı hesabı alma

Bir uygulama, bir belirteci kendi adıyla veya kullanıcı adına alabilir. Bir kullanıcı adına belirteç almak için uygulamanın kullanıcının hesabını bilmesi gerekir. MSAL Python, kullanıcının hesabını almak için get_accounts yöntemini sağlar. Bu yöntem hem hem de PublicClientApplicationConfidentialClientApplication sınıflarında kullanılabilir. yöntemi, kullanıcının daha önce oturum açtığı, yani önbellekte var olan hesapların listesini döndürür.

accounts = app.get_accounts(username=user.get("preferred_username"))

Kullanıcının oturum açmak için seçtiği hesap, daha sonra acquire_token_silent() içinde belirteçlerini bulmak için kullanılabilir.

Jeton verme akışları

MSAL Python ile belirteçleri almak için kullanılabilecek çeşitli kimlik doğrulama akışları vardır. Bu akışlar hakkında daha fazla bilgiyi Microsoft kimlik platformu belgelerinde bulabilirsiniz.

Warning

Uygulamalarınızda güvenlik belirteçlerini almak ve korumalı web API'lerini çağırmak için her zaman MSAL kullanın. Kendi belirteç alma mantığınızı uygulamanızı önermiyoruz. Bu akışlar, işlerin nasıl çalıştığını daha iyi anlamanıza yardımcı olur. Bir web uygulamasının güvenliğini sağlıyorsanız kimlik kitaplığını kullanmanızı öneririz. Bu kitaplık resmi olarak Microsoft tarafından korunmaz, ancak web uygulamalarında belirteçleri almak için ihtiyacınız olan mantığın çoğunu uygular.

Etkileşimli ve sessiz

MSAL Python hem etkileşimli hem de sessiz belirteç alımını destekler. Etkileşimli belirteç alımı için kullanıcı etkileşimi gerekirken sessiz belirteç alımı gerekli değildir. Genel istemciler genellikle kullanıcı etkileşimi gerektirirken, gizli istemciler sertifikalar ve gizli anahtarlar gibi önceden sağlanmış kimlik bilgilerine dayanır.

Bir belirteci sessizce edinmek için acquire_token_silent_with_error yöntemini kullanın. Bu yöntem, önbellekten geçerli bir erişim belirteci ya da önbellekten geçerli bir yenileme belirteci bulur ve ardından bunu yeni bir erişim belirteci almak için otomatik olarak kullanır. Hiçbiri doğru değilse, belirteci almak için etkileşimli bir yöntem kullanmanız gerekir.

Uygulamanız belirteç önbelleği arama sırasında tam belirteç yenileme hatasını önemsemiyorsa acquire_token_silent yöntemi önerilir.

Aşağıdaki kod parçacığında gösterildiği gibi bu yöntemin örnek kullanımıdır.

if accounts:
    # If so, you could then somehow display these accounts and let end user choose
    chosen = accounts[0]
    result = app.acquire_token_silent(scopes=["your_scope"], account=chosen)
    
    # At this point, you can save you can update your cache if you are using token caching
    # check result variable, if its None then you should interactively acquire a token
    if not result:
        # So no suitable token exists in cache. Let's get a new one from Microsoft Entra.
        result = app.acquire_token_by_one_of_the_actual_method(..., scopes=["User.Read"])
    
    if "access_token" in result:
        access_token = result["access_token"]
    else:
        print(result.get("error"))  
        print(result.get("error_description"))
        print(result.get("correlation_id"))  # You may need this when reporting a bug

Etkileşimli belirteç alımı için çeşitli yöntemler kullanılabilir. Kullanılacak yöntem, oluşturduğunuz uygulamanın türüne ve senaryonuz için geçerli olan belirteç verme akışına bağlıdır.

Ortak istemciler için etkileşimli belirteç edinimi

Genel istemci uygulamaları bir gizli diziyi güvenli bir şekilde depolayamaz ve yalnızca ürünle etkileşim kuran kullanıcının kimliğini doğrulayabilir. MSAL Python, genel uygulamalara yönelik belirteç edinme mantığını PublicClientApplication aracılığıyla kullanıma sunar. Aşağıda, genel istemci uygulamalarının belirteç edinmek için kullanabileceği farklı yöntemler verilmiştir.

Cihaz kodu akışı

Cihaz kodu akışı , web tarayıcısına erişimi olmayan cihazlarda çalışan uygulamalarda belirteçleri almak için kullanılır. Bunlar, başsız uygulamalar olarak bilinir. Bu akış kullanıcıya bir URL ve kod sağlar. Kullanıcı başka bir cihazdaki bir web tarayıcısına gider, kodu girer ve oturum açar. Kimlik doğrulaması başarılı olduğunda Microsoft Entra, tarayıcısı olmayan cihaza bir belirteç gönderir.

İlk olarak yöntemini çağırırsınız initiate_device_flow .

flow = app.initiate_device_flow(scopes=config["scope"])
if "user_code" not in flow:
    raise ValueError(
        "Fail to create device flow. Err: %s" % json.dumps(flow, indent=4))

print(flow["message"])
sys.stdout.flush()  # Some terminal needs this to ensure the message is shown

# Ideally you should wait here, in order to save some unnecessary polling
# input("Press Enter after signing in from another device to proceed, CTRL+C to abort.")

Ardından, belirteci almak için akış sözlüğü nesnesini acquire_token_by_device_flow yöntemine geçirirsiniz. Varsayılan olarak, bu yöntem mevcut iş parçacığını engeller. Blok süresini kısaltmak için bu yönergeleri izleyebilir veya engelleme davranışını kapatabilir ve ardından kendi özelleştirilmiş döngünüzde aramaya acquire_token_by_device_flow devam edebilirsiniz.

result = app.acquire_token_by_device_flow(flow)

if "access_token" in result:
    access_token = result["access_token"]
else:
    print(result.get("error"))  

Başarılı bir yanıt, access_token anahtarını içeren bir sözlüktür.

Etkileşimli belirteç alma

MSAL Python ayrıca ortak istemci uygulamalarının (masaüstü ve mobil) kullanıcı adına belirteç almasına olanak sağlar. Kullanıcı, yetkilendirme isteği URL'si aracılığıyla bir web tarayıcısı aracılığıyla oturum açar. Uygulamanızın yeniden yönlendirme URI’sini, Microsoft Entra yönetim merkezinde uygulama kaydınız için http://localhost olarak ayarlayın. PublicClientApplication oluşturma sırasında aracıyı kullanmayı seçerseniz, uygulamanızın ms-appx-web://Microsoft.AAD.BrokerPlugin/YOUR_CLIENT_ID öğesini yeniden yönlendirme URI’si olarak da kaydetmesi gerekir.

result = app.acquire_token_interactive(  # It automatically provides PKCE protection
    scopes=config["scope"])

if "access_token" in result:
    access_token = result["access_token"]
else:
    print(result.get("error"))  

Kullanıcı adı ve parola

Warning

Bu api, güvenlik riskleri nedeniyle genel istemci akışları için kullanım dışı bırakıldı, daha güvenli bir akış kullanın. Geçiş kılavuzu için bu kılavuzu izleyin.

Bu yaklaşımı kullanmanızı önermiyoruz. Kullanıcı adı ve parola içeren bir belirteç almak da mümkündür. MSAL Python bu kullanım örneğinin acquire_token_by_username_password yöntemini sağlar. Uygulama, güvenli olmayan bir desen olan parolayı doğrudan kullanıcıdan istediği için önerilmez.

Kullanabileceğiniz daha güvenli akışlar vardır. Kullanıcı adı ve parola kimlik doğrulaması akışı kılavuzunda daha fazla bilgi edinin.

result = app.acquire_token_by_username_password(
    username=config["username"], password=config["password"], scopes=config["scope"])

if "access_token" in result:
    access_token = result["access_token"]
else:
    print(result.get("error"))  

Gizli istemciler için etkileşimli belirteç edinme

Gizli istemci uygulamaları bir gizli diziyi güvenli bir şekilde depolayabilir ve hem uygulama hem de belirli bir kullanıcı adına kimlik doğrulaması yapabilir. MSAL Python, ConfidentialClientApplication geliştirirken belirteç edinmek için geliştiricilere çeşitli yöntemler sunar.

İstemci için belirteç edinme

Belirteci, bir kullanıcı için değil, istemci kimlik bilgilerini kullanarak uygulamanın kendisi adına alın. Örneğin, bu, eşitleme araçları gibi belirli bir kullanıcıyı değil, kullanıcıları toplu olarak işleyen uygulamalarda kullanılabilir. MSAL Python, bunu yapmak için acquire_token_for_client yöntemini sağlar. MSAL Python 1.23'ten bu yana bu yöntem otomatik olarak önbellekten belirteç arar ve yalnızca önbellek yanıt vermediğinde kimlik sağlayıcısına istek gönderir.

result = app.acquire_token_for_client(scopes=config["scope"])

if "access_token" in result:
    access_token = result["access_token"]
else:
    print(result.get("error"))    

Adına belirteç alma

Kullanıcı adına başka bir aşağı akış Web API'sini çağıran web uygulamaları veya web API'leri söz konusu olduğunda, kullanıcı beyanına dayalı bir belirteç edinmek için On Behalf Of flow'u kullanın. Örneğin, SAML ve JWT. Geçerli uygulama, son kullanıcıyı temsil eden bir belirteçle çağrılan bir orta katman hizmetidir. Geçerli uygulama, kullanıcı onayı olarak da bilinen bu tür bir belirteci kullanarak o kullanıcı adına aşağı akış web API'sine erişmek üzere başka bir belirteç isteyebilir. Orta katman uygulamasında rıza almak için kullanıcı etkileşimi bulunmaz. Orta katman uygulamanız için önceden onay alma hakkında bilgi için belgelere bakın.

İşte, acquire_token_on_behalf_of yöntemini kullanarak bir erişim belirteci alan kod örneği.

def get(self, request): # a web service endpoint receiving a request
    
    scopes = ["your-scopes"]
    downstream_api = "https://your-downstreamapi.com/resource" #your downstream API resource endpoint
    current_access_token = request.headers.get("Authorization", None)
    
    # initialize the app
    app = msal.ConfidentialClientApplication(...) # refer to initialization of the app documentation

    #acquire token on behalf of the user that called this API
    downstream_api_access_token = app.acquire_token_on_behalf_of(
        user_assertion=current_app_access_token.split(' ')[1],
        scopes=_scopes
    )

    if "access_token" in result:
        access_token = result["access_token"]
        # use access_token to call dowstream API e.g
        requests.get(downstream_api, headers={'Authorization': f'Bearer {downstream_api_access_token}'})
    else:
        print(result.get("error")) 

Yetkilendirme kodu akışıyla belirteç edinme

Kullanıcı adına kimlik doğrulaması yapılan web uygulamaları için, kullanıcının yetkilendirme isteği URL'si aracılığıyla oturum açmasına izin verdikten sonra yetkilendirme kodu aracılığıyla belirteçler alın. Bu genellikle kullanıcının bu kullanıcı için oturum açmasını ve web API'lerine erişmesini sağlayan bir uygulama tarafından kullanılan mekanizmadır.

Öncelikle, initiate_auth_code_flow kullanarak kimlik doğrulama kodu akışını başlatmanız gerekir. Bu yöntem, diğer parametreler arasında bir yeniden yönlendirme URI'sini ve durum dizesini alır. Durum parametresinin değeri de belirteç yanıtına eklenir. Bu değer yoksa, MSAL Python otomatik olarak dahili olarak bir değer oluşturur. Sağlanan yeniden yönlendirme URI'sinin Microsoft Entra yönetim merkezi kaydedilen yeniden yönlendirme URI'sine uyması gerekir. Bu yöntem, auth_uri ve state içeren bir sözlük olan kimlik doğrulama kodu akışını döndürür. auth_uri, kullanıcının oturum açmak için ziyaret etmesi gereken URL'dir.

flow = app.initiate_auth_code_flow(
    scopes=config["scope"], redirect_uri=config["redirect_uri"], state="your-state-value")

if "error" in flow:
    print(flow.get("error"))

# Save the response somewhere e.g in session
session["auth_flow"] = flow

# At this point, the app should guide the user to visit the auth ur (session["auth_flow"]["auth_uri"])

auth URI uç noktaları ziyaret edilerek alınan yanıt, acquire_token_by_auth_code_flow yönteminde kullanılır. Durum, yetkilendirme sunucusundan yanıtı doğrulamak için kullanabileceğiniz benzersiz bir tanımlayıcıdır. Kullanıcı oturum açma sırasında kapsamlara onay vermelidir.

# The uth_response value from visiting the auth_uri endpoint is passed as a query string
# You can change this by passing a value to the response_mode in the initiate_auth_code_flow method
try:
    result = app.acquire_token_by_auth_code_flow(session.get("flow", {}), auth_response)
    
    if "access_token" in result:
        access_token = result["access_token"]
    else:
        print(result.get("error"))
except ValueError:  # Usually caused by CSRF
    pass  # Simply ignore them

MSAL Python belirteç önbellekleme

Hem ortak hem de gizli istemci uygulamaları, belirteçlerin önbelleğe alınmasını destekler; bu işlem doğrudan MSAL Python tarafından yönetilir. Uygulamalar, başka yöntemlere güvenmeden önce önbellekten belirteç almaya çalışmalıdır. Daha fazla bilgi için bkz. önerilen belirteç alma düzeni.

Önbelleği kalıcı hale getirebilmek için geliştiricilerin belirteç önbelleği serileştirme mantığını yapılandırması gerekir.