Web API'lerini çağıran bir web uygulaması: Kod yapılandırması

Makale
10/24/2023

Kullanıcılar senaryosunda oturum açma web uygulamasında gösterildiği gibi, web uygulaması kullanıcıyı oturum açmak için OAuth 2.0 yetkilendirme kodu akışını kullanır. Bu akışın iki adımı vardır:

Yetkilendirme kodu isteyin. Bu bölüm, kullanıcıyla Microsoft kimlik platformu özel bir iletişim kutusu temsil eder. Bu iletişim kutusu sırasında kullanıcı oturum açar ve web API'lerinin kullanımını onaylar. Özel iletişim kutusu başarıyla sona erdiğinde, web uygulaması yeniden yönlendirme URI'sinde bir yetkilendirme kodu alır.
Yetkilendirme kodunu kullanarak API için erişim belirteci isteyin.

Kullanıcı senaryolarında oturum açabilen Web uygulaması yalnızca ilk adımı ele alır. Burada, web uygulamanızı yalnızca kullanıcıların oturumunu açmakla kalmaz, aynı zamanda web API'lerini de çağıracak şekilde nasıl değiştireceğinizi öğreneceksiniz.

Web uygulamalarını destekleyen Microsoft kitaplıkları

Aşağıdaki Microsoft kitaplıkları web uygulamalarını destekler:

Dil / çerçeve	Proje açık GitHub	Paket	Alma birini seçin	Oturum açma kullanıcıları	Web API'lerine erişme	Genel kullanıma açık (GA) veya Genel önizleme¹
.NET	MSAL.NET	Microsoft.Identity.Client	—			GA
.NET	Microsoft.IdentityModel	Microsoft.IdentityModel	—	²	²	GA
ASP.NET Core	ASP.NET Core	Microsoft.AspNetCore.Authentication	Hızlı Başlangıç			GA
ASP.NET Core	Microsoft.Identity.Web	Microsoft.Identity.Web	Hızlı Başlangıç			GA
Java	MSAL4J	msal4j	Hızlı Başlangıç			GA
Spring	spring-cloud-azure-starter-active-directory	spring-cloud-azure-starter-active-directory	Öğretici			GA
Node.js	MSAL Düğümü	msal-node	Hızlı Başlangıç			GA
Python	MSAL Python	msal				GA
Python	Kimlik	Kimlik	Hızlı Başlangıç			--

⁽¹⁾Çevrimiçi Hizmetler için Evrensel Lisans Koşulları, Genel önizlemedeki kitaplıklar için geçerlidir.

⁽²⁾Microsoft.IdentityModel kitaplığı yalnızca belirteçleri doğrular ; kimlik veya erişim belirteçleri isteyemez.

İlgilendiğiniz platformun sekmesini seçin:

İstemci gizli dizileri veya istemci sertifikaları

Web uygulamanızın artık aşağı akış web API'sini çağırdığını göz önünde bulundurarak, appsettings.json dosyasında bir istemci gizli dizisi veya istemci sertifikası sağlayın. Şunları belirten bir bölüm de ekleyebilirsiniz:

Aşağı akış web API'sinin URL'si
API'yi çağırmak için gereken kapsamlar

Aşağıdaki örnekte, GraphBeta bölümü bu ayarları belirtir.

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "ClientId": "[Enter_the_Application_Id_Here]",
    "TenantId": "common",

   // To call an API
   "ClientCredentials": [
    {
      "SourceType": "ClientSecret",
      "ClientSecret":"[Enter_the_Client_Secret_Here]"
    }
  ]
 },
 "GraphBeta": {
    "BaseUrl": "https://graph.microsoft.com/beta",
    "Scopes": ["user.read"]
    }
}

Not

Azure Kubernetes için iş yükü kimlik federasyonu gibi kimlik bilgisi olmayan bir çözüm de dahil olmak üzere bir istemci kimlik bilgileri koleksiyonu önerebilirsiniz. Microsoft.Identity.Web'in önceki sürümleri, istemci gizli dizisini "ClientCredentials" yerine tek bir "ClientSecret" özelliğinde ifade etti. Bu, geriye dönük uyumluluk için hala desteklenir, ancak hem "ClientSecret" özelliğini hem de "ClientCredentials" koleksiyonunu kullanamazsınız.

İstemci gizli dizisi yerine bir istemci sertifikası sağlayabilirsiniz. Aşağıdaki kod parçacığı, Azure Key Vault'ta depolanan bir sertifikanın kullanılmasını gösterir.

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "ClientId": "[Enter_the_Application_Id_Here]",
    "TenantId": "common",

   // To call an API
   "ClientCredentials": [
      {
        "SourceType": "KeyVault",
        "KeyVaultUrl": "https://msidentitywebsamples.vault.azure.net",
        "KeyVaultCertificateName": "MicrosoftIdentitySamplesCert"
      }
   ]
  },
  "GraphBeta": {
    "BaseUrl": "https://graph.microsoft.com/beta",
    "Scopes": ["user.read"]
  }
}

Uyarı

değerini bir dizi olarak değiştirmeyi Scopes unutursanız, kullanmayı IDownstreamApi denediğinizde kapsamlar null görünür ve aşağı akış API'sine anonim (kimliği doğrulanmamış) bir çağrı dener ve IDownstreamApi bu da ile 401/unauthenticatedsonuçlanır.

Microsoft.Identity.Web , sertifikaları hem yapılandırmaya hem de koda göre açıklamanın çeşitli yollarını sağlar. Ayrıntılar için bkz . Microsoft.Identity.Web - GitHub'da sertifikaları kullanma.

Startup.cs

Web uygulamanızın aşağı akış API'sine yönelik bir belirteç alması gerekir. satırının arkasına .AddMicrosoftIdentityWebApp(Configuration)ekleyerek .EnableTokenAcquisitionToCallDownstreamApi() bunu belirtirsiniz. Bu satır, IAuthorizationHeaderProvider denetleyicinizde ve sayfa eylemlerinizde kullanabileceğiniz hizmeti kullanıma sunar. Ancak, aşağıdaki iki seçenekte gördüğünüz gibi, daha basit bir şekilde yapılabilir. Ayrıca, Startup.cs'de bir .AddInMemoryTokenCaches()belirteç önbelleği uygulaması seçmeniz de gerekir:

using Microsoft.Identity.Web;

public class Startup
{
  // ...
  public void ConfigureServices(IServiceCollection services)
  {
  // ...
  services.AddAuthentication(OpenIdConnectDefaults.AuthenticationScheme)
          .AddMicrosoftIdentityWebApp(Configuration, "AzureAd")
            .EnableTokenAcquisitionToCallDownstreamApi(new string[]{"user.read" })
            .AddInMemoryTokenCaches();
   // ...
  }
  // ...
}

'a EnableTokenAcquisitionToCallDownstreamApi geçirilen kapsamlar isteğe bağlıdır ve web uygulamanızın oturum açarken kapsamları ve kullanıcının bu kapsamlara onayını istemesini sağlar. Kapsamları belirtmezseniz, Microsoft.Identity.Web artımlı bir onay deneyimi sağlar.

Microsoft.Identity.Web , belirteç almanıza gerek kalmadan bir web uygulamasından web API'sini çağırmak için iki mekanizma sunar. Seçtiğiniz seçenek, Microsoft Graph'ı mı yoksa başka bir API'yi mi çağırmak istediğinize bağlıdır.

1. Seçenek: Microsoft Graph'ı çağırma

Microsoft Graph'ı çağırmak istiyorsanız, Microsoft.Identity.Web API eylemlerinizde (Microsoft Graph SDK'sı tarafından kullanıma sunulan) doğrudan kullanmanızı GraphServiceClient sağlar. Microsoft Graph'ı kullanıma açmak için:

Projenize Microsoft.Identity.Web.GraphServiceClient NuGet paketini ekleyin.

Startup.cs dosyasına sonra .EnableTokenAcquisitionToCallDownstreamApi() ekleyin.AddMicrosoftGraph(). .AddMicrosoftGraph() birkaç geçersiz kılmaya sahiptir. Yapılandırma bölümünü parametre olarak alan geçersiz kılma kullanıldığında kod şu hale gelir:

using Microsoft.Identity.Web;

public class Startup
{
  // ...
  public void ConfigureServices(IServiceCollection services)
  {
  // ...
  services.AddAuthentication(OpenIdConnectDefaults.AuthenticationScheme)
          .AddMicrosoftIdentityWebApp(Configuration, "AzureAd")
            .EnableTokenAcquisitionToCallDownstreamApi(new string[]{"user.read" })
               .AddMicrosoftGraph(Configuration.GetSection("GraphBeta"))
            .AddInMemoryTokenCaches();
   // ...
  }
  // ...
}

Seçenek 2: Microsoft Graph dışında bir aşağı akış web API'sini çağırma

Microsoft Graph dışında bir API çağırmak istiyorsanız, Microsoft.Identity.Web API eylemlerinizde arabirimi kullanmanıza IDownstreamApi olanak tanır. Bu arabirimi kullanmak için:

Projenize Microsoft.Identity.Web.DownstreamApi NuGet paketini ekleyin.

Startup.cs dosyasına sonra .EnableTokenAcquisitionToCallDownstreamApi() ekleyin.AddDownstreamApi(). .AddDownstreamApi() iki bağımsız değişkeni vardır ve aşağıdaki kod parçacığında gösterilir:

Denetleyici eylemlerinizde karşılık gelen yapılandırmaya başvurmak için kullanılan bir hizmetin (API) adı
aşağı akış web API'sini çağırmak için kullanılan parametreleri temsil eden bir yapılandırma bölümü.

using Microsoft.Identity.Web;

public class Startup
{
  // ...
  public void ConfigureServices(IServiceCollection services)
  {
  // ...
  services.AddAuthentication(OpenIdConnectDefaults.AuthenticationScheme)
          .AddMicrosoftIdentityWebApp(Configuration, "AzureAd")
            .EnableTokenAcquisitionToCallDownstreamApi(new string[]{"user.read" })
               .AddDownstreamApi("MyApi", Configuration.GetSection("GraphBeta"))
            .AddInMemoryTokenCaches();
   // ...
  }
  // ...
}

Özet

Web API'lerinde olduğu gibi çeşitli belirteç önbelleği uygulamalarını seçebilirsiniz. Ayrıntılar için bkz . GitHub'da Microsoft.Identity.Web - Belirteç önbelleği serileştirmesi .

Aşağıdaki görüntüde Microsoft.Identity.Web'in çeşitli olasılıkları ve bunların Startup.cs dosyası üzerindeki etkisi gösterilmektedir:

Web API'sini çağırmak ve belirteç önbelleği uygulaması belirtmek için başlangıç noktası C S'deki hizmet yapılandırma seçeneklerini gösteren blok diyagramı

Not

Buradaki kod örneklerini tam olarak anlamak için ASP.NET Core temelleri ve özellikle bağımlılık ekleme ve seçenekleri hakkında bilgi sahibi olun.

İstemci gizli dizileri veya istemci sertifikaları

Aşağı akış web API'sinin URL'si
API'yi çağırmak için gereken kapsamlar

Aşağıdaki örnekte, GraphBeta bölümü bu ayarları belirtir.

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "ClientId": "[Enter_the_Application_Id_Here]",
    "TenantId": "common",

   // To call an API
   "ClientCredentials": [
    {
      "SourceType": "ClientSecret",
      "ClientSecret":"[Enter_the_Client_Secret_Here]"
    }
  ]
 },
 "GraphBeta": {
    "BaseUrl": "https://graph.microsoft.com/beta",
    "Scopes": ["user.read"]
    }
}

Not

İstemci gizli dizisi yerine bir istemci sertifikası sağlayabilirsiniz. Aşağıdaki kod parçacığı, Azure Key Vault'ta depolanan bir sertifikanın kullanılmasını gösterir.

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "ClientId": "[Enter_the_Application_Id_Here]",
    "TenantId": "common",

   // To call an API
   "ClientCredentials": [
      {
        "SourceType": "KeyVault",
        "KeyVaultUrl": "https://msidentitywebsamples.vault.azure.net",
        "KeyVaultCertificateName": "MicrosoftIdentitySamplesCert"
      }
   ]
  },
  "GraphBeta": {
    "BaseUrl": "https://graph.microsoft.com/beta",
    "Scopes": ["user.read"]
  }
}

Uyarı

Startup.Auth.cs

Web uygulamanızın aşağı akış API'sine yönelik bir belirteç alması gerekir. Microsoft.Identity.Web, bir web uygulamasından web API'sini çağırmak için iki mekanizma sağlar. Seçtiğiniz seçenek, Microsoft Graph'ı mı yoksa başka bir API'yi mi çağırmak istediğinize bağlıdır.

1. Seçenek: Microsoft Graph'ı çağırma

Projenize Microsoft.Identity.Web.GraphServiceClient NuGet paketini ekleyin.
Startup.Auth.cs dosyasında hizmet koleksiyonuna ekleyin.AddMicrosoftGraph(). .AddMicrosoftGraph() birkaç geçersiz kılmaya sahiptir. Yapılandırma bölümünü parametre olarak alan geçersiz kılma kullanıldığında kod şu hale gelir:

using Microsoft.Extensions.DependencyInjection;
using Microsoft.Identity.Client;
using Microsoft.Identity.Web;
using Microsoft.Identity.Web.OWIN;
using Microsoft.Identity.Web.TokenCacheProviders.InMemory;
using Microsoft.IdentityModel.Validators;
using Microsoft.Owin.Security;
using Microsoft.Owin.Security.Cookies;
using Owin;

namespace WebApp
{
    public partial class Startup
    {
        public void ConfigureAuth(IAppBuilder app)
        {
            app.SetDefaultSignInAsAuthenticationType(CookieAuthenticationDefaults.AuthenticationType);

            app.UseCookieAuthentication(new CookieAuthenticationOptions());

            // Get an TokenAcquirerFactory specialized for OWIN
            OwinTokenAcquirerFactory owinTokenAcquirerFactory = TokenAcquirerFactory.GetDefaultInstance<OwinTokenAcquirerFactory>();

            // Configure the web app.
            app.AddMicrosoftIdentityWebApp(owinTokenAcquirerFactory,
                                          updateOptions: options => {});

            // Add the services you need.
            owinTokenAcquirerFactory.Services
                .Configure<ConfidentialClientApplicationOptions>(options => 
                      { options.RedirectUri = "https://localhost:44326/"; })
                .AddMicrosoftGraph()
                .AddInMemoryTokenCaches();
            owinTokenAcquirerFactory.Build();
        }
    }
}

Seçenek 2: Microsoft Graph dışında bir aşağı akış web API'sini çağırma

Microsoft Graph dışında bir API çağırmak istiyorsanız, Microsoft.Identity.Web API eylemlerinizde arabirimi kullanmanıza IDownstreamApi olanak tanır. Bu arabirimi kullanmak için:

Projenize Microsoft.Identity.Web.DownstreamApi NuGet paketini ekleyin.
Startup.cs dosyasına sonra .EnableTokenAcquisitionToCallDownstreamApi() ekleyin.AddDownstreamApi(). .AddDownstreamApi() iki bağımsız değişkeni vardır:
- Hizmetin adı (api): Bu adı denetleyici eylemlerinizde ilgili yapılandırmaya başvurmak için kullanırsınız
- aşağı akış web API'sini çağırmak için kullanılan parametreleri temsil eden bir yapılandırma bölümü.

Kod şu şekildedir:

  using Microsoft.Extensions.DependencyInjection;
  using Microsoft.Identity.Client;
  using Microsoft.Identity.Web;
  using Microsoft.Identity.Web.OWIN;
  using Microsoft.Identity.Web.TokenCacheProviders.InMemory;
  using Microsoft.IdentityModel.Validators;
  using Microsoft.Owin.Security;
  using Microsoft.Owin.Security.Cookies;
  using Owin;

  namespace WebApp
  {
      public partial class Startup
      {
          public void ConfigureAuth(IAppBuilder app)
          {
              app.SetDefaultSignInAsAuthenticationType(CookieAuthenticationDefaults.AuthenticationType);

              app.UseCookieAuthentication(new CookieAuthenticationOptions());

              // Get a TokenAcquirerFactory specialized for OWIN.
              OwinTokenAcquirerFactory owinTokenAcquirerFactory = TokenAcquirerFactory.GetDefaultInstance<OwinTokenAcquirerFactory>();

              // Configure the web app.
              app.AddMicrosoftIdentityWebApp(owinTokenAcquirerFactory,
                                            updateOptions: options => {});

              // Add the services you need.
              owinTokenAcquirerFactory.Services
                  .Configure<ConfidentialClientApplicationOptions>(options => 
                        { options.RedirectUri = "https://localhost:44326/"; })
                  .AddDownstreamApi("Graph", owinTokenAcquirerFactory.Configuration.GetSection("GraphBeta"))
                  .AddInMemoryTokenCaches();
              owinTokenAcquirerFactory.Build();
          }
      }
  }

Özet

Çeşitli belirteç önbelleği uygulamaları seçebilirsiniz. Ayrıntılar için bkz . GitHub'da Microsoft.Identity.Web - Belirteç önbelleği serileştirmesi .

Aşağıdaki görüntüde Microsoft.Identity.Web'in çeşitli olasılıkları ve bunların Startup.cs dosyası üzerindeki etkisi gösterilmektedir:

Web API'sini çağırmak ve belirteç önbelleği uygulaması belirtmek için başlangıç noktası C S'deki hizmet yapılandırma seçeneklerini gösteren blok diyagramı

Not

Buradaki kod örneklerini tam olarak anlamak için ASP.NET Core temelleri ve özellikle bağımlılık ekleme ve seçenekleri hakkında bilgi sahibi olun.

Bu makaledeki kod örnekleri ve aşağıdakiler ASP.NET Web uygulaması örneğinden ayıklanır. Tam uygulama ayrıntıları için bu örneğe başvurmak isteyebilirsiniz.

Bu makaledeki kod örnekleri ve aşağıdakiler, MSAL Node kullanan bir web uygulaması örneği olan Microsoft Graph'ı çağıran Node.js & Express.js web uygulamasından ayıklanır.

Örnek şu anda MSAL Node'un yetkilendirme kodu URL'sini oluşturmasına izin verir ve Microsoft kimlik platformu için yetkilendirme uç noktasına gezintiyi işler. Bu, aşağıda gösterilmiştir:

/**
 * Prepares the auth code request parameters and initiates the first leg of auth code flow
 * @param req: Express request object
 * @param res: Express response object
 * @param next: Express next function
 * @param authCodeUrlRequestParams: parameters for requesting an auth code url
 * @param authCodeRequestParams: parameters for requesting tokens using auth code
 */
redirectToAuthCodeUrl(authCodeUrlRequestParams, authCodeRequestParams, msalInstance) {
    return async (req, res, next) => {
        // Generate PKCE Codes before starting the authorization flow
        const { verifier, challenge } = await this.cryptoProvider.generatePkceCodes();

        // Set generated PKCE codes and method as session vars
        req.session.pkceCodes = {
            challengeMethod: 'S256',
            verifier: verifier,
            challenge: challenge,
        };

        /**
         * By manipulating the request objects below before each request, we can obtain
         * auth artifacts with desired claims. For more information, visit:
         * https://azuread.github.io/microsoft-authentication-library-for-js/ref/modules/_azure_msal_node.html#authorizationurlrequest
         * https://azuread.github.io/microsoft-authentication-library-for-js/ref/modules/_azure_msal_node.html#authorizationcoderequest
         **/
        req.session.authCodeUrlRequest = {
            ...authCodeUrlRequestParams,
            responseMode: msal.ResponseMode.FORM_POST, // recommended for confidential clients
            codeChallenge: req.session.pkceCodes.challenge,
            codeChallengeMethod: req.session.pkceCodes.challengeMethod,
        };

        req.session.authCodeRequest = {
            ...authCodeRequestParams,
            code: '',
        };

        try {
            const authCodeUrlResponse = await msalInstance.getAuthCodeUrl(req.session.authCodeUrlRequest);
            res.redirect(authCodeUrlResponse);
        } catch (error) {
            next(error);
        }
    };
}

Yetkilendirme kodunu kullanan kod

Microsoft.Identity.Web doğru OpenID Bağlan ayarlarını yaparak, alınan kod olayına abone olarak ve kodu kullanarak kodunuzu basitleştirir. Yetkilendirme kodunu kullanmak için ek kod gerekmez. Bunun nasıl çalıştığı hakkında ayrıntılı bilgi için bkz . Microsoft.Identity.Web kaynak kodu .

AuthProvider sınıfında handleRedirect yöntemi, Microsoft Entra Id'den alınan yetkilendirme kodunu işler. Bu, aşağıda gösterilmiştir:

handleRedirect(options = {}) {
    return async (req, res, next) => {
        if (!req.body || !req.body.state) {
            return next(new Error('Error: response not found'));
        }

        const authCodeRequest = {
            ...req.session.authCodeRequest,
            code: req.body.code,
            codeVerifier: req.session.pkceCodes.verifier,
        };

        try {
            const msalInstance = this.getMsalInstance(this.msalConfig);

            if (req.session.tokenCache) {
                msalInstance.getTokenCache().deserialize(req.session.tokenCache);
            }

            const tokenResponse = await msalInstance.acquireTokenByCode(authCodeRequest, req.body);

            req.session.tokenCache = msalInstance.getTokenCache().serialize();
            req.session.idToken = tokenResponse.idToken;
            req.session.account = tokenResponse.account;
            req.session.isAuthenticated = true;

            const state = JSON.parse(this.cryptoProvider.base64Decode(req.body.state));
            res.redirect(state.successRedirect);
        } catch (error) {
            next(error);
        }
    }
}

Bkz . Kullanıcılarda oturum açma web uygulaması: Java örneğinin yetkilendirme kodunu nasıl aldığını anlamak için kod yapılandırması . Uygulama kodu aldıktan sonra AuthFilter.java#L51-L56:

AuthHelper.java#L67-L97 içindeki yöntemine AuthHelper.processAuthenticationCodeRedirect temsilciler.
getAuthResultByAuthCode çağrısı yapar.

class AuthHelper {
  // Code omitted
  void processAuthenticationCodeRedirect(HttpServletRequest httpRequest, String currentUri, String fullUrl)
            throws Throwable {

  // Code omitted
  AuthenticationResponse authResponse = AuthenticationResponseParser.parse(new URI(fullUrl), params);

  // Code omitted
  IAuthenticationResult result = getAuthResultByAuthCode(
                    httpRequest,
                    oidcResponse.getAuthorizationCode(),
                    currentUri);

// Code omitted
  }
}

getAuthResultByAuthCode yöntemi AuthHelper.java#L176 içinde tanımlanır. Bir MSAL ConfidentialClientApplicationoluşturur ve yetkilendirme kodundan oluşturulan ile AuthorizationCodeParameters çağrılaracquireToken().

   private IAuthenticationResult getAuthResultByAuthCode(
            HttpServletRequest httpServletRequest,
            AuthorizationCode authorizationCode,
            String currentUri) throws Throwable {

        IAuthenticationResult result;
        ConfidentialClientApplication app;
        try {
            app = createClientApplication();

            String authCode = authorizationCode.getValue();
            AuthorizationCodeParameters parameters = AuthorizationCodeParameters.builder(
                    authCode,
                    new URI(currentUri)).
                    build();

            Future<IAuthenticationResult> future = app.acquireToken(parameters);

            result = future.get();
        } catch (ExecutionException e) {
            throw e.getCause();
        }

        if (result == null) {
            throw new ServiceUnavailableException("authentication result was null");
        }

        SessionManagementHelper.storeTokenCacheInSession(httpServletRequest, app.tokenCache().serialize());

        return result;
    }

    private ConfidentialClientApplication createClientApplication() throws MalformedURLException {
        return ConfidentialClientApplication.builder(clientId, ClientCredentialFactory.create(clientSecret)).
                authority(authority).
                build();
    }

Bkz . Kullanıcılarda oturum açma web uygulaması: Python örneğinin yetkilendirme kodunu nasıl aldığını anlamak için kod yapılandırması .

Microsoft oturum açma ekranı, yetkilendirme kodunu uygulama kaydında belirtilen URL'ye /getAToken gönderir. Yol bu URL'yi auth_response işler, yetkilendirme kodunu işlemek için çağırır auth.complete_login ve ardından bir hata döndürür veya giriş sayfasına yönlendirilir.

@app.route(app_config.REDIRECT_PATH)
def auth_response():
    result = auth.complete_log_in(request.args)
    if "error" in result:
        return render_template("auth_error.html", result=result)
    return redirect(url_for("index"))

Bu kodun tam bağlamı için bkz app.py .

Gizli istemci uygulaması, istemci gizli dizisi yerine istemci sertifikası veya istemci onayı kullanarak kimliğini de kanıtlayabilir. İstemci onaylarının kullanımı, İstemci onayları bölümünde ayrıntılı olarak yer alan gelişmiş bir senaryodur.

Belirteç önbelleği

Önemli

Web uygulamaları veya web API'leri için belirteç önbelleği uygulaması, genellikle dosya tabanlı olan masaüstü uygulamaları için uygulamadan farklıdır. Güvenlik ve performans nedenleriyle, web uygulamaları ve web API'leri için kullanıcı hesabı başına bir belirteç önbelleği olduğundan emin olmak önemlidir. Her hesap için belirteç önbelleğini seri hale getirmeniz gerekir.

ASP.NET temel öğreticisi, uygulamanızın Startup.cs dosyasında belirteç önbelleği uygulamasına karar vermenize olanak sağlamak için bağımlılık eklemeyi kullanır. Microsoft.Identity.Web, Belirteç önbelleği serileştirmesi bölümünde açıklanan önceden oluşturulmuş belirteç önbelleği serileştiricileriyle birlikte gelir. İlginç bir olasılık ASP.NET Çekirdek dağıtılmış bellek önbelleklerini seçmektir:

// Use a distributed token cache by adding:
    services.AddMicrosoftIdentityWebAppAuthentication(Configuration, "AzureAd")
            .EnableTokenAcquisitionToCallDownstreamApi(
                initialScopes: new string[] { "user.read" })
            .AddDistributedTokenCaches();

// Then, choose your implementation.
// For instance, the distributed in-memory cache (not cleared when you stop the app):
services.AddDistributedMemoryCache();

// Or a Redis cache:
services.AddStackExchangeRedisCache(options =>
{
 options.Configuration = "localhost";
 options.InstanceName = "SampleInstance";
});

// Or even a SQL Server token cache:
services.AddDistributedSqlServerCache(options =>
{
 options.ConnectionString = _config["DistCache_ConnectionString"];
 options.SchemaName = "dbo";
 options.TableName = "TestCache";
});

Belirteç önbelleği sağlayıcıları hakkında ayrıntılı bilgi için Microsoft.Identity.Web'in Belirteç önbelleği serileştirme makalesine ve ASP.NET Core web uygulaması öğreticilerine de bakın | Belirteç, web uygulamaları öğreticisinin aşamasını önbelleğe alır.

ASP.NET öğreticisi, uygulamanızın Startup.Auth.cs dosyasında belirteç önbelleği uygulamasına karar vermenize olanak sağlamak için bağımlılık eklemeyi kullanır. Microsoft.Identity.Web, Belirteç önbelleği serileştirmesi bölümünde açıklanan önceden oluşturulmuş belirteç önbelleği serileştiricileriyle birlikte gelir. İlginç bir olasılık ASP.NET Çekirdek dağıtılmış bellek önbelleklerini seçmektir:

var services = owinTokenAcquirerFactory.Services;
// Use a distributed token cache by adding:
services.AddDistributedTokenCaches();

// Then, choose your implementation.
// For instance, the distributed in-memory cache (not cleared when you stop the app):
services.AddDistributedMemoryCache();

// Or a Redis cache:
services.AddStackExchangeRedisCache(options =>
{
 options.Configuration = "localhost";
 options.InstanceName = "SampleInstance";
});

// Or even a SQL Server token cache:
services.AddDistributedSqlServerCache(options =>
{
 options.ConnectionString = _config["DistCache_ConnectionString"];
 options.SchemaName = "dbo";
 options.TableName = "TestCache";
});

Belirteç önbelleği sağlayıcıları hakkında ayrıntılı bilgi için Microsoft.Identity.WebBelirteci önbelleği serileştirme makalesine ve ASP.NET Core web uygulaması öğreticilerine | bakın Belirteç, web uygulamasının öğreticisinin aşamasını önbelleğe alır.

Ayrıntılar için bkz. MSAL.NET için belirteç önbelleği serileştirme.

MSAL Java, belirteç önbelleğini seri hale getirmek ve seri durumdan çıkarmak için yöntemler sağlar. Java örneği, AuthHelper.java#L99-L122 içindeki yönteminde getAuthResultBySilentFlowgösterildiği gibi oturumdan serileştirmeyi işler:

IAuthenticationResult getAuthResultBySilentFlow(HttpServletRequest httpRequest, HttpServletResponse httpResponse)
      throws Throwable {

  IAuthenticationResult result =  SessionManagementHelper.getAuthSessionObject(httpRequest);

  IConfidentialClientApplication app = createClientApplication();

  Object tokenCache = httpRequest.getSession().getAttribute("token_cache");
  if (tokenCache != null) {
      app.tokenCache().deserialize(tokenCache.toString());
  }

  SilentParameters parameters = SilentParameters.builder(
          Collections.singleton("User.Read"),
          result.account()).build();

  CompletableFuture<IAuthenticationResult> future = app.acquireTokenSilently(parameters);
  IAuthenticationResult updatedResult = future.get();

  // Update session with latest token cache.
  SessionManagementHelper.storeTokenCacheInSession(httpRequest, app.tokenCache().serialize());

  return updatedResult;
}

Sınıfın SessionManagementHelper ayrıntıları Java için MSAL örneğinde sağlanır.

Node.js örnekte, belirteç önbelleğini depolamak için uygulama oturumu kullanılır. MSAL Düğümü önbellek yöntemleri kullanılarak, belirteç isteği yapılmadan önce oturumdaki belirteç önbelleği okunur ve belirteç isteği başarıyla tamamlandıktan sonra güncelleştirilir. Bu, aşağıda gösterilmiştir:

acquireToken(options = {}) {
    return async (req, res, next) => {
        try {
            const msalInstance = this.getMsalInstance(this.msalConfig);

            /**
             * If a token cache exists in the session, deserialize it and set it as the 
             * cache for the new MSAL CCA instance. For more, see: 
             * https://github.com/AzureAD/microsoft-authentication-library-for-js/blob/dev/lib/msal-node/docs/caching.md
             */
            if (req.session.tokenCache) {
                msalInstance.getTokenCache().deserialize(req.session.tokenCache);
            }

            const tokenResponse = await msalInstance.acquireTokenSilent({
                account: req.session.account,
                scopes: options.scopes || [],
            });

            /**
             * On successful token acquisition, write the updated token 
             * cache back to the session. For more, see: 
             * https://github.com/AzureAD/microsoft-authentication-library-for-js/blob/dev/lib/msal-node/docs/caching.md
             */
            req.session.tokenCache = msalInstance.getTokenCache().serialize();
            req.session.accessToken = tokenResponse.accessToken;
            req.session.idToken = tokenResponse.idToken;
            req.session.account = tokenResponse.account;

            res.redirect(options.successRedirect);
        } catch (error) {
            if (error instanceof msal.InteractionRequiredAuthError) {
                return this.login({
                    scopes: options.scopes || [],
                    redirectUri: options.redirectUri,
                    successRedirect: options.successRedirect || '/',
                })(req, res, next);
            }

            next(error);
        }
    };
}

Python örneğinde kimlik paketi, depolama için genel session nesneyi kullanarak belirteç önbelleğini üstlenir.

Flask, tanımlama bilgisinde depolanan oturumlar için yerleşik desteğe sahiptir, ancak kimlik tanımlama bilgilerinin uzunluğu nedeniyle örnek bunun yerine Flask-session paketini kullanır. Her şey app.py başlatılır:

import identity
import identity.web
import requests
from flask import Flask, redirect, render_template, request, session, url_for
from flask_session import Session

import app_config

app = Flask(__name__)
app.config.from_object(app_config)
Session(app)

auth = identity.web.Auth(
    session=session,
    authority=app.config["AUTHORITY"],
    client_id=app.config["CLIENT_ID"],
    client_credential=app.config["CLIENT_SECRET"],
)

içindeki app_config.pyayar nedeniyle SESSION_TYPE="filesystem" Flask-session paketi, yerel dosya sistemini kullanarak oturumları depolar.

Üretim için uygulamanızın birden çok örneğinde kalıcı olan ve "sqlachemy" veya "redis" gibi bir ayar kullanmanız gerekir.

Sonraki adımlar

Bu noktada, kullanıcı oturum açtığında belirteç, belirteç önbelleğinde depolanır. Şimdi web uygulamasının diğer bölümlerinde nasıl kullanıldığını görelim.

Bu senaryoda bir sonraki makale olan Genel oturum kapatmada hesapları önbellekten kaldırma makalesine geçin.

Web API'lerini çağıran bir web uygulaması: Kod yapılandırması

Web uygulamalarını destekleyen Microsoft kitaplıkları

İstemci gizli dizileri veya istemci sertifikaları

Startup.cs

1. Seçenek: Microsoft Graph'ı çağırma

Seçenek 2: Microsoft Graph dışında bir aşağı akış web API'sini çağırma

Özet

Yetkilendirme kodunu kullanan kod

Belirteç önbelleği

Sonraki adımlar

Ek kaynaklar